> ## Documentation Index
> Fetch the complete documentation index at: https://cryptorobot.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Traders

> Deploy and manage automated trading bots

## 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.

```mermaid theme={null}
graph LR
    Create[Create Trader] --> Config[Configure]
    Config --> Start[Start Pod]
    Start --> Monitor[Monitor & Commands]
    Monitor --> Stop[Stop]
```

## Trader Lifecycle

<Steps>
  <Step title="Create an empty trader">
    Creates a trader with sensible defaults: `dry_run: true`, API server enabled, `stressShield` active.
  </Step>

  <Step title="Assign exchange, strategy, and pair handling">
    Patch with `exchangeId`, `strategyId`, `handling` (pair list method), and `plugins`.
  </Step>

  <Step title="Start the bot">
    Patch with `running: true`. A container (pod) is spawned and begins trading.
  </Step>

  <Step title="Monitor and control">
    Use pod API commands (`ping`, `status`, `balance`, `profit`, etc.) to manage the running bot.
  </Step>
</Steps>

## Step 1: Create Trader

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

```json Response theme={null}
{
  "_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:

```bash theme={null}
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
    }
  }'
```

```json Response theme={null}
{
  "_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

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

```json Response theme={null}
{
  "_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:

```bash theme={null}
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

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

```json Response theme={null}
{
  "_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

```bash theme={null}
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:

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

```json Response theme={null}
{
  "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:

```bash theme={null}
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}`      |