# Events

TokenBot supports 27 event types across 5 domains.

## Event Payload Format

```json
{
  "event": "trade.filled",
  "event_id": "evt_abc123",
  "timestamp": "2026-02-20T12:00:00Z",
  "data": { ... }
}
```

## Trade Events

| Event             | Description                       |
| ----------------- | --------------------------------- |
| `trade.created`   | A new trade order has been placed |
| `trade.updated`   | Trade order details updated       |
| `trade.filled`    | Trade order fully filled          |
| `trade.closed`    | Trade position closed             |
| `trade.cancelled` | Trade order cancelled             |

**Example payload (`trade.filled`):**

```json
{
  "event": "trade.filled",
  "event_id": "evt_123",
  "timestamp": "2026-02-20T12:00:00Z",
  "data": {
    "id": "trd_abc123",
    "exchange_account_id": "exc_123",
    "strategy_id": "str_123",
    "trade_pair": "BTC/USDT",
    "side": "BUY",
    "type": "LIMIT",
    "price": 50000.00,
    "amount": 0.1,
    "fee": 0.05,
    "status": "FILLED",
    "filled_at": "2026-02-20T12:00:00Z"
  }
}
```

## Copier Events

| Event            | Description             |
| ---------------- | ----------------------- |
| `copier.created` | New copier created      |
| `copier.updated` | Copier settings updated |
| `copier.deleted` | Copier deleted          |
| `copier.started` | Copier activated        |
| `copier.stopped` | Copier deactivated      |

## Copy Trade Events

| Event            | Description                               |
| ---------------- | ----------------------------------------- |
| `copy.triggered` | Copy trade initiated from strategy signal |
| `copy.completed` | Copy trade successfully executed          |
| `copy.failed`    | Copy trade failed to execute              |

**Example payload (`copy.failed`):**

```json
{
  "event": "copy.failed",
  "event_id": "evt_456",
  "timestamp": "2026-02-20T12:01:00Z",
  "data": {
    "copier_id": "cop_123",
    "strategy_id": "str_123",
    "source_trade_id": "trd_abc123",
    "error": "Insufficient balance"
  }
}
```

## Strategy Events

| Event                  | Description               |
| ---------------------- | ------------------------- |
| `strategy.created`     | New strategy created      |
| `strategy.updated`     | Strategy settings updated |
| `strategy.deleted`     | Strategy deleted          |
| `strategy.activated`   | Strategy activated        |
| `strategy.deactivated` | Strategy deactivated      |

## Exchange Events

| Event                     | Description                                               |
| ------------------------- | --------------------------------------------------------- |
| `exchange.connected`      | Exchange account connected                                |
| `exchange.disconnected`   | Exchange account disconnected (e.g., invalid credentials) |
| `exchange.sync_completed` | Exchange balance sync completed                           |

## All Events Reference

Subscribe to all events with `["*"]` or pick specific ones:

```
trade.created, trade.updated, trade.filled, trade.closed, trade.cancelled,
copier.created, copier.updated, copier.deleted, copier.started, copier.stopped,
copy.triggered, copy.completed, copy.failed,
strategy.created, strategy.updated, strategy.deleted, strategy.activated, strategy.deactivated,
exchange.connected, exchange.disconnected, exchange.sync_completed
```

Total: **24 events** (3 not yet implemented: `trade.closed`, `strategy.activated`, `strategy.deactivated` are reserved for future use).