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

# GET /orderbook

> Order book depth for a single trading pair.

## Description

Returns the current order book for a single pair, split into `bids` and `asks` arrays.

## Parameters

<ParamField query="ticker_id" type="string" required>
  Pair identifier in `{base}_{target}` format, e.g. `TRX_USDT`. See [ticker\_id format](/reference/ticker-id-format).
</ParamField>

<ParamField query="depth" type="integer">
  Total order count across both sides. The response returns up to `floor(depth / 2)` levels on each side.

  * `depth=100` returns up to 50 bids and 50 asks
  * `depth=0` — or omitting the parameter — returns the full order book
  * Any positive integer is accepted; there is no fixed set of allowed values
</ParamField>

## Response

<ResponseField name="ticker_id" type="string" required>
  The requested pair identifier, echoed back.
</ResponseField>

<ResponseField name="timestamp" type="integer" required>
  Last order book update time, Unix epoch in milliseconds.
</ResponseField>

<ResponseField name="bids" type="array" required>
  Array of `[price, quantity]` tuples sorted by price **descending** (best bid first).

  * `price` is the bid price in target currency
  * `quantity` is the order size in base currency
</ResponseField>

<ResponseField name="asks" type="array" required>
  Array of `[price, quantity]` tuples sorted by price **ascending** (best ask first).

  * `price` is the ask price in target currency
  * `quantity` is the order size in base currency
</ResponseField>

## Example request

<CodeGroup>
  ```bash curl theme={null}
  curl "https://internal-api.binibit.com/api/marketdata/getcoingecko/orderbook?ticker_id=TRX_USDT&depth=100"
  ```

  ```javascript Node theme={null}
  const url = new URL(
    "https://internal-api.binibit.com/api/marketdata/getcoingecko/orderbook"
  );
  url.searchParams.set("ticker_id", "TRX_USDT");
  url.searchParams.set("depth", "100");
  const book = await fetch(url).then(r => r.json());
  ```

  ```python Python theme={null}
  import requests
  book = requests.get(
      "https://internal-api.binibit.com/api/marketdata/getcoingecko/orderbook",
      params={"ticker_id": "TRX_USDT", "depth": 100},
  ).json()
  ```
</CodeGroup>

## Example response

```json theme={null}
{
  "ticker_id": "TRX_USDT",
  "timestamp": 1777399660025,
  "bids": [
    [0.31970297, 554.73],
    [0.31969307, 4.43],
    [0.31968317, 111.41]
  ],
  "asks": [
    [0.3261391, 503.02],
    [0.3261694, 123.38],
    [0.3261795, 20.01]
  ]
}
```

## Computing spread

```javascript theme={null}
const bestBid = book.bids[0][0];
const bestAsk = book.asks[0][0];
const spread = bestAsk - bestBid;
const spreadPct = (spread / bestAsk) * 100;
console.log(`Spread: ${spread} (${spreadPct.toFixed(2)}%)`);
```

## Notes

<Note>
  * Order book snapshots are eventually consistent — a trade you observe in `/historical_trades` may take up to 1 second to be removed from the book.
  * For real-time order book streams, a WebSocket API is on the [roadmap](/introduction#roadmap) for v2.
  * The `quantity` is the **remaining** order size at that price level after partial fills.
</Note>

## Errors

| Code                | Cause                                       |
| ------------------- | ------------------------------------------- |
| `400 INVALID_PARAM` | `ticker_id` is missing or malformed.        |
| `404 NOT_FOUND`     | The ticker\_id is not a valid trading pair. |