> For the complete documentation index, see [llms.txt](https://docs.tokenbot.com/home/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tokenbot.com/home/api-docs/webhooks/events.md).

# Events

TokenBot defines **46 event types** across 12 families. The canonical list lives in the shared `@tokenbot-org/data-models` package (the `WebhookEvent` enum). You can subscribe to any subset of these (up to 20 events per webhook), or to all of them with `["*"]`.

> Not every event is emitted yet — the enum is the full registrable set. Trade, copier, copy, strategy, exchange, reward, and withdrawal events are the most commonly fired today.

## Event Payload Format

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

Each delivery also carries `X-TokenBot-Event` and `X-TokenBot-Delivery-Id` headers (see [Security](/home/api-docs/webhooks/security.md)).

## Trade Events

| Event             | Description                          |
| ----------------- | ------------------------------------ |
| `trade.created`   | A new trade order has been placed    |
| `trade.updated`   | Trade order details updated          |
| `trade.executed`  | Trade order executed/filled          |
| `trade.filled`    | Deprecated alias of `trade.executed` |
| `trade.cancelled` | Trade order cancelled                |
| `trade.failed`    | Trade order failed                   |
| `trade.closed`    | Trade position closed                |

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

```json
{
  "event": "trade.executed",
  "event_id": "evt_123",
  "timestamp": "2026-06-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",
    "executed_at": "2026-06-20T12:00:00Z"
  }
}
```

## Position Events

| Event             | Description           |
| ----------------- | --------------------- |
| `position.opened` | A position was opened |
| `position.closed` | A position was closed |

## Strategy Events

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

## Copier Events

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

## Copy Events

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

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

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

## Exchange Events

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

## Alert Events

| Event                         | Description                       |
| ----------------------------- | --------------------------------- |
| `alert.triggered`             | A configured alert fired          |
| `alert.price_reached`         | A price threshold was reached     |
| `alert.volume_spike`          | A volume spike was detected       |
| `alert.drawdown_exceeded`     | A drawdown threshold was exceeded |
| `alert.profit_target_reached` | A profit target was reached       |

## User Events

| Event            | Description          |
| ---------------- | -------------------- |
| `user.created`   | A user was created   |
| `user.updated`   | A user was updated   |
| `user.verified`  | A user was verified  |
| `user.suspended` | A user was suspended |
| `user.deleted`   | A user was deleted   |

## Account Events

| Event              | Description             |
| ------------------ | ----------------------- |
| `account.created`  | An account was created  |
| `account.verified` | An account was verified |

## Reward Events

| Event           | Description                  |
| --------------- | ---------------------------- |
| `reward.earned` | Reward points / $TBOT earned |

## Withdrawal Events

| Event                  | Description                |
| ---------------------- | -------------------------- |
| `withdrawal.created`   | A withdrawal was requested |
| `withdrawal.completed` | A withdrawal completed     |

## System Events

| Event                | Description                     |
| -------------------- | ------------------------------- |
| `system.maintenance` | Maintenance window notification |
| `system.update`      | Platform update notification    |

## Subscribing

Subscribe to specific events or use `["*"]` for all:

```json
{
  "url": "https://your-server.com/webhooks",
  "events": ["trade.executed", "copy.failed", "copier.started"]
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.tokenbot.com/home/api-docs/webhooks/events.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.