> ## 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 has two APIs. The Business API (payouts, cards, trading, virtual accounts, stablecoin and bitcoin transfers) is at https://api.bitnob.com. The Enterprise API (non-custodial wallets) is at https://api.platform.bitnob.com.
> Business API auth: sign every request with HMAC-SHA256 and send four headers: `X-Auth-Client` (your client ID), `X-Auth-Timestamp` (Unix seconds), `X-Auth-Nonce` (16 random bytes, hex), and `X-Auth-Signature`, the hex HMAC-SHA256 of `CLIENT_ID:TIMESTAMP:NONCE:BODY` keyed with your client secret. BODY is the exact request body string you send, or an empty string. A missing header, a bad signature, or a timestamp more than about 5 minutes off returns `401`.
> Enterprise API auth: send your key in the `X-API-Key` header. Write requests such as creating a transaction also need an `Idempotency-Key` header, or they fail with `idempotency_key_required` before anything happens.
> Sandbox and production share the Business API base URL. The credentials you sign with select the environment, and `GET /api/whoami` returns it in `data.environment`. Use sandbox credentials in sample code and tests, and never put live credentials in code.
> Amounts are strings unless stated otherwise. Never parse them into floats. Balances, transactions, withdrawals (`POST /api/withdrawals`) and virtual accounts use integer strings in the smallest unit: satoshis for BTC, 6 decimals for USDT and USDC, kobo for NGN, and cents for KES and UGX (100 is 1 KES or 1 UGX). A mobile money collection takes `amount` as a JSON integer in cents.
> Payouts and trading use decimal strings in major units: a payout quote `amount` of `"1"` is 1 USDT, and a trading `quantity` of `"0.0001"` is 0.0001 BTC. Payout responses also carry `cent_amount`, the settlement amount in minor units.
> Card amounts are micro-units (1 USD = 1,000,000). Send them as JSON integers. Card responses return them as integer strings, and card webhooks as integers.
> Generate a unique `reference` for each money movement before the first attempt, and reuse it on retries. A reused reference returns `409` on payout quotes (`ALREADY_EXISTS`), withdrawals (`DUPLICATE_KEY_ERROR`) and card creation (`ALREADY_EXISTS`). It returns the existing record on NGN-pair trading orders, NGN virtual accounts and active mobile money collections. On a mobile money collection that has closed or failed it returns `409` `DUPLICATE_REFERENCE`. It isn't checked on crypto-pair trading orders, so look the order up with `GET /api/trading/orders/{reference}` before resending.
> Quotes expire at `expires_at`; read it from the response instead of assuming a window. An expired trading quote returns `422` `PRECONDITION_FAILED`, and an expired payout quote returns `400` `VALIDATION_ERROR`. Create a new quote rather than retrying. A payout quote can be initialized once, and a trading quote is consumed by the order that fills it.
> Webhooks: verify the `x-bitnob-signature` header, the hex HMAC-SHA512 of the raw request body keyed with your webhook secret, before parsing JSON. Compare in constant time and de-duplicate on `event_id`. A successful API response means accepted: confirm the outcome from the webhook, such as `payouts.withdrawal.success`.
> Errors return `status`, `code` and `detail`. Branch on `code`, never on `detail`. Since the November 5, 2026 response format change, each company gets either the current or the new error codes until its cutoff date, so handle both: `PROVIDER_ERROR` or `PROCESSING_ERROR`, and `BVN_PROVIDER_UNAVAILABLE` or `BVN_VERIFICATION_UNAVAILABLE`. A body that fails to parse returns `{"error": {"code": "BAD_REQUEST"}}`.

# Track orders and history

> Check the state of a single trade and page through past trades for reconciliation.

The Trade Status & History endpoints allow you to:

* Fetch a single trade by ID or reference
* List crypto-pair trades across your account
* Monitor conversion volumes, timestamps, and trade outcomes
* Power your ledger, dashboards, and audit flows

## Retrieve one order

Full reference: [Get Order By ID](https://www.bitnob.dev/api-reference/trading/get-order-by-id-or-reference.md).

```bash theme={null}
GET /api/trading/orders/:id
```

### Path parameter

| Parameter | Type | Required | Description |
| - | - | - | - |
| id | string | Yes | Order ID, or your `reference` for a crypto-pair order |

Use the order `id` for any pair. Lookup by your own `reference` works for crypto-pair orders only; an NGN reference returns `400` `invalid id`.

### Example request

```bash theme={null}
curl --location 'https://api.bitnob.com/api/trading/orders/4ac59dd0-3c25-43c7-8e51-2ed020149e1b' \
--header 'Content-Type: application/json' \
--header 'x-auth-client: CLIENT_ID' \
--header 'x-auth-timestamp: TIMESTAMP' \
--header 'x-auth-nonce: NONCE' \
--header 'x-auth-signature: SIGNATURE'
```

### Example response

```json theme={null}
{
    "success": true,
    "message": "Order retrieved successfully",
    "data": {
        "order": {
            "id": "4ac59dd0-3c25-43c7-8e51-2ed020149e1b",
            "base_currency": "USDC",
            "quote_currency": "USDT",
            "side": "SELL",
            "order_type": "limit",
            "quantity": "10.00000000",
            "price": "0.99725063",
            "status": "filled",
            "exchange": "internal",
            "created_at": "2025-12-14T11:40:53.802259000Z",
            "updated_at": "2025-12-14T11:40:55.216095000Z",
            "filled_quantity": "10.00000000",
            "remaining_quantity": "0"
        }
    },
    "metadata": {
        "request_id": "trading_req_019b219e-659a-7870-b44b-71dd179c2362"
    },
    "timestamp": "2025-12-15T10:46:27.59472953Z"
}
```

## List orders

Full reference: [Get Orders](https://www.bitnob.dev/api-reference/trading/list-orders.md). The list returns crypto-pair orders only. NGN trades aren't included, so fetch those one at a time by ID with [Get Order By ID](https://www.bitnob.dev/api-reference/trading/get-order-by-id-or-reference.md).

```bash theme={null}
GET /api/trading/orders
```

### Filters

Filters go in a JSON request body, not the query string. Query parameters are ignored. Every filter is optional, and a request without a body lists all orders.

| Field | Type | Required | Description |
| - | - | - | - |
| status | string | No | Filter by order status: `pending`, `filled`, `rejected`, or `cancelled`. |
| base\_currency | string | No | Filter by base currency, for example `BTC`. |
| quote\_currency | string | No | Filter by quote currency, for example `USDT`. |
| limit | integer | No | Maximum number of orders to return. |

Sign the body like any other request body. The response carries `total_count`, `has_more`, and `next_cursor` alongside the `orders` array.

### Example request

```bash theme={null}
curl --location --request GET 'https://api.bitnob.com/api/trading/orders' \
--header 'Content-Type: application/json' \
--header 'x-auth-client: CLIENT_ID' \
--header 'x-auth-timestamp: TIMESTAMP' \
--header 'x-auth-nonce: NONCE' \
--header 'x-auth-signature: SIGNATURE' \
--data '{"status":"filled","limit":20}'
```

### Example response

```json theme={null}
{
    "success": true,
    "message": "Orders retrieved successfully",
    "data": {
        "orders": [
            {
                "id": "9671943f-43ef-43b3-b435-1441280d2a43",
                "base_currency": "BTC",
                "quote_currency": "USDT",
                "side": "BUY",
                "order_type": "limit",
                "quantity": "0.00002000",
                "price": "83125.17242500",
                "status": "filled",
                "created_at": "2026-10-08T10:17:46.195624000Z",
                "updated_at": "2026-10-08T10:17:47.571335000Z",
                "filled_quantity": "0.00002000",
                "remaining_quantity": "0",
                "quote_id": "50a8d856-af0f-45a1-b246-7532fca46f82",
                "reference": "order-1781868270"
            }
        ],
        "total_count": "15",
        "has_more": false,
        "next_cursor": ""
    },
    "timestamp": "2026-10-20T12:27:30.055875261Z"
}
```

| Field | Meaning |
| - | - |
| `total_count` | Number of orders that match, as a string. |
| `has_more` | `true` when there are more orders after this page. |
| `next_cursor` | Cursor for the next page. Empty when `has_more` is `false`. |

## Order statuses

| Status | Meaning |
| - | - |
| `pending` | Accepted, not yet filled. |
| `filled` | Executed completely. The terminal success state. |
| `rejected` | Not executed. `filled_quantity` stays `0`. |
| `cancelled` | Canceled before fill via [Cancel order](https://www.bitnob.dev/api-reference/trading/cancel-order.md). |
| `failed` | NGN orders only. Not executed. `filled_quantity` stays `0`. |

## What to build on it

Powering ledger UIs or admin dashboards with completed trade data

Matching internal accounting and reconciliation jobs

Investigating failed trades by reference ID via [Get Order By ID](https://www.bitnob.dev/api-reference/trading/get-order-by-id-or-reference.md)

Generating usage-based analytics or reporting


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