市场与盘口

本页是市场列表 / 盘口 / 行情聚合 相关的读接口：JSON-RPC 方法、链 REST 别名，以及热读包装的 GET /api/v1/markets。实时行情与 K 线见 实时行情 · K 线。 交易界面的分类 tab 不是本页字段，见 链外运营 · 市场分类。

REST 缓存别名

与 Chain JSON-RPC 读方法 同源实现，返回 {height, data, page?} 骨架，HTTP 错误用真实状态码。

合并后现状：原 7 条别名中，GET /api/v1/markets、GET /api/v1/markets/{symbol}/summary、 GET /api/v1/bbos、GET /api/v1/marks 已由读侧热读实现接管（扁平热读包装，非本骨架）。 需要链骨架的做市商请用 POST /api/v1/query 同名方法。见 接口变更清单 §3.3。

路由	对应方法	说明
GET /api/v1/markets/{symbol}	getMarket	单市场详情
GET /api/v1/orderbook/{symbol}?depth={n}	getOrderbook	depth 可选，默认 50；0=全深度；非法值 → 400
GET /api/v1/stats	getGlobalStats	全局统计

---

市场/盘口

getMarkets

市场列表（不含 Delisted）。无参数。

响应 data · MarketListItem[]：

字段	类型	说明
symbol	String	交易对名
market_id	MarketId(u32)	系统内部 ID
kind	MarketKind	见 MarketKind
lifecycle	MarketLifecycle	"Created"→"Active"→"Halted"→"DelistPending"→"Delisted"
emergency_halt	bool	紧急熔断（与 lifecycle halt 正交）
halt_reason	HaltReason | null	Halted 分因："Admin" 管理员暂停（仅 ResumeMarket 恢复）· "QuoteStale" 报价过期自动暂停（报价恢复后自动恢复）；未暂停 / 旧链为 null
price_decimals	u32	价格小数位
size_decimals	u32	数量小数位
max_leverage	u32	最大杠杆
mark_price	String	标记价（px 精度 decimal）
prev_day_price	String	24h 前标记价（px 精度）
open_interest	String	未平仓量（= 多头总量，sz 精度）
open_interest_notional	String	未平仓名义值（SCALE_6）
day_ntl_volume	String	日内名义成交量（SCALE_6）
day_base_volume	String	日内基础成交量（sz 精度）

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": [{
      "symbol": "BTC-USDT",
      "market_id": 1,
      "kind": "Native",
      "lifecycle": "Active",
      "emergency_halt": false,
      "price_decimals": 2,
      "size_decimals": 5,
      "max_leverage": 50,
      "mark_price": "97225.00",
      "prev_day_price": "96500.00",
      "open_interest": "10.50000",
      "open_interest_notional": "1021862.500000",
      "day_ntl_volume": "12500000.000000",
      "day_base_volume": "128.50000"
    }]
  }
}

getMarket

单市场详情。

参数	类型	必填	说明
symbol	String	是	交易对名
market_id	u32	否	精确寻址；携带时优先于 symbol（重名 symbol 场景按 id 管理）

响应 data：

字段	类型	说明
config	MarketConfigWire	完整配置（symbol/kind/price_decimals/size_decimals/fee_recipient/max_leverage/fee_rates/margin_table 等）
emergency_halt	bool	紧急熔断
halt_reason	HaltReason | null	Halted 分因（同 getMarkets）
mark_price	String	标记价（px 精度）
latest_quote	OracleQuoteResponse?	最近 oracle 报价（部分市场）
last_stats	MarketStatsResponse?	最近统计

OracleQuoteResponse：

字段	类型	说明
bid_price	String	买一价（px 精度）
ask_price	String	卖一价（px 精度）
mark_price	String	标记价（px 精度）
source_ts_ms	u64	报价源时间戳
quoter	Address20	报价者地址
last_price	String?	外部最新成交价（HTTP 查询中恒为 null；仅 WS external_quote 携带）
volume	String?	外部成交量增量（HTTP 查询中恒为 null；仅 WS 携带）

MarketStatsResponse：

字段	类型	说明
long_size	String	多头总量（sz 精度）
short_size	String	空头总量（sz 精度）
net_size	String	净持仓（sz 精度）
oracle_counter_pnl	String	OracleCounter 累计 PnL（SCALE_6）
open_interest	String	未平仓量（sz 精度）
open_interest_notional	String	未平仓名义值（SCALE_6）
fills_in_block	u32	本块成交笔数
block_height	u64	最近统计块高

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": {
      "config": {
        "symbol": "BTC-USDT",
        "kind": "Native",
        "price_decimals": 2,
        "size_decimals": 5,
        "fee_recipient": "0x2222333344445555666677778888999900001111",
        "max_leverage": 50,
        "maker_fee_rate": "0.000200",
        "taker_fee_rate": "0.000500",
        "margin_table": [{
          "max_notional": "1000000.000000",
          "im_rate": "0.020000",
          "mm_rate": "0.010000",
          "max_leverage": 50
        }],
        "mark_max_change_bps": 500,
        "max_fills_per_quote": 32,
        "price_floor": "0.01",
        "price_ceil": "1000000.00"
      },
      "emergency_halt": false,
      "halt_reason": null,
      "mark_price": "97225.00",
      "latest_quote": null,
      "last_stats": {
        "long_size": "10.50000",
        "short_size": "8.20000",
        "net_size": "2.30000",
        "oracle_counter_pnl": "150.000000",
        "open_interest": "10.50000",
        "open_interest_notional": "1021862.500000",
        "fills_in_block": 5,
        "block_height": 12345
      }
    }
  }
}

getMarketById

按 market_id 点查单市场详情。重名 symbol 场景下精确管理的入口；响应结构与 getMarket 完全一致（同一 MarketDetailResponse 投影）。

参数	类型	必填	说明
market_id	u32	是	市场 ID

getOrderbook

盘口深度。bids 按价格降序、asks 升序。

参数	类型	必填	说明
symbol	String	是	交易对名
market_id	u32	否	精确寻址；携带时优先于 symbol
depth	usize	否	每侧档数；0 = 全深度；默认 50

响应 data：

字段	类型	说明
symbol	String	交易对名
height	u64	快照高度
state_hash	Hex32	盘口状态哈希
source	String	固定 "index"
bids	Level[]	买单档位
asks	Level[]	卖单档位

Level：

字段	类型	说明
price	String	价格（px 精度）
qty	String	该档 remaining 合计（sz 精度；不是原始下单量）
cumulative_qty	String	累计数量（sz 精度，从最优价向外累加）

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": {
      "symbol": "BTC-USDT",
      "height": 12345,
      "state_hash": "0xabc123def456789012345678901234567890abcdef1234567890abcdef123456",
      "source": "index",
      "bids": [
        { "price": "97200.00", "qty": "1.50000", "cumulative_qty": "1.50000" },
        { "price": "97150.00", "qty": "3.20000", "cumulative_qty": "4.70000" }
      ],
      "asks": [
        { "price": "97250.00", "qty": "2.10000", "cumulative_qty": "2.10000" }
      ]
    }
  }
}

---

行情聚合

getAllBBOs

全市场最优报价（不含 Delisted）。无参数。

响应 data： AllBboItem[]

字段	类型	说明
symbol	String	交易对名
bid	String?	买一价（px 精度）；空盘为 null
ask	String?	卖一价（px 精度）；空盘为 null
spread	String?	价差（px 精度）；任一侧空时 null

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": [
      { "symbol": "BTC-USDT", "bid": "97200.00", "ask": "97250.00", "spread": "50.00" },
      { "symbol": "ETH-USDT", "bid": null, "ask": "3450.00", "spread": null }
    ]
  }
}

getAllMarks

全市场标记价映射（不含 Delisted）。返回的是 mark（清算/uPnL 同源公允价），不是盘口中点 mid。无参数。

响应 data： Map<String, String> — symbol → mark_price（各自 px 精度）

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": {
      "BTC-USDT": "97225.00",
      "ETH-USDT": "3450.00"
    }
  }
}

getMarketSummary

单市场综合摘要。

参数	类型	必填	说明
symbol	String	是	交易对名
market_id	u32	否	精确寻址；携带时优先于 symbol

响应 data：

字段	类型	说明
symbol	String	交易对名
mark_price	String	标记价（px 精度）
best_bid	String?	买一价（px 精度）；空盘为 null
best_ask	String?	卖一价（px 精度）；空盘为 null
spread	String?	价差（px 精度）；任一侧空时 null
open_interest	String?	未平仓量（sz 精度）；无 stats 时 null
open_interest_notional	String?	未平仓名义值（SCALE_6）；无 stats 时 null
fills_in_block	u32?	本块成交笔数；无 stats 时 null
bid_levels	usize	买单档位数
ask_levels	usize	卖单档位数
open_orders	usize	挂单数
prev_day_price	String	24h 前标记价（px 精度）
day_ntl_volume	String	24h 名义成交量（SCALE_6）
day_base_volume	String	24h 币本位成交量（sz 精度）

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": {
      "symbol": "BTC-USDT",
      "mark_price": "97225.00",
      "best_bid": "97200.00",
      "best_ask": "97250.00",
      "spread": "50.00",
      "open_interest": "10.50000",
      "open_interest_notional": "1021862.500000",
      "fills_in_block": 5,
      "bid_levels": 42,
      "ask_levels": 38,
      "open_orders": 156,
      "prev_day_price": "96500.00",
      "day_ntl_volume": "12500000.000000",
      "day_base_volume": "128.50000"
    }
  }
}

getGlobalStats

全局统计摘要。无参数。

响应 data：

字段	类型	说明
account_count	usize	账户总数
market_count	usize	市场总数
deposit_count	usize	充值单总数
withdraw_count	usize	提现单总数
total_balance	String	总余额（SCALE_6；不含 uPnL，非 TVL）
total_open_interest_notional	String	全市场未平仓名义总额（SCALE_6）
settlement_paused	bool	桥接结算是否暂停
open_order_count	usize	全局挂单数

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": {
      "account_count": 1024,
      "market_count": 3,
      "deposit_count": 512,
      "withdraw_count": 128,
      "total_balance": "50000000.000000",
      "total_open_interest_notional": "25000000.000000",
      "settlement_paused": false,
      "open_order_count": 2048
    }
  }
}

---

getRecentTrades

公开成交历史（taker 侧去重）。按时间降序。读 index 成交流 ring buffer（出块 ingest + 启动 journal 10k 块回补）。

参数	类型	必填	说明
symbol	String	是	交易对名
market_id	u32	否	精确寻址；携带时优先于 symbol
offset	usize	否	默认 0
limit	usize	否	默认 100，最大 1000

响应 data · TradeResponse[]：

字段	类型	说明
block_height	u64	所在块高
event_seq	u64	块内事件序号
timestamp_ms	u64	成交时间（毫秒）
market_id	u32	市场 ID
symbol	String	交易对名
price	String	成交价（px 精度）
qty	String	成交量（sz 精度）
notional	String	名义价值（SCALE_6）
side	Side	"Bid" 或 "Ask"（taker 进攻方向）

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": [{
      "block_height": 12345,
      "event_seq": 3,
      "timestamp_ms": 1717200001000,
      "market_id": 1,
      "symbol": "BTC-USDT",
      "price": "97234.50",
      "qty": "0.50000",
      "notional": "48617.250000",
      "side": "Bid"
    }],
    "page": { "offset": 0, "limit": 100, "total": null }
  }
}

getUserFillsSince

用户成交增量同步（做市轮询）。读 fill archive 并与 index 内存 merge；返回严格晚于 cursor 的 fill，旧→新升序。游标为 (block_height, event_seq, order_id) 全序键（与 dedupe 键一致）。

参数	类型	必填	说明
address	Address20	是	账户地址
symbol	String	否	按市场过滤
market_id	u32	否	精确市场过滤（重名/跨代际历史）；携带时优先于 symbol，可查已下市市场历史
cursor	Object?	否	上一页末尾游标 { block_height, event_seq, order_id }；省略则从最早 fill 开始
limit	usize	否	默认 100，最大 1000

响应 data · UserFillsSinceResponse：

字段	类型	说明
fills	UserFillResponse[]	本页 fill（旧→新）
next_cursor	Object?	下一页游标；仅当本页满 limit 时返回，否则 null 表示已追上

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": {
      "fills": [{
        "block_height": 12345,
        "event_seq": 3,
        "timestamp_ms": 1717200001000,
        "market_id": 1,
        "symbol": "BTC-USDT",
        "order_id": 1001,
        "client_order_id": "my-cloid-1",
        "price": "97234.50",
        "qty": "0.50000",
        "notional": "48617.250000",
        "fee": "24.308625",
        "is_taker": true,
        "aggressor_side": "Bid"
      }],
      "next_cursor": { "block_height": 12345, "event_seq": 3, "order_id": 1001 }
    }
  }
}

市场列表（REST）

程序化接入行情：实时盘口 / 成交见 实时行情；K 线见 K 线。做市下单与账户仍用 Chain。

GET /api/v1/markets

节点已知市场列表（内存 cache）。热读包装，与 /bbos / /marks / /markets/{symbol}/summary 同族。

Response 200 — 扁平热读包装（meta 字段见 实时行情 §3.2）：

{
  "chain_height": 2046216,
  "book_updated_at_ms": 1717200000123,
  "stale": false,
  "ready": true,
  "data": [
    {
      "market_id": 1,
      "symbol": "BTC-USDT",
      "price_decimals": 2,
      "size_decimals": 4
    }
  ]
}

Field	Type	Description
chain_height	number	同 status hot_feed.chain_height
book_updated_at_ms	number	盘口最近更新时间（ms）
stale	boolean	上游 stale 时为 true；仍返回 200 与内存数据
ready	boolean	Feed 已 seed 且 slot 可读
data	array	MarketInfo[]，字段：market_id / symbol / price_decimals / size_decimals

做市商如需链 RPC 骨架（{ height, data }），用 Chain getMarkets / GET /api/v1/markets 的 链别名语义已被本热读包装取代，请改用 POST /api/v1/query。

---