Traders

Overview

Traders are automated trading bots that execute strategies on connected exchanges. Each trader runs as an isolated container (pod) with its own configuration, API server, and webhook system.

Trader Lifecycle

Create an empty trader

Creates a trader with sensible defaults: dry_run: true, API server enabled, stressShield active.

Assign exchange, strategy, and pair handling

Patch with exchangeId, strategyId, handling (pair list method), and plugins.

Start the bot

Patch with running: true. A container (pod) is spawned and begins trading.

Monitor and control

Use pod API commands (ping, status, balance, profit, etc.) to manage the running bot.

Step 1: Create Trader

curl -X POST https://api.cryptorobot.ai/traders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{
  "_id": "685c3a...",
  "userId": "682e0a...",
  "name": "Trader 1",
  "dry_run": true,
  "dry_run_wallet": 10000,
  "stake_currency": "USDT",
  "stake_amount": "unlimited",
  "fiat_display_currency": "USD",
  "cancel_open_orders_on_exit": true,
  "unfilledtimeout": { "entry": 10, "exit": 10 },
  "stressShield": { "enabled": true },
  "webhook": { "enabled": true, "format": "json", "url": "..." },
  "api_server": {
    "enabled": true,
    "listen_ip_address": "0.0.0.0",
    "listen_port": 8080,
    "verbosity": "error",
    "jwt_secret_key": "...",
    "username": "...",
    "password": "..."
  },
  "createdAt": "2024-01-15T10:00:00.000Z",
  "updatedAt": "2024-01-15T10:00:00.000Z"
}

Step 2: Configure Trader

Assign an exchange, strategy, pair handling method, and plugins:

curl -X PATCH https://api.cryptorobot.ai/traders/685c3a... \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "exchangeId": "683a1f...",
    "strategyId": "684b2f...",
    "handling": "VolumePairList",
    "plugins": {
      "sortByPerformance": true,
      "ignoreLowValue": true,
      "removeRecentlyListed": true
    }
  }'

Response

{
  "_id": "685c3a...",
  "exchangeId": "683a1f...",
  "strategyId": "684b2f...",
  "exchange": {
    "_id": "683a1f...",
    "which": "binance",
    "configured": true
  },
  "strategy": {
    "_id": "684b2f...",
    "name": "BTC Momentum",
    "templateId": "tmpl-1",
    "configured": true
  },
  "pairlists": [
    { "method": "VolumePairList", "number_assets": 50, "sort_key": "quoteVolume", "refresh_period": 10800 },
    { "method": "AgeFilter", "min_days_listed": 30 },
    { "method": "PrecisionFilter" },
    { "method": "PerformanceFilter" }
  ],
  "webhook": {
    "enabled": true,
    "format": "json",
    "webhookstatus": { "event": "status" },
    "strategy_msg": { "event": "strategy_msg", "traderId": "685c3a...", "userId": "682e0a...", "msg": "{msg}" }
  }
}

Pair Handling Methods

Method	Description
`VolumePairList`	Select pairs by trading volume (default: top 50)
`StaticPairList`	Use exchange whitelist as fixed pair list

Plugins

Plugin	Description
`sortByPerformance`	Sort pairs by recent trade performance
`ignoreLowValue`	Skip pairs with very low value
`removeRecentlyListed`	Filter out newly listed pairs (< 30 days)

Step 3: Start Trading

curl -X PATCH https://api.cryptorobot.ai/traders/685c3a... \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"running": true}'

Response

{
  "_id": "685c3a...",
  "running": true,
  "pod": {
    "Id": "container-abc123",
    "State": {
      "Status": "running",
      "Running": true,
      "Paused": false,
      "Restarting": false,
      "StartedAt": "2024-01-15T10:05:00.000Z"
    },
    "Created": "2024-01-15T10:04:58.000Z"
  }
}

Pod Commands

Once running, send commands to the trader’s pod via the API:

curl -X POST https://api.cryptorobot.ai/traders/pods/api \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"traderId": "685c3a...", "action": "status"}'

Available Commands

Action	Description
`ping`	Check if pod is responsive (returns `pong`)
`start`	Resume trading
`stop`	Pause trading (keeps pod running)
`status`	Get current trading status
`balance`	Get account balance
`profit`	Get profit summary
`daily`	Get daily profit report
`performance`	Get pair performance stats
`trades`	List recent trades
`whitelist`	Get active whitelist
`blacklist`	Get active blacklist
`locks`	Get pair locks
`available_pairs`	List available trading pairs
`logs`	Get bot logs
`reload_config`	Hot-reload configuration
`forcesell`	Force close a position

Example: Check Profit

curl -X POST https://api.cryptorobot.ai/traders/pods/api \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"traderId": "685c3a...", "action": "profit"}'

Response

{
  "_id": "...",
  "traderId": "685c3a...",
  "action": "profit",
  "result": {
    "profit_closed_coin": 0.0123,
    "profit_closed_percent": 1.23,
    "profit_all_coin": 0.0456,
    "profit_all_percent": 4.56
  }
}

Stop Trading

curl -X PATCH https://api.cryptorobot.ai/traders/685c3a... \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"running": false}'

Pod Events (Webhooks)

The trader pod sends real-time events via webhooks. Query events for a trader:

curl "https://api.cryptorobot.ai/traders/pods/events?traderId=685c3a...&$sort[createdAt]=-1&$limit=10" \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "data": [
    {
      "traderId": "685c3a...",
      "event": "status",
      "status": "running",
      "createdAt": "2024-01-15T10:05:05.000Z"
    }
  ]
}

Stress Shield

The stressShield feature monitors market stress signals and can automatically pause trading during high-volatility events:

curl -X PATCH https://api.cryptorobot.ai/traders/685c3a... \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"stressShield": {"enabled": true}}'

When enabled, the trader receives strategy_msg webhooks from the stress monitoring system.

Key Fields

Field	Type	Description
`dry_run`	boolean	Paper trading mode (default: `true`)
`dry_run_wallet`	number	Virtual wallet size for paper trading
`stake_currency`	string	Quote currency for trading (e.g. `USDT`)
`stake_amount`	string/number	Amount per trade (`"unlimited"` or fixed amount)
`running`	boolean	Whether the bot pod is active
`exchangeId`	string	Connected exchange ID
`strategyId`	string	Active strategy ID
`handling`	string	Pair selection method
`plugins`	object	Active pair filter plugins
`pairlists`	array	Generated pair list pipeline
`pod`	object	Container state (when running)
`stressShield`	object	Market stress protection config
`webhook`	object	Webhook configuration for pod events
`api_server`	object	Pod API server configuration
`unfilledtimeout`	object	Timeout for unfilled orders `{entry, exit}`

Getting Started

Authentication

Core Concepts

Overview

Trader Lifecycle

Step 1: Create Trader

Step 2: Configure Trader

Pair Handling Methods

Plugins

Step 3: Start Trading

Pod Commands

Available Commands

Example: Check Profit

Stop Trading

Pod Events (Webhooks)

Stress Shield

Key Fields

​Overview

​Trader Lifecycle

​Step 1: Create Trader

​Step 2: Configure Trader

​Pair Handling Methods

​Plugins

​Step 3: Start Trading

​Pod Commands

​Available Commands

​Example: Check Profit

​Stop Trading

​Pod Events (Webhooks)

​Stress Shield

​Key Fields

Overview

Trader Lifecycle

Step 1: Create Trader

Step 2: Configure Trader

Pair Handling Methods

Plugins

Step 3: Start Trading

Pod Commands

Available Commands

Example: Check Profit

Stop Trading

Pod Events (Webhooks)

Stress Shield

Key Fields