> For the complete documentation index, see [llms.txt](https://docs.bbx.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bbx.com/bbx-dex-public-api/coingecko-integration/order-book.md).

# Order Book

Returns the current order-book depth for a specified **BBX DEX** cryptocurrency perpetual futures market.

The response contains separate `bids` and `asks` arrays. Each price level is represented as a `[price, quantity]` pair, with both values returned as strings.

***

### Endpoint

```http
GET /fapi/market/v1/public/coingecko/orderbook
```

### Full URL

```
https://dex.bbx.com/fapi/market/v1/public/coingecko/orderbook
```

***

### Authentication

No authentication is required.

The endpoint is publicly accessible and does not require:

* An API key
* A request signature
* Login credentials
* An authentication token
* A custom request header

***

### Query Parameters

| Parameter   | Type    | Required | Description                                                         |
| ----------- | ------- | -------: | ------------------------------------------------------------------- |
| `ticker_id` | string  |      Yes | Contract identifier in `BASE-TARGET` format, for example `BTC-USDT` |
| `depth`     | integer |       No | Total requested order-book levels across the bid and ask sides      |

***

### Pair Naming

The `ticker_id` must use the following format:

```
BASE-TARGET
```

Examples:

```
BTC-USDT
ETH-USDT
SOL-USDT
```

***

### Depth Rules

The `depth` parameter represents the total requested number of levels across both sides of the order book.

Examples:

| Requested depth | Maximum bid levels | Maximum ask levels |
| --------------: | -----------------: | -----------------: |
|           `100` |                 50 |                 50 |
|           `200` |                100 |                100 |

For odd depth values, the requested depth is divided between both sides and rounded up where applicable.

If `depth` is omitted or set to `0`, the endpoint returns the maximum available depth, subject to a maximum of 500 levels per side.

Values greater than or equal to `1000` are treated as a request for the maximum available depth.

A negative `depth` value returns an `invalid_depth` error.

***

### Example Request

```bash
curl -s \
  'https://dex.bbx.com/fapi/market/v1/public/coingecko/orderbook?ticker_id=BTC-USDT&depth=200'
```

***

### Example Response

```json
{
  "ticker_id": "BTC-USDT",
  "timestamp": 1721548812345,
  "bids": [
    ["67249.8", "0.512"],
    ["67249.5", "1.203"]
  ],
  "asks": [
    ["67251.2", "0.877"],
    ["67251.9", "2.014"]
  ]
}
```

> The values shown above are illustrative. Live responses contain current BBX market data.

***

### Response Fields

| Field       | Type    | Requirement | Description                                                |
| ----------- | ------- | ----------- | ---------------------------------------------------------- |
| `ticker_id` | string  | Mandatory   | Contract identifier in `BASE-TARGET` format                |
| `timestamp` | integer | Recommended | Order-book update time as a Unix timestamp in milliseconds |
| `bids`      | array   | Mandatory   | Bid levels represented as `[price, quantity]` string pairs |
| `asks`      | array   | Mandatory   | Ask levels represented as `[price, quantity]` string pairs |

***

### Order Sorting

Bid levels are sorted from the highest price to the lowest price.

Ask levels are sorted from the lowest price to the highest price.

Each price level is represented as:

```json
["price", "quantity"]
```

For example:

```json
["67249.8", "0.512"]
```

In this example:

* `67249.8` is the price
* `0.512` is the quantity available at that price level

***

### Timestamp Unit

The `timestamp` field is returned as a Unix timestamp in milliseconds.

Example:

```
1721548812345
```

***

### Empty Order Books

If order-book data is temporarily unavailable, including for a newly listed contract whose depth cache has not yet been populated, the endpoint returns HTTP `200` with empty `bids` and `asks` arrays.

Example:

```json
{
  "ticker_id": "BTC-USDT",
  "timestamp": 1721548812345,
  "bids": [],
  "asks": []
}
```

The endpoint does not return an empty response body for this condition.

***

### Invalid Requests

An unknown, disabled, or unsupported contract identifier returns an `invalid_symbol` error.

A negative `depth` value returns an `invalid_depth` error.

Refer to the **Error Handling** section for the applicable error-response format.