买卖盘
POST/api/v1.0/quote/order-book获取标的的实时买卖盘摆盘。返回档数与盘口形态由用户行情权限档(LV1/LV2/LV3)与品类共同决定。
请求参数
| 参数 | 类型 | 位置 | 必填 | 说明 |
|---|---|---|---|---|
code | string | 请求体 | 是 | 标的代码,格式 <MARKET>.<SYMBOL>,如 HK.00700。 |
num | int | 请求体 | 否 | 返回档数上限,范围 1~60;不传则返回权限允许的最大档数。 |
请求示例
bash
curl -s -X POST "https://webapi.futunn.com/api/v1.0/quote/order-book" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <AccessToken>" \
-d '{"code":"HK.00700","num":3}' | jq响应字段
返回 data[](单 code 也为数组,含 1 个元素);每个元素含 code/name 与 books[] 盘口数组。美股 LV3 按交易所返回多个 book(如 NASDAQ + ARCA),其它品类为单元素 book。
顶层字段
| 参数 | 类型 | 说明 |
|---|---|---|
data | object[] | 单标的摆盘,长度为 1 |
data[].code | string | 标的代码 |
data[].name | string | 英文名 |
data[].sc_name | string | 简体名 |
data[].tc_name | string | 繁体名 |
data[].books | object[] | 盘口数组;美股 LV3 可含多个交易所 |
data[].books[].exchange | string | 交易所;合单盘口可为空 |
data[].books[].bid_flag | int | |
data[].books[].ask_flag | int | |
data[].books[].order_volume_precision | int | |
data[].books[].exchange_data_time_ms | int | 交易所时间,毫秒 |
data[].books[].server_send_to_client_time_ms | int | |
data[].books[].difference | int | |
data[].books[].bid_list | object[] | 买盘档位 |
data[].books[].bid_list[].price | number | 档位价格 |
data[].books[].bid_list[].volume | int | 档位数量 |
data[].books[].bid_list[].order_count | int | 档位订单数 |
data[].books[].ask_list | object[] | 卖盘档位 |
data[].books[].ask_list[].price | number | 档位价格 |
data[].books[].ask_list[].volume | int | 档位数量 |
data[].books[].ask_list[].order_count | int | 档位订单数 |
pagination | object | 部分接口返回分页信息 |
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) |
限制范围
- code 必须使用接口支持且已开通行情权限的市场前缀;下表列出常见市场,其他已注册前缀同样可能受支持,否则返回
invalid_symbol。 - 返回档数 = min(num, 权限档给出的上限);权限不足 / HK 全盘(SF) 一律降级为默认 1 档。
常见市场前缀与品类:
| 前缀 | 市场 | 支持品类 |
|---|---|---|
| HK | 香港 | 正股 / 信托 / REIT / 窝轮 / 牛熊证 / 界内证 / 指数 / 板块 / ETF / 期权 |
| US | 美国 | 正股 / ETF / 指数 |
| SH | 上海 | 正股 / ETF / 指数 / 板块 |
| SZ | 深圳 | 正股 / ETF / 指数 / 板块 |
| BJ | 北京 | 正股 / 指数 |
| KR | 韩国 | 正股 / ETF / 指数 |
错误码
| ret_code | error.code | 触发条件 | 处理建议 |
|---|---|---|---|
| 0 | — | 成功 | — |
| -3 | invalid_parameter | 缺 code / num 超出 1~60 范围 / 字段类型错 | 校正请求体后重试 |
| -4 / -6 | internal_error | 服务错误 | 重试;持续失败请联系技术支持 |
| -7 | invalid_symbol | code 无法解析(前缀不支持 / 代码不存在) | 检查市场前缀是否在限制范围内;通过 search 接口确认代码合法性 |
响应示例
json
{
"ret_code": 0,
"ret_msg": "success",
"data": [
{
"code": "HK.00700",
"name": "TENCENT",
"sc_name": "腾讯控股",
"tc_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
}
]
}
]
}
]
}