买卖盘
POST/v1/quote/order-book获取标的的实时买卖盘摆盘。返回档数与盘口形态由用户行情权限档（LV1/LV2/LV3）与品类共同决定，网关按权限自动选择拉取方式与档数。
请求参数
| 参数 | 类型 | 位置 | 必填 | 说明 |
|---|---|---|---|---|
code | string | 请求体 | 是 | 标的代码，格式 <MARKET>.<SYMBOL>，如 HK.00700。 |
num | int | 请求体 | 否 | 返回档数上限，范围 1~60；不传则返回权限允许的最大档数。 |
请求示例
bash
curl -s -X POST "$ip/v1/quote/order-book" \
-H "Content-Type: application/json" \
-H "X-Futu-Client-Nnid: 76879657" \
-d '{"code":"HK.00700","num":3}' | jq响应字段
返回 data[]（单 code 也为数组，含 1 个元素）；每个元素含 code/name 与 books[] 盘口数组。美股 LV3 按交易所返回多个 book（如 NASDAQ + ARCA），其它品类为单元素 book。
顶层字段
| 字段 | 类型 | 说明 |
|---|---|---|
| code | string | 标的代码 |
| name | string | 标的名称 |
| books | array | 盘口数组，每元素为一个交易所/品种的摆盘 |
books[] 元素结构
| 字段 | 类型 | 说明 |
|---|---|---|
| exchange | string | 交易所/品种标识；美股 LV3 为 NASDAQ / ARCA，其它品类为空串 |
| bid_flag | int | 买盘有效标志，1=有买盘数据 / 0=无 |
| ask_flag | int | 卖盘有效标志，1=有卖盘数据 / 0=无 |
| exchange_data_time_ms | int64 | 交易所数据生成时间（毫秒时间戳） |
| server_send_to_client_time_ms | int64 | 服务端下发时间（毫秒时间戳） |
| order_volume_precision | int | 订单数量精度（n 表示 volume 放大 10^n；0 表示整数） |
| difference | double | 外汇差价（仅特定品类有值，普通股票为 0） |
| bid_list | array | 买盘列表，按价降序，每档含 price/volume/order_count |
| ask_list | array | 卖盘列表，按价升序，结构同 bid_list |
bid_list[] / ask_list[] 元素结构
| 字段 | 类型 | 说明 |
|---|---|---|
| price | double | 该档价格 |
| volume | int64 | 该档总数量（单位见 order_volume_precision） |
| order_count | int | 该档订单数（部分市场不下发，为 0） |
限制范围
- 支持市场：HK / US / SH / SZ / SG / JP / BMS(马来) 等；其它未列市场默认返回 1 档。
- 品类：正股 / ETF / 窝轮 / 牛熊证 / 界内证 / 期权 / 期货 等。
- 返回档数 = min(num, 下表按品类 x 权限档给出的上限)；权限不足 / 表中「—」/ HK 全盘(SF) 一律降级为默认 1 档。
各品类 x 权限档的返回档数：
| 品类 | LV1 | LV2 | LV3 |
|---|---|---|---|
| 港股（正股/窝轮/牛熊/界内证） | 1 | 10 | — |
| 港股期权/期货 | 1 | 10 | — |
| 美股（含 ETF） | 1 | 60（全美综合） | NASDAQ 60 + ARCA 60（分交易所） |
| 美股期权 | 1 | — | — |
| 美股期货 | — | 40 | — |
| A 股 | 5 | — | — |
| 新加坡股票 | 1 | 40 | — |
| 马来西亚股票 | 3 | 5 | 10 |
| 日本股票 | — | 10 | 40 |
错误码
| ret_code | error.code | 触发条件 | 处理建议 |
|---|---|---|---|
| 0 | — | 成功 | — |
| -3 | invalid_parameter | 缺 code / num 超出 1~60 范围 / 字段类型错 | 校正请求体后重试 |
| -4 | internal_error | 网关构造后端请求失败 | 重试；持续失败请联系网关侧 |
| -6 | internal_error | 网关响应转换失败 | 重试；持续失败请联系网关侧 |
| -7 | invalid_symbol | code 无法解析（前缀不支持 / 代码不存在） | 检查市场前缀是否在限制范围内；通过 search 接口确认代码合法性 |
响应示例
json
{
"ret_code": 0,
"ret_msg": "success",
"data": [
{
"code": "HK.00700",
"name": "腾讯控股",
"books": [
{
"exchange": "",
"bid_flag": 1,
"ask_flag": 1,
"exchange_data_time_ms": 1780378533000,
"server_send_to_client_time_ms": 1780378533768,
"order_volume_precision": 0,
"difference": 0,
"ask_list": [
{ "price": 473.6, "volume": 21400, "order_count": 23 },
{ "price": 473.8, "volume": 7900, "order_count": 21 },
{ "price": 474.0, "volume": 29000, "order_count": 48 }
],
"bid_list": [
{ "price": 473.4, "volume": 28300, "order_count": 42 },
{ "price": 473.2, "volume": 22800, "order_count": 26 },
{ "price": 473.0, "volume": 21500, "order_count": 39 }
]
}
]
}
]
}