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; the gateway automatically selects the fetch method and level count based on permissions.

Request Parameters

Parameter	Type	Position	Required	Description
code	string	body	yes	Symbol code, format <MARKET>.<SYMBOL>, e.g. HK.00700.
num	int	body	no	Maximum number of price levels to return, range 1~60; if not provided, returns the maximum levels allowed by the user's permission.

Request Example

curl -s -X POST "https://webapi.moomoo.com/api/v1.0/quote/order-book" \
  -H "Content-Type: application/json" \
  -H "X-Futu-Client-Nnid: 76879657" \
  -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

Field	Type	Description
code	string	Symbol code
name	string	English name
sc_name	string	Simplified Chinese name
tc_name	string	Traditional Chinese name
books	array	Order book array, each element is a book for one exchange/category

books[] Element Structure

Field	Type	Description
exchange	string	Exchange/category identifier; US LV3 is NASDAQ / ARCA, others are empty string
bid_flag	int	Bid data valid flag, 1=has bid data / 0=none
ask_flag	int	Ask data valid flag, 1=has ask data / 0=none
exchange_data_time_ms	int64	Exchange data generation time (millisecond timestamp)
server_send_to_client_time_ms	int64	Server dispatch time (millisecond timestamp)
order_volume_precision	int	Order volume precision (n means volume is scaled by 10^n; 0 means integer)
difference	double	Forex spread (only meaningful for certain categories, 0 for regular stocks)
bid_list	array	Bid list, sorted by price descending, each level contains price/volume/order_count
ask_list	array	Ask list, sorted by price ascending, same structure as bid_list

bid_list[] / ask_list[] Element Structure

Field	Type	Description
price	double	Price at this level
volume	int64	Total volume at this level (unit per order_volume_precision)
order_count	int	Number of orders at this level (some markets do not provide this, returns 0)

Supported Markets

• Code must use a supported market prefix from the 5 markets listed below; otherwise 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.

Supported market prefixes and categories:

Prefix	Market	Supported Categories
HK	Hong Kong	Equity / Trust / REIT / Warrant / CBBC / Inline Warrant / Index / Sector / ETF / Option
US	United States	Equity / ETF / Index
SH	Shanghai	Equity / ETF / Index / Sector
SZ	Shenzhen	Equity / ETF / Index / Sector
BJ	Beijing	Equity / Index

Error Codes

ret_code	error.code	Trigger Condition	Recommended Action
0	—	Success	—
-3	invalid_parameter	Missing code / num out of 1~60 range / field type error	Correct request body and retry
-4	internal_error	Gateway failed to construct backend request	Retry; if persistent, contact gateway support
-6	internal_error	Gateway response conversion failed	Retry; if persistent, contact gateway support
-7	invalid_symbol	Code 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

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