Skip to content

买卖盘 ​

POST /api/v1.0/quote/order-book

获取标的的实时买卖盘摆盘。返回档数与盘口形态由用户行情权限档(LV1/LV2/LV3)与品类共同决定。

请求参数 ​

参数类型位置必填说明
codestring请求体是标的代码,格式 <MARKET>.<SYMBOL>,如 HK.00700。
numint请求体否返回档数上限,范围 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。

顶层字段 ​

参数类型说明
dataobject[]单标的摆盘,长度为 1
data[].codestring标的代码
data[].namestring英文名
data[].sc_namestring简体名
data[].tc_namestring繁体名
data[].booksobject[]盘口数组;美股 LV3 可含多个交易所
data[].books[].exchangestring交易所;合单盘口可为空
data[].books[].bid_flagint
data[].books[].ask_flagint
data[].books[].order_volume_precisionint
data[].books[].exchange_data_time_msint交易所时间,毫秒
data[].books[].server_send_to_client_time_msint
data[].books[].differenceint
data[].books[].bid_listobject[]买盘档位
data[].books[].bid_list[].pricenumber档位价格
data[].books[].bid_list[].volumeint档位数量
data[].books[].bid_list[].order_countint档位订单数
data[].books[].ask_listobject[]卖盘档位
data[].books[].ask_list[].pricenumber档位价格
data[].books[].ask_list[].volumeint档位数量
data[].books[].ask_list[].order_countint档位订单数
paginationobject部分接口返回分页信息

books[] 元素结构 ​

字段类型说明
exchangestring交易所/品种标识;美股 LV3 为 NASDAQ / ARCA,其它品类为空串
bid_flagint买盘有效标志,1=有买盘数据 / 0=无
ask_flagint卖盘有效标志,1=有卖盘数据 / 0=无
exchange_data_time_msint64交易所数据生成时间(毫秒时间戳)
server_send_to_client_time_msint64服务端下发时间(毫秒时间戳)
order_volume_precisionint订单数量精度(n 表示 volume 放大 10^n;0 表示整数)
differencedouble外汇差价(仅特定品类有值,普通股票为 0)
bid_listarray买盘列表,按价降序,每档含 price/volume/order_count
ask_listarray卖盘列表,按价升序,结构同 bid_list

bid_list[] / ask_list[] 元素结构 ​

字段类型说明
pricedouble该档价格
volumeint64该档总数量(单位见 order_volume_precision)
order_countint该档订单数(部分市场不下发,为 0)

限制范围 ​

  • code 必须使用接口支持且已开通行情权限的市场前缀;下表列出常见市场,其他已注册前缀同样可能受支持,否则返回 invalid_symbol。
  • 返回档数 = min(num, 权限档给出的上限);权限不足 / HK 全盘(SF) 一律降级为默认 1 档。

常见市场前缀与品类:

前缀市场支持品类
HK香港正股 / 信托 / REIT / 窝轮 / 牛熊证 / 界内证 / 指数 / 板块 / ETF / 期权
US美国正股 / ETF / 指数
SH上海正股 / ETF / 指数 / 板块
SZ深圳正股 / ETF / 指数 / 板块
BJ北京正股 / 指数
KR韩国正股 / ETF / 指数

错误码 ​

ret_codeerror.code触发条件处理建议
0—成功—
-3invalid_parameter缺 code / num 超出 1~60 范围 / 字段类型错校正请求体后重试
-4 / -6internal_error服务错误重试;持续失败请联系技术支持
-7invalid_symbolcode 无法解析(前缀不支持 / 代码不存在)检查市场前缀是否在限制范围内;通过 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
            }
          ]
        }
      ]
    }
  ]
}