Bot Configuration Reference

This comprehensive guide covers all aspects of configuring custom bots, from basic metadata to advanced schema definitions.

Bot Configuration File (bot-config.yaml)

The bot-config.yaml file is the main configuration file that defines your bot's metadata, structure, and requirements.

Complete Structure

name: string # Required: Bot identifier
description: string # Required: Brief description
version: string # Required: Semantic version (e.g., "1.0.0")
author: string # Required: Author name or organization
type: string # Required: scheduled | realtime
runtime: string # Required: python3.11 | nodejs20

entrypoints: # Required: Entry point definitions
  bot: string # Required: Main bot file
  backtest: string # Optional: Backtest file

schema: # Required: Schema definitions
  bot: string # Required: Bot parameter schema file
  backtest: string # Optional: Backtest parameter schema file

readme: string # Required: Documentation file

metadata: # Optional: Additional metadata
  categories: [string] # Bot categories for organization
  instruments: [string] # Supported instruments (stocks, crypto, forex)
  exchanges: [string] # Supported exchanges
  tags: [string] # Searchable tags
  #... Additional metadata fields

Required Fields

Basic Information

name: momentum-trading-bot
description: 'A momentum-based trading strategy using technical indicators'
version: 1.2.0
author: TradingExperts
type: scheduled
runtime: python3.11
readme: README.md

Field Descriptions:

name: Unique identifier for your custom bot (lowercase, hyphens allowed)
description: Brief, clear description of what your bot does
version: Semantic versioning format (MAJOR.MINOR.PATCH)
author: Your name, organization, or handle
type: Execution model for your bot
runtime: Execution environment
readme: Path to a markdown file with detailed documentation

Entry Points

entrypoints:
  bot: main.py # Main trading logic
  backtest: backtest.py # Backtesting logic (optional)

Entry Point Types:

bot: Main execution entry point (required)
backtest: Backtesting entry point (recommended)
webhook: Webhook event handler (for event-driven bots)
analysis: Custom analysis functions
custom: Any additional entry points

Schema Definitions

schema:
  bot: bot-schema.json
  backtest: backtest-schema.json # Optional: if implementing backtesting

Each entry point should have a corresponding schema file defining its parameters.

Bot Types

Scheduled Bots

type: scheduled

Characteristics:

Execute on fixed schedules (cron expressions)
Suitable for: DCA strategies, portfolio rebalancing, periodic analysis
Execution: Single run per trigger
State: Stateless between executions

Use Cases:

Daily portfolio rebalancing
Weekly DCA purchases
End-of-day analysis
Monthly performance reports

Realtime Bots

type: realtime

Characteristics:

Run continuously, processing live data
Execution: Continuous loop
State: Maintains state across iterations

Use Cases:

Grid trading strategies
Market making
Arbitrage detection
Scalping

Runtime Environments

Python 3.11

runtime: python3.11

Benefits:

Extensive trading libraries (ccxt, pandas, numpy, scikit-learn)
Machine learning capabilities
Scientific computing ecosystem
Popular in quantitative finance

Dependency Management:

Use requirements.txt for dependencies
Automatic Docker-based vendoring
Support for compiled packages

Node.js 20

runtime: nodejs20

Benefits:

Excellent async/await support
Large npm ecosystem
Good web3 support for crypto bots

Metadata Configuration

Metadata provides additional context for your bot, improving discoverability and organization in the marketplace.

Instruments

metadata:
  instruments:
    - crypto # Cryptocurrencies
    - stocks # Stock markets
    - forex # Foreign exchange
    - commodities # Commodity markets
    - options # Options trading
    - futures # Futures contracts

Exchanges

metadata:
  exchanges:
    - binance # Binance
    - coinbase # Coinbase Pro
    - kraken # Kraken
    - ftx # FTX
    - bitmex # BitMEX
    - interactive-brokers # Interactive Brokers

Risk and Complexity

metadata:
  risk_level: medium # low | medium | high
  complexity: intermediate # beginner | intermediate | advanced
  min_capital: 1000 # Minimum recommended capital ($)
  max_capital: 100000 # Maximum recommended capital ($)

JSON Schema Configuration

JSON schemas define the parameters your bot accepts and validate user inputs.

Bot Schema (bot-schema.json)

Basic Structure

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Bot Configuration",
  "description": "Configuration parameters for the trading bot",
  "properties": {
    // Parameter definitions
  },
  "required": ["symbol", "api_key"],
  "additionalProperties": false
}

For more information on JSON Schema, see the JSON Schema documentation.

Backtest Schema Example (backtest-schema.json)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Backtest Configuration",
  "properties": {
    "start_date": {
      "type": "string",
      "format": "date",
      "description": "Backtest start date (YYYY-MM-DD)"
    },
    "end_date": {
      "type": "string",
      "format": "date",
      "description": "Backtest end date (YYYY-MM-DD)"
    },
    "initial_balance": {
      "type": "number",
      "minimum": 0,
      "default": 10000,
      "description": "Starting balance for backtest"
    },
    "commission": {
      "type": "number",
      "minimum": 0,
      "maximum": 0.01,
      "default": 0.001,
      "description": "Trading commission rate (0.001 = 0.1%)"
    },
    "slippage": {
      "type": "number",
      "minimum": 0,
      "maximum": 0.01,
      "default": 0.0005,
      "description": "Slippage rate for realistic execution"
    }
  },
  "required": ["start_date", "end_date"],
  "additionalProperties": false
}

Validation and Testing

JSON Schema Validation

# Validate schema files
jsonschema --instance config.json --schema bot-schema.json

YAML Configuration Validation

# Validate YAML configuration files
python -c "import yaml; yaml.safe_load(open('bot-config.yaml'))"

# Or use yq for more detailed validation
yq eval '.' bot-config.yaml > /dev/null

Debugging Tips

Use Validation Tools: Validate schemas and configurations early
Test Incrementally: Test each component individually
Check Examples: Compare with working examples
Read Error Messages: Pay attention to specific validation errors
Use the CLI: Leverage CLI validation commands

Docs

Configuration