系统与约定

协议基础（JSON-RPC 信封、响应骨架、分页、公共约定）与系统端点（健康 / 状态 / 错误码 / 枚举 / 精度）。

主题	入口
错误码与 RejectReason	错误码
健康 / 状态 / 配置 / 限流 / 审计端点	系统端点
枚举 wire 编码	枚举速查
数值精度与地址格式	精度约定

2. JSON-RPC 2.0 信封

全部读写（除 GET /api/v1/health 和 REST 别名）走 JSON-RPC 2.0，统一入口 POST /api/v1/query 和 POST /api/v1/action。

2.1 请求格式

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getMarkets",
  "params": {}
}

字段	类型	必填	说明
jsonrpc	String	是	固定 "2.0"
id	any	是	请求标识，响应回显；可为 null
method	String	是	方法名，camelCase（读）或 PascalCase（写）
params	Object	否	方法参数，无参时可省略或传 {} / null

2.2 成功响应（读）

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "height": 12345,
    "chain_height": 12346,
    "stale": true,
    "data": { "symbol": "BTC-USDT", "mark_price": "97225.00" },
    "page": { "offset": 0, "limit": 100, "total": 243, "has_more": true }
  }
}

字段	类型	说明
result.height	u64	本包数据高度：热读=index 快照、历史分页=explorer 水印（不再恒等于链 tip）
result.chain_height	u64?	链 tip；height < chain_height 表示数据落后
result.stale	bool	height < chain_height（历史分页在 explorer 落后时置 true）
result.data	T	端点具体数据
result.page	Object?	仅分页端点：offset/limit(实际生效值)/total/next_cursor?/has_more?。total 可为 null——journal 扫描类端点（getRecentTrades/getAdminAuditLog 等）真实总量不可知；getUserFills / getOrderFills 读 fill archive，历史可全量查但 total 仍为 null

2.3 成功响应（写）

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tx_hash": "0xa1b2...",
    "height": 12346,
    "envelope_idx": 3,
    "signer": "0x1111222233334444555566667777888899990000",
    "nonce": 42,
    "action": { "PlaceOrder": { ... } },
    "status": "accepted",
    "events": [ ... ]
  }
}

详见 写操作响应格式。

2.4 错误响应

始终 HTTP 200，错误体现在 body：

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": { "code": -32004, "message": "market not found" }
}

字段	类型	说明
error.code	i32	错误码（见 §3）
error.message	String	人类可读描述
error.data	Value?	附加诊断信息（如 nonce 窗口值）

---

响应骨架

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

{
  "height": 12345,
  "chain_height": 12346,
  "stale": true,
  "data": { ... },
  "page": { "offset": 0, "limit": 100, "total": 243, "has_more": true }
}

字段	类型	说明
height	u64	本包数据高度（热读=index、历史=explorer 水印）
chain_height	u64?	链 tip（历史分页可能高于 height）
stale	bool	height < chain_height
data	T	端点具体数据
page	Object?	仅分页端点出现（见 §3）；含 next_cursor?/has_more?。非分页端点省略此字段

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

---

分页约定

分页端点统一使用：

请求参数（在 params 内）：

参数	类型	默认	说明
offset	usize	0	偏移量
limit	usize	端点特定	返回条数上限
cursor	String?	无	keyset 游标（getRecentTrades 等）：优先于 offset，返回严格晚于游标的条目

响应 page 对象：

字段	类型	说明
offset	usize	请求的 offset
limit	usize	实际生效值（取 min(请求值, 系统上限)）
total	usize?	总条数。index 扫描端点有值；journal 扫描端点（getRecentTrades/getAdminAuditLog）为 null；fill archive 端点（getUserFills/getOrderFills）历史可全量查但 total 仍为 null
next_cursor	String?	下一页 keyset 游标（has_more=true 时提供；传给下一次请求的 cursor）
has_more	bool?	是否还有下一页

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

---

公共约定

分页参数

参数	类型	说明
offset	number	起始偏移，默认 0
limit	number	页大小（各接口有独立默认值和上限）

区块、交易列表按时间新→旧；K 线按 bucket 时间旧→新。

地址与哈希

• 账户 / 签名者地址：0x 前缀十六进制
• 交易 hash、区块 digest：0x 前缀十六进制
• 路径 {id}：数字高度（12345）或 digest（0xabc…）；部分接口仅支持高度

Symbol 解析

• 索引接口（fills、events 等）：通过 market_id 在内存 market cache 中解析 symbol；未知市场时 symbol 为 null 或省略。
• 实时行情 / K 线：见 只读行情 分组；symbol 解析规则见 实时行情 §2。

事件溯源（Event provenance）

凡由链上 event 物化或过滤的列表项，均可关联回产生该 event 的 L2 envelope（已签名交易）：

字段	类型	说明
envelope_idx	number | null	事件所在区块内的 envelope 索引（0-based）
tx_hash	string | null	产生该 event 的 L2 交易 hash（0x…），可跳转 GET /api/v1/tx/{hash}

适用接口：/fills、/fund-flows、/bridge-flows、/positions、/account/events、/referral/events、/rebate/events，以及区块 /blocks/{id}/events。

语义说明

• 对成交、资金流水、持仓变动等，tx_hash 指向触发该 event 的 envelope。例如 maker 侧的手续费流水，其 tx_hash 通常是对手方 taker 提交的交易，而非 maker 自己的挂单交易。
• 对 /orders（按 order_id 聚合），使用 placed_tx_hash（下单）与 closed_tx_hash（终态：撤单/过期/完全成交），由 derive worker 在索引时写入。
• 对 /bridge-flows，external_tx_hash 为 event body 中的 L1 链上 hash（如充值/提现结算）；tx_hash 仍为 L2 envelope hash。

---

6. 批量请求（读 only）

POST /api/v1/query 支持 JSON 数组形式的批量请求：

[
  {"jsonrpc": "2.0", "id": 1, "method": "getMarkets"},
  {"jsonrpc": "2.0", "id": 2, "method": "getAccount", "params": {"address": "0x..."}}
]

• 逐项独立处理、各自快照（独立 index.read()）
• 返回逐项 result/error 的数组
• 一个子请求失败不拖垮整批
• 需要跨端点一致性读（同一 height）→ 用 getBootstrap

POST /api/v1/action 禁止 batch。

---