Skip to content

Order Book ​

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

Get real-time bid/ask order book for a symbol. The number of levels and book shape are determined jointly by the user's market data permission level (LV1/LV2/LV3) and category.

Request Parameters ​

ParameterTypePositionRequiredDescription
codestringbodyyesSymbol code, format <MARKET>.<SYMBOL>, e.g. HK.00700.
numintbodynoMaximum number of price levels to return, range 1~60; if not provided, returns the maximum levels allowed by the user's permission.

Request Example ​

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

Response Fields ​

Returns data[] (single code is also an array with 1 element); each element contains code/name and a books[] order book array. US LV3 returns multiple books by exchange (e.g. NASDAQ + ARCA); other categories return a single-element book.

Top-level Fields ​

NameTypeDescription
dataobject[]Order book for one symbol. The array length is 1
data[].codestringSymbol
data[].namestringEnglish name
data[].sc_namestringSimplified Chinese name
data[].tc_namestringTraditional Chinese name
data[].booksobject[]Book array. US LV3 can include several exchanges
data[].books[].exchangestringExchange. Empty for an aggregated book
data[].books[].bid_flagint
data[].books[].ask_flagint
data[].books[].order_volume_precisionint
data[].books[].exchange_data_time_msintExchange time, Unix milliseconds
data[].books[].server_send_to_client_time_msint
data[].books[].differenceint
data[].books[].bid_listobject[]Bid levels
data[].books[].bid_list[].pricenumberLevel price
data[].books[].bid_list[].volumeintLevel size
data[].books[].bid_list[].order_countintOrder count at this level
data[].books[].ask_listobject[]Ask levels
data[].books[].ask_list[].pricenumberLevel price
data[].books[].ask_list[].volumeintLevel size
data[].books[].ask_list[].order_countintOrder count at this level
paginationobjectPagination returned by some endpoints

books[] Element Structure ​

FieldTypeDescription
exchangestringExchange/category identifier; US LV3 is NASDAQ / ARCA, others are empty string
bid_flagintBid data valid flag, 1=has bid data / 0=none
ask_flagintAsk data valid flag, 1=has ask data / 0=none
exchange_data_time_msint64Exchange data generation time (millisecond timestamp)
server_send_to_client_time_msint64Server dispatch time (millisecond timestamp)
order_volume_precisionintOrder volume precision (n means volume is scaled by 10^n; 0 means integer)
differencedoubleForex spread (only meaningful for certain categories, 0 for regular stocks)
bid_listarrayBid list, sorted by price descending, each level contains price/volume/order_count
ask_listarrayAsk list, sorted by price ascending, same structure as bid_list

bid_list[] / ask_list[] Element Structure ​

FieldTypeDescription
pricedoublePrice at this level
volumeint64Total volume at this level (unit per order_volume_precision)
order_countintNumber of orders at this level (some markets do not provide this, returns 0)

Supported Markets ​

  • Code must use a market prefix supported by the API and your quote entitlements; the table below lists common markets, and other registered prefixes may also be supported. Otherwise, the API returns invalid_symbol.
  • Returned levels = min(num, the upper limit per category x permission level); insufficient permission / HK full-market (SF) downgrades to default 1 level.

Common market prefixes and categories:

PrefixMarketSupported Categories
HKHong KongEquity / Trust / REIT / Warrant / CBBC / Inline Warrant / Index / Sector / ETF / Option
USUnited StatesEquity / ETF / Index
SHShanghaiEquity / ETF / Index / Sector
SZShenzhenEquity / ETF / Index / Sector
BJBeijingEquity / Index
KRKoreaEquity / ETF / Index

Error Codes ​

ret_codeerror.codeTrigger ConditionRecommended Action
0—Success—
-3invalid_parameterMissing code / num out of 1~60 range / field type errorCorrect request body and retry
-4 / -6internal_errorService errorRetry; if persistent, contact support
-7invalid_symbolCode cannot be parsed (unsupported prefix / code does not exist)Check that market prefix is within supported range; use search API to confirm code validity

Response Example ​

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