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

> ## Agent Instructions
> Bitnob API requests authenticate with an `X-Auth-Client` API key header against https://api.bitnob.com.
> Always use the sandbox environment for testing. Never put live API keys in sample code.
> Money amounts are integers in the smallest unit of the currency (satoshis for BTC, cents for fiat). Never use floats.
> Every state-changing request takes a client-supplied `reference` and must be treated as idempotent on retry.
> Quotes expire. Re-quote rather than reusing a stale quote id.

# Trade statuses and webhook events

> The order fields, status values, and webhook events the trading API returns, in one place to look up.

A single reference for the values the trading API returns. For the flow that produces them, see [How trading works](https://www.bitnob.dev/docs/trading/how-trading-works.md).

## Order fields

Returned by [Get order by id or reference](https://www.bitnob.dev/api-reference/trading/get-order-by-id-or-reference.md) and [List orders](https://www.bitnob.dev/api-reference/trading/list-orders.md).

| Field | Type | Description |
| - | - | - |
| `id` | string | Bitnob's order identifier. Accepted anywhere an order id is required. |
| `reference` | string | Your own identifier, supplied on submission. Also accepted for lookup on crypto-pair orders. |
| `base_currency` | string | The asset being bought or sold, for example `BTC`. |
| `quote_currency` | string | The asset it is priced in, for example `USDT`. |
| `side` | string | `BUY` or `SELL`. |
| `order_type` | string | `limit` for quote-backed crypto-pair orders, `market` for NGN orders. |
| `quantity` | string | The amount requested, as a decimal string. |
| `filled_quantity` | string | The amount actually executed. |
| `remaining_quantity` | string | Quantity still outstanding. `0` on a fully filled order. |
| `price` | string | The executed price, expressed as quote currency per unit of base. |
| `exchange` | string | Venue that executed the order. `internal` for Bitnob liquidity. |
| `status` | string | Order outcome. See below. |
| `created_at`, `updated_at` | string | RFC 3339 timestamps. |

> [!NOTE]
>
> Amounts and prices are decimal strings, not numbers. Parse them with a decimal type, never a float. See [Currencies and amounts](https://www.bitnob.dev/docs/getting-started/core-concepts-and-architecture/currencies-and-amounts.md).

## Order status values

| Status | Meaning | Terminal |
| - | - | - |
| `pending` | Accepted, not yet filled. | No |
| `filled` | The order executed in full. `remaining_quantity` is `0`. | Yes |
| `rejected` | The order did not execute. `filled_quantity` stays `0`. | Yes |
| `cancelled` | Canceled before fill. | Yes |
| `failed` | NGN orders only. The order did not execute. | Yes |

Treat only `filled` as success, and confirm from a lookup or a webhook rather than from the submission response. `side` is submitted in upper case (`BUY`, `SELL`) and may be echoed in lower case in some responses, so compare case-insensitively.

## Webhook events

Two events carry every trade outcome. Full payloads and the handler checklist are on [Receive trade webhooks](https://www.bitnob.dev/docs/trading/trade-webhooks.md).

| Event | Fires when |
| - | - |
| `trade.completed` | The trade executed and settled. |
| `trade.failed` | The trade failed: quote expiry, insufficient balance, or a system error. |

### Webhook payload fields

| Field | Description |
| - | - |
| `event` | The event name. Branch on this first. |
| `event_id` | Unique per delivery. Use it to de-duplicate retries. |
| `data.tradeId` | The executed trade. `null` on `trade.failed`, because no trade exists. |
| `data.reference` | Your reference, and your join key back to the submitted order. |
| `data.from`, `data.to` | The assets converted, in lower case. |
| `data.inputAmount`, `data.outputAmount` | Amounts in the smallest unit of each asset. |
| `data.rate` | The rate applied to this trade. |
| `data.status` | `completed` or `failed`. |
| `data.reason` | Present on failures, for example `Quote expired` or `Insufficient balance`. |
| `data.timestamp` | When the outcome occurred. |

> [!WARNING]
>
> `data.tradeId` is `null` on `trade.failed`. Key your records on `reference`, which is present on both events, or a failed trade cannot be matched to the order that produced it.

## Failure reasons

`reason` carries the cause on `trade.failed`. The two documented values are `Quote expired` and `Insufficient balance`. For how to respond to each, see [Handle trading failures](https://www.bitnob.dev/docs/trading/error-handling-patterns.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.