> 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/zhs/bbx-dex-public-api/coingecko-ji-cheng/he-yue-ding-dan-bo.md).

# 合约订单簿

返回指定 BBX DEX 加密货币永续合约市场当前的订单簿深度数据。

响应分别包含 `bids` 和 `asks` 数组。每个价格档位均以 `[价格, 数量]` 的形式表示，其中价格和数量均以字符串形式返回。

### 端点

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

### 完整 URL

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

### 身份验证

无需身份验证。

该端点可公开访问，并且无需：

* API 密钥
* 请求签名
* 登录凭证
* 身份验证令牌
* 自定义请求头

### 查询参数

| 参数          | 类型        | 是否必填 | 说明                                      |
| ----------- | --------- | ---- | --------------------------------------- |
| `ticker_id` | `string`  | 是    | 合约标识符，采用 `BASE-TARGET` 格式，例如 `BTC-USDT` |
| `depth`     | `integer` | 否    | 买单侧和卖单侧合计请求的订单簿档位数量                     |

### 交易对命名规则

`ticker_id` 必须采用以下格式：

```
BASE-TARGET
```

示例：

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

### 深度规则

`depth` 参数表示买单侧和卖单侧合计请求的订单簿档位数量。

| 请求深度  | 最多返回的买单档位 | 最多返回的卖单档位 |
| ----- | --------- | --------- |
| `100` | `50`      | `50`      |
| `200` | `100`     | `100`     |

当 `depth` 为奇数时，请求深度将在订单簿两侧之间分配，并在适用情况下向上取整。

当省略 `depth` 或将其设置为 `0` 时，该端点将返回当前可用的最大深度，但每侧最多返回 500 个档位。

当 `depth` 大于或等于 `1000` 时，将视为请求当前可用的最大深度。

当 `depth` 为负数时，将返回 `invalid_depth` 错误。

### 请求示例

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

### 响应示例

```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"]
  ]
}
```

> 以上数值仅用于示例。实际响应将返回 BBX 当前的市场数据。

### 响应字段

| 字段          | 类型        | 要求 | 说明                           |
| ----------- | --------- | -- | ---------------------------- |
| `ticker_id` | `string`  | 必填 | 合约标识符，采用 `BASE-TARGET` 格式    |
| `timestamp` | `integer` | 推荐 | 订单簿更新时间，采用 Unix 毫秒级时间戳       |
| `bids`      | `array`   | 必填 | 买单档位，以 `[价格, 数量]` 字符串数组的形式表示 |
| `asks`      | `array`   | 必填 | 卖单档位，以 `[价格, 数量]` 字符串数组的形式表示 |

### 订单排序

买单档位按照价格从高到低排列。

卖单档位按照价格从低到高排列。

每个价格档位采用以下格式：

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

示例：

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

在该示例中：

* `67249.8` 为价格
* `0.512` 为该价格档位的可用数量

### 时间戳单位

`timestamp` 字段采用 Unix 毫秒级时间戳。

示例：

```
1721548812345
```

### 空订单簿

如果订单簿数据暂时不可用，包括新上线合约的深度缓存尚未生成，该端点将返回 HTTP `200`，同时返回空的 `bids` 和 `asks` 数组。

示例：

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

在这种情况下，该端点不会返回空的响应正文。

### 无效请求

未知、已禁用或不受支持的合约标识符将返回 `invalid_symbol` 错误。

负数的 `depth` 参数将返回 `invalid_depth` 错误。

有关适用的错误响应格式，请参阅「错误处理」章节。