读方法与 REST 别名

统一入口：POST /api/v1/query（JSON-RPC 2.0） · 37 个 QueryMethod · 支持 batch REST 别名：7 个 CDN-cacheable GET 包装 · 复用同名 JSON-RPC 实现 GET /api/v1/health：裸 REST 探针 生产 Base URL： https://rpc.auroran.io

---

目录

• 1. 健康检查
• 2. 响应骨架
• 3. 分页约定
• 4. REST 缓存别名
• 5. 链/元数据
  • 5.1 getHealth
  • 5.2 getBlock
  • 5.3 getBlockEvents
  • 5.4 getTx
  • 5.5 getExchangeConfig
  • 5.6 getActionsMeta
• 6. 市场/盘口
  • 6.1 getMarkets
  • 6.2 getMarket
  • 6.3 getOrderbook
• 7. 行情聚合
  • 7.1 getAllBBOs
  • 7.2 getAllMarks
  • 7.3 getMarketSummary
  • 7.4 getGlobalStats
• 8. 账户/角色
  • 8.1 getAccount
  • 8.2 getAccountOrders
  • 8.3 getPosition
  • 8.4 listAccounts
• 9. Bridge 充提
  • 9.1 getBridgeSettlement
  • 9.2 getBridgeDeposit
  • 9.3 getBridgeDepositByExternalRef
  • 9.4 listBridgeDeposits
  • 9.5 getBridgeWithdrawal
  • 9.6 listBridgeWithdrawals
• 10. 历史/审计
  • 10.1 getRecentTrades
  • 10.2 getUserFills
  • 10.3 getCandles
  • 10.4 getOrderStatus
  • 10.5 getUserRateLimit
  • 10.6 getAdminAuditLog
  • 10.7 getUserFees
  • 10.8 getReferral
• 11. 风险/清算
  • 11.1 getLiquidatablePositions
  • 11.2 getEstimatedLiquidationPrice
• 12. 检索/排行/监控
  • 12.1 getTopAccounts
  • 12.2 getAllOpenOrders
  • 12.3 getTriggerOrders
  • 12.4 getOcoPairs
• 13. Bootstrap
  • 13.1 getBootstrap

---

1. 健康检查

GET /api/v1/health

纯 REST，不走 JSON-RPC。HTTP 200 = 正常，503 = halted。

响应示例：

{
  "status": "ok",
  "height": 12345
}

字段	类型	说明
status	String	"ok"（当前仅 ok；recovering/degraded 预留）
height	u64	当前链高度

---

2. 响应骨架

所有 JSON-RPC 读方法的 result 使用统一骨架：

{
  "height": 12345,
  "data": { ... },
  "page": { "offset": 0, "limit": 100, "total": 243 }
}

字段	类型	说明
height	u64	index 快照高度标签（非版本选择器）
data	T	端点具体数据
page	Object?	仅分页端点出现（见 §3）。非分页端点省略此字段

REST 别名直接返回此骨架（无 jsonrpc/id 外壳）。

---

3. 分页约定

分页端点统一使用：

请求参数（在 params 内）：

参数	类型	默认	说明
offset	usize	0	偏移量
limit	usize	端点特定	返回条数上限

响应 page 对象：

字段	类型	说明
offset	usize	请求的 offset
limit	usize	实际生效值（取 min(请求值, 系统上限)）
total	usize?	总条数。index 扫描端点有值；journal 扫描端点（getRecentTrades/getUserFills/getAdminAuditLog）为 null——历史总量不可知

端点类型	默认 limit	最大 limit
事件扫描（getBlockEvents）	500	2000
成交 / 审计	100	1000
list 系列	100	500
K 线	500	2000
排行（getTopAccounts）	50	50

---

4. REST 缓存别名

CDN-cacheable GET 包装，复用同名 JSON-RPC 实现。返回 {height, data, page?}，HTTP 错误用真实状态码（非 JSON-RPC error body）。

路由	对应方法	说明
GET /api/v1/markets	getMarkets	市场列表
GET /api/v1/markets/{symbol}	getMarket	单市场详情
GET /api/v1/markets/{symbol}/summary	getMarketSummary	单市场摘要
GET /api/v1/orderbook/{symbol}?depth={n}	getOrderbook	depth 可选，默认 50；0=全深度；非法值 → 400
GET /api/v1/bbos	getAllBBOs	全市场最优报价
GET /api/v1/marks	getAllMarks	全市场标记价
GET /api/v1/stats	getGlobalStats	全局统计

---

5. 链/元数据

5.1 getHealth

JSON-RPC 存活探针。与 GET /health 语义不同：不检查 halted，恒 HTTP 200。无参数。

请求：

{ "jsonrpc": "2.0", "id": 1, "method": "getHealth" }

响应 data： { "status": "ok", "height": 12345 }

5.2 getBlock

查询单个块。不传 height 返回最新块。

参数	类型	必填	说明
height	u64	否	块高度，默认 tip

响应 data：

字段	类型	说明
parent	Hex32	父块哈希
height	u64	块高度
timestamp_ms	u64	块时间戳（毫秒）
digest	Hex32	块 SHA-256 哈希
envelope_count	usize	块内交易数
event_count	usize	块内事件数
state_root	Hex32	状态根哈希
envelopes	BlockEnvelopeView[]	交易列表

BlockEnvelopeView：

字段	类型	说明
tx_hash	TxHash	交易哈希（0x hex）
envelope_idx	u32	块内序号
signer	Address20	签名者地址
nonce	u64	账户 nonce
action	Value	Action JSON
status	TxStatus	"accepted" · "kept-reject"
reason	RejectReason?	仅 kept-reject 时出现

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": {
      "parent": "0xabc...def",
      "height": 12345,
      "timestamp_ms": 1717200000000,
      "digest": "0x123...789",
      "envelope_count": 15,
      "event_count": 42,
      "state_root": "0xdef...abc",
      "envelopes": [{
        "tx_hash": "0xa1b2...c3d4",
        "envelope_idx": 0,
        "signer": "0x1111222233334444555566667777888899990000",
        "nonce": 42,
        "action": { "PlaceOrder": { ... } },
        "status": "accepted"
      }]
    }
  }
}

5.3 getBlockEvents

按高度查块内事件（分页）。事件格式见 事件投影。

参数	类型	必填	说明
height	u64	是	块高度
offset	usize	否	默认 0
limit	usize	否	默认 500，最大 2000

请求：

{ "jsonrpc": "2.0", "id": 1, "method": "getBlockEvents", "params": { "height": 12345, "offset": 0, "limit": 10 } }

响应 data： EventValue[] — 每项为 {"seq": u64, "block_height": u64, "envelope_idx": u32, "kind": {"DomainTag": {"Variant": {...}}}}，数值字段已投影为 decimal string。

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": [{
      "seq": 3,
      "block_height": 12345,
      "envelope_idx": 1,
      "kind": {
        "Exec": {
          "Filled": {
            "taker_order_id": 1001,
            "maker_order_id": 1002,
            "market_id": 1,
            "price": "97234.50",
            "qty": "0.50000",
            "notional": "48617.250000",
            "taker_fee": "24.308625",
            "maker_fee": "-4.861725",
            "aggressor_side": "Bid"
          }
        }
      }
    }],
    "page": { "offset": 0, "limit": 10, "total": 42 }
  }
}

5.4 getTx

按交易哈希查回执。

参数	类型	必填	说明
hash	TxHash	是	32 字节 hex（0x 前缀）

响应 data：

字段	类型	说明
tx_hash	TxHash	交易哈希
height	u64	所在块高
envelope_idx	u32	块内序号
signer	Address20	签名者地址
nonce	u64	账户 nonce
action	Value	Action JSON
status	TxStatus	"accepted" · "kept-reject"
reason	RejectReason?	仅 kept-reject 时出现
events	Value[]	本笔交易事件（decimal string 投影）

5.5 getExchangeConfig

全局配置/状态。无参数。

响应 data：

字段	类型	说明
action_version	u32	Wire 协议版本（当前 2）
max_decimals	u32	SCALE_6 精度上限
max_tx_per_block	usize	每块最大交易数
settlement_paused	bool	全局 Bridge 结算闸门
market_count	usize	活跃市场数

响应示例：

{
  "action_version": 2,
  "max_decimals": 6,
  "max_tx_per_block": 1024,
  "settlement_paused": false,
  "market_count": 3
}

5.6 getActionsMeta

39 种 Action 的鉴权/角色元数据。无参数。

响应 data：

字段	类型	说明
action_version	u32	Wire 协议版本
actions	ActionMetaItem[]	每项：name(ActionKind) / auth(AuthChannel) / role(AccountRole?) / master_only(bool)

---

6. 市场/盘口

6.1 getMarkets

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

响应 data · MarketListItem[]：

字段	类型	说明
symbol	String	交易对名
market_id	MarketId(u32)	系统内部 ID
kind	MarketKind	"Native" CLOB · "ExternalPeg" 预言机
lifecycle	MarketLifecycle	"Created"→"Active"→"Halted"→"DelistPending"→"Delisted"
emergency_halt	bool	紧急熔断（与 lifecycle halt 正交）
price_decimals	u32	价格小数位
size_decimals	u32	数量小数位
max_leverage	u32	最大杠杆
mark_price	String	标记价（px 精度 decimal）
prev_day_price	String	24h 前标记价（px 精度）
day_ntl_volume	String	日内名义成交量（SCALE_6）
day_base_volume	String	日内基础成交量（sz 精度）

6.2 getMarket

单市场详情。

参数	类型	必填	说明
symbol	String	是	交易对名

响应 data：

字段	类型	说明
config	MarketConfigWire	完整配置（symbol/kind/price_decimals/size_decimals/fee_recipient/max_leverage/fee_rates/margin_tiers 等）
emergency_halt	bool	紧急熔断
mark_price	String	标记价（px 精度）
latest_quote	OracleQuoteResponse?	最近 oracle 报价（仅 ExternalPeg）
last_stats	MarketStatsResponse?	最近统计

OracleQuoteResponse：

字段	类型	说明
bid_price	String	买一价（px 精度）
ask_price	String	卖一价（px 精度）
mark_price	String	标记价（px 精度）
source_ts_ms	u64	报价源时间戳
sequence_id	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	最近统计块高

6.3 getOrderbook

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

参数	类型	必填	说明
symbol	String	是	交易对名
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	数量（sz 精度）
cumulative_qty	String	累计数量（sz 精度，从最优价向外累加）

---

7. 行情聚合

7.1 getAllBBOs

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

响应 data： AllBboItem[]

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

7.2 getAllMarks

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

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

7.3 getMarketSummary

单市场综合摘要。

参数	类型	必填	说明
symbol	String	是	交易对名

响应 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 精度）

7.4 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	全局挂单数

---

8. 账户/角色

8.1 getAccount

账户全貌：余额、持仓、衍生指标。合法 address 但链上从未出现 → 返回零值壳（balance="0"、nonce=0、空 positions），不回 -32004。

参数	类型	必填	说明
address	Address20	是	账户地址

响应 data：

字段	类型	说明
address	Address20	账户地址
balance	String	余额（SCALE_6）
nonce	u64	当前 nonce
role_mask	u64	角色位掩码
account_value	String	总价值 = balance + Σ(uPnL)（SCALE_6）
total_margin_used	String	已用保证金（SCALE_6）
total_notional	String	总名义价值（SCALE_6）
withdrawable	String	可提现 = max(0, account_value − total_margin_used)（SCALE_6）
positions	Map<MarketId, PositionResponse>	持仓映射（key = MarketId u32）。仅含已开仓（size != 0）的市场；只设了杠杆或预存逐仓保证金但未开仓的市场不出现在此（其锁定资金仍反映在 total_margin_used / withdrawable）
agents	AgentResponse[]	已授权 agent 列表
dms_deadline_ms	u64?	Dead-Man-Switch 截止时刻（毫秒）；null = 未开启

PositionResponse：

字段	类型	说明
symbol	String	交易对名
size	String	仓位大小（sz 精度），正=多，负=空
entry_vwap	String	开仓均价 VWAP（px 精度）
mark_price	String	当前标记价（px 精度；与 marks 主题同源）
margin_mode	MarginMode	"Cross" · "Isolated"
leverage	u32	杠杆倍数
isolated_margin	String	逐仓保证金（SCALE_6）；Cross 为 "0"
margin_used	String	占用保证金（SCALE_6）
unrealized_pnl	String	未实现盈亏 = size × (mark − entry)（SCALE_6）
notional	String	名义价值 =
liquidation_price	String?	强平价（px 精度）；无法计算时 null
roe	String?	ROE 比率（SCALE_6）；IM=0 时 null

AgentResponse：

字段	类型	说明
address	Address20	Agent 的 secp256k1 API-wallet 地址
role_mask	u64	Agent 被授予的角色位图
expires_at_ms	u64	过期时间（毫秒）；0 = 永不过期

8.2 getAccountOrders

查询账户当前挂单。

参数	类型	必填	说明
address	Address20	是	账户地址

响应 data： AccountOrdersResponse — address + orders: RestingOrderResponse[]

RestingOrderResponse：

字段	类型	说明
order_id	u64	系统订单 ID
owner	Address20	挂单账户
market_id	u32	市场 ID
symbol	String	交易对名
side	Side	"Bid" · "Ask"
price	String	限价（px 精度）
qty	String	原始数量（sz 精度）
remaining	String	未成交余量（sz 精度）
filled	String	已成交量 = qty − remaining（sz 精度）
tif	TimeInForce	"Gtc" · "Ioc" · "Fok" · "PostOnly"
reduce_only	bool	仅减仓
order_type	String	"Limit"（Gtc/PostOnly）· "Market"（Ioc/Fok）
client_order_id	String?	客户端订单 ID
placed_at_ms	u64	挂单时刻（毫秒）
expires_at_ms	u64?	GTD 过期时刻；null = GTC 长挂

8.3 getPosition

按地址+市场查单仓位（含实时衍生指标）。账户不存在、无该市场持仓、或 symbol 无效 → -32004。

参数	类型	必填	说明
address	Address20	是	账户地址
symbol	String	是	交易对名

响应 data： PositionResponse（同 getAccount 中的持仓结构）

8.4 listAccounts

账户列表（分页 + 可选多维度过滤）。

参数	类型	必填	说明
offset	usize	否	默认 0
limit	usize	否	默认 100，最大 500
role	RoleFilter	否	按角色过滤（trader/oracle_operator/settlement_operator/admin/liquidator/quoter）
referral_code	String	否	按注册的推荐码检索（≤1 命中）
referred_by_code	String	否	按绑定的推荐码检索

响应 data： AccountListItem[]

字段	类型	说明
address	Address20	账户地址
balance	String	余额（SCALE_6）
nonce	u64	当前 nonce
role_mask	u64	角色位掩码
position_count	usize	持仓数（仅计 size != 0 的市场）

---

9. Bridge 充提

9.1 getBridgeSettlement

全局结算闸门。无参数。

响应 data： { "settlement_paused": false }

9.2 getBridgeDeposit

按链上分配序号查询单笔充值。

参数	类型	必填	说明
seq	u64	是	链上充值序号（自增，严格连续）

响应 data： { "deposit": DepositResponse }

9.3 getBridgeDepositByExternalRef

按外部链充值引用 (chain, seq) 查询充值单。用于 operator 判断某笔外部链充值是否已处理——未找到时 data 为 null。

参数	类型	必填	说明
chain	String	是	外部链标识（小写，如 "bsc" / "admin"）
seq	u64	是	外部链充值序号

响应 data： { "deposit": DepositResponse } 或 null

9.4 listBridgeDeposits

充值列表（seq 升序，可按 owner 过滤）。

参数	类型	必填	说明
owner	Address20	否	按 owner 过滤
offset	usize	否	默认 0
limit	usize	否	默认 100，最大 500

9.5 getBridgeWithdrawal

按 ID 查询单笔提现。

参数	类型	必填	说明
id	u64	是	提现请求 ID

响应 data： { "withdrawal": WithdrawResponse }

9.6 listBridgeWithdrawals

提现列表（可按 owner、status 过滤）。

参数	类型	必填	说明
owner	Address20	否	按 owner 过滤
status	String	否	pending/settled/refunded
offset	usize	否	默认 0
limit	usize	否	默认 100，最大 500

DepositResponse 字段：

字段	类型	说明
seq	u64	链上充值序号（自增，排序键）
chain	String	外部链标识（小写，如 "bsc" / "admin"）
external_seq	u64	外部链充值序号（去重键）
tx_hash	[u8;32]?	BSC 交易哈希（JSON 序列化为字节数组，非 0x hex）
owner	Address20	充值账户
amount	String	充值金额（SCALE_6）
bsc_block	u64	BSC 块号（管理员补 0）
bsc_ts	u64	BSC 时间戳秒（管理员补 0）
status	DepositStatus	"Recorded" 已登记 · "Credited" 已入账
recorded_at_block	u64	登记链块高
recorded_at_ms	u64	登记时间（毫秒）
credited_at_block	u64?	入账块高（未入账为 null）
credited_at_ms	u64?	入账时间（未入账为 null）

WithdrawResponse 字段：

字段	类型	说明
request_id	u64	提现请求 ID
owner	Address20	提现账户
amount	String	提现金额（SCALE_6）
chain	String	用户选择的下提目标链（如 "bsc"）
status	WithdrawStatus	"Pending" · "Settled" · "Refunded"
settle_tx_hash	[u8;32]?	仅 Settled（JSON 字节数组）
settle_bsc_block	u64?	仅 Settled
settle_bsc_ts	u64?	仅 Settled
reason_code	u8?	仅 Refunded
requested_at_block	u64	请求所在块
requested_at_ms	u64	请求时间
finalized_at_block	u64?	null = Pending
finalized_at_ms	u64?	null = Pending

---

10. 历史/审计

以下端点走 journal 扫描（最多回溯 10,000 块），page.total 恒为 null。

10.1 getRecentTrades

公开成交历史（taker 侧去重）。按时间降序。

参数	类型	必填	说明
symbol	String	是	交易对名
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 进攻方向）

10.2 getUserFills

用户成交历史（含费用）。

参数	类型	必填	说明
address	Address20	是	账户地址
symbol	String	否	按市场过滤
start_time_ms	u64	否	起始时间（毫秒）
end_time_ms	u64	否	结束时间（毫秒）
offset	usize	否	默认 0
limit	usize	否	默认 100，最大 1000

响应 data · UserFillResponse[]： 同 TradeResponse + 以下字段：

字段	类型	说明
order_id	u64	用户侧订单 ID（成交↔订单对账键）
client_order_id	String?	客户端订单 ID（仍挂簿时由 index 反查；已离簿为 null）
fee	String	手续费（SCALE_6；负值 = maker rebate）
is_taker	bool	是否吃单方
aggressor_side	Side	吃单方向

10.3 getCandles

K 线历史（journal 聚合）。无 start_time_ms/end_time_ms 时走块级缓存（按 (market_id, interval_ms) 缓存，新块失效），适合图表轮询。

参数	类型	必填	说明
symbol	String	是	交易对名
interval_ms	u64	是	K 线周期（毫秒），必须 > 0
start_time_ms	u64	否	起始时间（毫秒）
end_time_ms	u64	否	结束时间（毫秒）
limit	usize	否	默认 500，最大 2000

响应 data · CandleResponse[]：

字段	类型	说明
open_time_ms	u64	蜡烛起始（对齐 interval 边界）
close_time_ms	u64	蜡烛结束 = open_time_ms + interval_ms
open	String	开盘价（px 精度）
high	String	最高价（px 精度）
low	String	最低价（px 精度）
close	String	收盘价（px 精度）
volume	String	成交量（sz 精度）
trades	u64	成交笔数

常用 interval_ms：1m=60000, 5m=300000, 15m=900000, 1h=3600000, 4h=14400000, 1d=86400000

10.4 getOrderStatus

按 order_id 或 (address, symbol, client_order_id) 查订单生命周期。二选一。

参数	类型	必填	说明
order_id	u64	条件	按 order_id 直接查（与 cloid 互斥）
client_order_id	String	条件	按 cloid 查（需同时给 address + symbol）
address	Address20	条件	cloid 模式必填
symbol	String	条件	cloid 模式必填

响应 data：

字段	类型	说明
order_id	u64	订单 ID
status	OrderLifecycleStatus	"open" · "closed" · "unknown"
market_id	u32?	市场 ID
symbol	String?	交易对名
side	Side?	仅 open
price	String?	限价（px 精度），仅 open
qty	String?	原始数量（sz 精度），仅 open
remaining	String?	余量（sz 精度），仅 open
filled	String?	已成交量（sz 精度）
avg_price	String?	成交均价（px 精度）
client_order_id	String?	客户端订单 ID
close_reason	CloseReason?	仅 closed："filled"/"ioc_expired"/"cancelled"/"gtd_expired"/"fok_rejected"/"market_delisted"

10.5 getUserRateLimit

用户速率限制视图（journal 窗口即时统计）。

参数	类型	必填	说明
address	Address20	是	账户地址

响应 data：

字段	类型	说明
address	Address20	账户地址
cum_vlm	String	窗口内累计名义成交量（SCALE_6）
n_requests_used	u64	窗口内已用请求数
n_requests_cap	u64	系统上限 max_tx_per_block（参考值）
window_blocks	u64	扫描窗口（10,000 块）

10.6 getAdminAuditLog

管理操作审计（journal 扫描 OpsEvent）。

参数	类型	必填	说明
signer	Address20	否	按操作者过滤
start_time_ms	u64	否	起始时间（毫秒）
end_time_ms	u64	否	结束时间（毫秒）
offset	usize	否	默认 0
limit	usize	否	默认 100，最大 1000

响应 data · AdminAuditEntry[]： block_height/event_seq/timestamp_ms/signer/event(OpsEvent JSON)

10.7 getUserFees

用户自定义费率。

参数	类型	必填	说明
address	Address20	是	账户地址

响应 data： address / custom_maker_fee_rate(String?, SCALE_6, null=市场默认) / custom_taker_fee_rate(String?, 同上)

10.8 getReferral

用户推荐关系。

参数	类型	必填	说明
address	Address20	是	账户地址

响应 data： address / referred_by_code(String?, 被谁推荐，null=未绑定) / referral_code(String?, 自己的推荐码，null=未注册) / n_referrals(u64)

---

11. 风险/清算

11.1 getLiquidatablePositions

需清算仓位列表（按 shortfall 降序）。emergency_halt 市场不列出。

参数	类型	必填	说明
symbol	String	否	按市场过滤
offset	usize	否	默认 0
limit	usize	否	默认 100，最大 1000

响应 data · LiquidatablePosition[]：

字段	类型	说明
account	Address20	账户地址
market_id	u32	市场 ID
symbol	String	交易对名
size	String	仓位大小（sz 精度）
entry_vwap	String	开仓均价（px 精度）
mark_price	String	标记价（px 精度）
equity	String	账户权益（SCALE_6）
mm_required	String	所需维持保证金（SCALE_6）
shortfall	String	缺口 = mm_required − equity（SCALE_6）

11.2 getEstimatedLiquidationPrice

估算强平价（what-if，不修改状态）。

参数	类型	必填	精度	说明
symbol	String	是	—	交易对名
size	String	是	sz_decimals	仓位大小（signed decimal，正=多，负=空）
entry_price	String	否	px_decimals	入场价，默认用 mark
leverage	u32	是	—	杠杆倍数

响应 data：

字段	类型	说明
symbol	String	交易对名
size	String	假设仓位
entry_price	String	假设入场价
mark_price	String	当前标记价
leverage	u32	杠杆倍数
margin	String	所需保证金（SCALE_6）
liquidation_price	String?	强平价（px 精度）；null = 无法被强平

---

12. 检索/排行/监控

12.1 getTopAccounts

账户排行（有界全扫描 + 排序）。

参数	类型	必填	说明
sort_by	TopSortKey	是	"balance" 按余额 · "equity" 按权益
limit	usize	否	默认 50，最大 50

响应 data · TopAccountItem[]： address / balance(SCALE_6) / account_value(SCALE_6)

12.2 getAllOpenOrders

全局/按市场挂单列表。

参数	类型	必填	说明
symbol	String	否	不传查全局
offset	usize	否	默认 0
limit	usize	否	默认 100，最大 1000

响应 data： RestingOrderResponse[]（同 getAccountOrders 的 orders 项）

12.3 getTriggerOrders

查询账户的离线触发单列表。

参数	类型	必填	说明
address	Address20	是	账户地址
symbol	String	否	按市场过滤

响应 data · TriggerOrdersResponse： address + triggers: TriggerOrderResponse[]

TriggerOrderResponse：

字段	类型	说明
trigger_id	u64	触发单 ID
market_id	u32	市场 ID
symbol	String	交易对名
side	Side	"Bid" · "Ask"
order_type	TriggerOrderType	"market" · "limit"
qty	String	下单数量（sz 精度）
trigger_price	String	触发线（px 精度）
trigger_direction	TriggerDirection	"Above" · "Below"
limit_price	String?	限价（仅 limit，px 精度）
tif	TimeInForce	TIF
reduce_only	bool	仅减仓
client_order_id	String?	客户端订单 ID
created_at_block	u64	创建块高
created_at_ms	u64	创建时刻（毫秒）
expires_at_ms	u64?	过期时刻；null = 永不过期

12.4 getOcoPairs

查询账户的 OCO 组合单列表（含 Active / Resolved）。

参数	类型	必填	说明
address	Address20	是	账户地址
symbol	String	否	按市场过滤

响应 data · OcoPairsResponse： address + pairs: OcoPairResponse[]

OcoPairResponse：

字段	类型	说明
pair_id	u64	OCO pair ID
market_id	u32	市场 ID
symbol	String	交易对名
status	OcoStatus	"Active" · "Resolved"
legs	OcoLegs	腿 ID 引用（仅 id，腿详情经 getTriggerOrders/getAccountOrders 回查）
placed_at_block	u64	创建块高
client_pair_id	u64?	客户端 pair ID

---

13. Bootstrap

13.1 getBootstrap

一致性首屏聚合。单次 index.read() 同 height 保证一致性。

参数	类型	必填	说明
address	Address20	否	返回账户摘要
symbols	String[]	否	返回指定市场盘口
book_depth	usize	否	盘口每侧档数；0 = 全深度；默认 50

响应 data：

字段	类型	说明
markets	MarketListItem[]	市场列表（不含 Delisted）
account	AccountSummaryResponse?	账户摘要（提供 address 时返回）
books	Map<String, BookView>	symbol → 盘口（bids/asks/spread/state_hash）
action_meta	ActionsMetaResponse	39 Action 鉴权元数据

BookView：

字段	类型	说明
state_hash	Hex32	盘口状态哈希
bids	Level[]	买单档位
asks	Level[]	卖单档位
spread	String?	价差（px 精度）；任一侧空时 null