買賣盤
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 }
]
}
]
}
]
}