做市商对接指南

本文档是 做市商程序化接入的总览：说明单一节点上交易、行情与历史接口如何分工、推荐接入顺序，以及运行期状态机与对账约定。
不包含 msgpack / EIP-712 等签名实现细节——见 签名与鉴权。协议字段以交易与账户 · 历史与审计分册为准。

阅读路径

顺序	文档	内容
0	官方 SDK（可选）	Rust / Java 客户端，封装读写、签名与 WS
1	本页	架构、接入清单、WS/nonce、对账
2	签名与鉴权	环境参数、Agent、L1 msgpack、User-Signed
3	WebSocket	12 个推送主题
4	write-actions · 读方法分册	45 写 / 46 读 schema
5	读侧 schemas	历史字段契约

官方 SDK

语言	仓库
Rust	auroran-sdk-rust
Java	auroran-sdk-java

推荐使用 SDK 完成 Agent 注册、L1 签名、下单与 WebSocket 订阅；自行实现时以签名与鉴权为准。

1. 单节点 API 分工

交易、行情与历史接口由同一节点、同一 Base URL 提供，按「契约族」分组。对外差异见 接口变更清单。

契约族	路径	响应包装
链读写（JSON-RPC + 别名）	`POST /api/v1/query` · `/api/v1/action` · `GET /api/v1/health` · `GET /api/v1/markets/{symbol}` · `/api/v1/orderbook/{symbol}` · `/api/v1/stats`	`{height, data, page?}`
热读行情	`/api/v1/market/orderbook/{symbol}` · `/api/v1/market/trades/{symbol}` · `/api/v1/bbos` · `/api/v1/marks` · `/api/v1/markets` · `/api/v1/markets/{symbol}/summary`	扁平热读 `{chain_height, book_updated_at_ms, stale, ready, data}`
历史检索	`/api/v1/blocks` · `/api/v1/fills` · `/api/v1/orders` · `/api/v1/fund-flows` · …	`{data, page}`
WebSocket	`GET /api/v1/ws`	`op` / `topics` 订阅制（链主题 + 读侧主题同一连接）

流量划分（做市日常）

走链读写（query / action / WS）	走读侧 REST
下单 / 撤单 / 改杠杆 / Agent 注册	日终 / 长周期成交、委托、流水对账
当前账户、挂单、nonce	区块 / 交易分页浏览（审计）
市场列表（含 lifecycle）、冷启动 `getBootstrap`	K 线、排行榜
成交 `getUserFills` / 增量 / 单笔 archive	含 PnL 归因的聚合视图 `GET /fills` 等
终态订单 `getOrderStatus`（点查）	历史委托 `GET /orders`
全部 WebSocket 交易推送	公开行情 WS（`book.` / `trades.` / `bbo.` / `marks` / `candles.`）

原则

程序化交易 / 做市：默认走 链读写（POST /api/v1/query、/action、WS）。写、签名、实时读、交易推送均在此。
读侧 REST：历史索引、对账、K 线、排行榜、区块浏览、实时行情网关；对账前读 GET /api/v1/status 确认 derive_lag_blocks 与 hot_feed。
路径同名 ≠ 等价：同一主机上 /markets、/bbos、/marks、/markets/{symbol}/summary 为热读包装（非链骨架），/chain/* 为链读代理——见下节对照表与变更清单 §3.3。

1.1 一条规则（避免选错）

对接交易系统的默认答案：链读写（query / action / WS）。 只有明确需要「历史分页 / 索引聚合 / 对账 / K 线 / 读侧展示」时，才调用读侧 REST。

1.2 重叠路径：契约族与选型

合并后只有一个主机，同名路径的归属是固定的；做市商按「应选」列接入即可。

能力	同一节点上的路径	做市商应选
市场列表	`POST /query getMarkets`（含 `lifecycle`、`mark_price` 等完整字段） vs `GET /api/v1/markets`（热读四字段）	`getMarkets`
盘口 / BBO / Mark / Summary	`getOrderbook` / `getAllBBOs` / `getAllMarks` / `getMarketSummary`（query 或链别名） vs `/market/orderbook/{symbol}` · `/bbos` · `/marks` · `/markets/{symbol}/summary`（热读包装）	query（做市主路径）；热读包装给展示 / 第三方
冷启动	`getBootstrap`（markets + books + account 一次拉齐）	query
当前账户	`getAccount` vs `GET /api/v1/chain/account`（读侧代理，`{height,data}`）	`getAccount`
保证金 / 杠杆偏好	`getMarketSettings`	query
当前挂单	`getAccountOrders` · WS `orderUpdates` vs `GET /api/v1/chain/open-orders`（代理）	query / WS
实时成交	WS `userFills` · `getUserFillsSince` · `getUserFills` / `getOrderFills`	query / WS
订单状态 / 终态	`getOrderStatus`（点查） vs 历史委托 `GET /orders`	query（点查）；历史用 `/orders`
历史成交（PnL 归因）	`GET /api/v1/fills`（含 `realized_pnl` / `position_action`）	读侧（对账）
历史委托	`GET /api/v1/orders`（默认不含 open）	读侧
写操作 / 签名	`POST /api/v1/action`	唯一写入口
WebSocket 交易推送	`/api/v1/ws`：`account.` / `userFills.` / `orderUpdates.` / `triggerUpdates.`	统一 WS
WebSocket 公开行情 / K 线	`/api/v1/ws`：`book.` / `trades.` / `bbo.` / `marks` / `candles.`	同一连接追加订阅
区块 / 交易检索	`getBlock` / `getTx`（权威） vs `/blocks` · `/envelopes` · `/tx`（可分页索引）	验 tx / 热路径 query；审计浏览读侧
索引是否追平	`GET /api/v1/status`	读侧（对账前必读）

为何读侧也有 /api/v1/markets？
供展示/行情网关用（热读四字段）。不能替代 getMarkets：缺少 lifecycle / emergency_halt / 标记价等下单前必查字段。

为何读侧有 /chain/account？
供前端应用读链上快照；做市系统直连 getAccount，少一跳、响应形态与 getAccount 一致。

1.3 按场景速查

场景	用
启动：拉市场 + 订单簿 + 账户	Chain `getBootstrap` 或 `getMarkets` + `getOrderbook` + `getAccount`
运行：下单 / 维护挂单	Chain `POST /action` + WS
日终 / 长周期对账	读侧 `GET /fills` · `/orders` · `/fund-flows`（且 `derive_lag_blocks==0`）
看 K 线 / 排行榜 / 实时行情	读侧 K 线 · 实时行情
不确定	先链读写 query；只有读侧独有的能力（历史 / K 线 / 排行）才用读侧 REST

2. 接入流程总览

步骤	动作	文档
1	确认 `chain_id` / `network_tag` 等	签名 §2
2	Master `RegisterAgent`（授予 Trader）	签名 §4
3	Agent 私钥 + L1 通道签名交易 Action	签名 §5
4	`getBootstrap`（markets / books / account）	账户与订单 — getBootstrap
5	WS：`book.` · `bbo.` · `orderUpdates.{addr}` · `userFills.{addr}` · `account.{addr}`	websocket
6	`PlaceOrder` / `BatchPlaceOrder`	write-actions §5
7	本地挂单以 `orderUpdates` 为准，断线后 `getAccountOrders` 校正	本页 §5
8	Chain `getUserFillsSince` 增量对账；需 PnL 归因时用读侧 `GET /fills`（`derive_lag_blocks==0`）	本页 §6

启动前探测

GET …/api/v1/health → status: ok
getExchangeConfig → action_version: 2
getMarkets → 目标 symbol 为 Active
getAccount → 记录 nonce

3. 保证金与字段口径

下单 admission 不要用 withdrawable（含 uPnL 的展示值）。

场景	链上口径字段
Cross 开仓 / 加仓	`cross_trading_available`
提现 / 划逐仓 / reduce_only	`cross_cash_available`

完整表格见 write-actions §7.0。

4. Nonce 与重试

链上规则（默认 window = 64）：

有效 nonce：[getAccount.nonce, getAccount.nonce + window)，窗口内可乱序到达
同一 nonce 不可重复；kept-reject 也消耗 nonce
超出窗口 / 重放 → NONCE_REPLAY

客户端建议：

本地 单调分配 nonce（从 getAccount.nonce 起，每笔 +1，不跳号、不复用）
可在窗口内 并发在途（不必串行等 HTTP 200）
POST /action 禁止 batch

响应	处理
`accepted`	从 `events` 取 `order_id`
`kept-reject`	勿重发同一 nonce；修正参数后用下一 nonce
`NONCE_REPLAY`	`getAccount` resync
HTTP 超时	`getTx` / WS 判断是否已落链后再决定

详见交易与账户 §4.3 · precision §5（reason 为 raw i128）。

5. 订单与 WebSocket 状态机

5.1 `orderUpdates.{address}`

`kind`	动作
`accepted`	意图确认（尚无完整 cloid）
`resting`	按 `order_id` upsert
`done` / `expired`	删除

IOC/FOK/全成可能无 resting。改价 crossing 时同块可出现 done → resting → userFills。

5.2 `client_order_id`

建议 per (owner, symbol) 唯一。
WS 仅在 resting 帧携带 cloid。

5.3 改单

部分市场可直接挂簿；部分市场依赖 oracle quote，无可用报价时返回 QuoteNotAvailable。
批量改单：BatchModify；批量撤单：MassCancel（Owner / Side / Ids）；上限见 write-actions §5.4 / §6.3。

6. 对账：链实时数据 ↔ 读侧历史

6.1 数据源

需求	用
实时成交	WS `userFills`
增量轮询（推荐）	Chain `getUserFillsSince`（cursor 旧→新）
全量 / 时间窗分页	Chain `getUserFills`（fill archive）
单笔订单 fill 明细	Chain `getOrderFills`（`order_id` 或 `address`+`symbol`+`client_order_id`）
订单汇总（filled / avg / 终态）	Chain `getOrderStatus`（closed 永久 archive；open 无 journal 扫描）
PnL 归因 / 日终聚合	读侧 `GET /fills`（`derive_lag_blocks→0`）
当前挂单	WS `orderUpdates` · Chain `getAccountOrders`
历史委托	读侧 `GET /orders`（默认不含 open）

6.2 成交字段映射（摘要）

语义	Chain WS	读侧 `FillRecord`
块高 / 序	`block_height`, `event_seq`	`height`, `seq`
时间戳	`timestamp_ms`	—
价量费	`price`, `qty`, `fee`	同左
市场 / 订单	`symbol`, `order_id`, `client_order_id`	`order_id`, `symbol`
已实现 PnL	—	`realized_pnl`, `position_action`

完整映射与 derive 规则见读侧 FillRecord。

6.3 索引新鲜度

GET {node}/api/v1/status

derive_lag_blocks == 0 → 成交/委托/流水可對账。
stats_lag_blocks == 0 → account-stats / 排行榜可信。

7. 运维约定

主题	约定
Chain JSON-RPC	错误亦 HTTP 200；看 body
读侧 REST 缺参	多数 500（非 400）
WS 断连	重订阅 + `getBootstrap` / `getAccountOrders` 校正
HTTP 限流	文档未承诺 QPS；参考 `getUserRateLimit`（index 滑动窗口，信息性）

8. 文档索引

主题	链接
官方 SDK（Rust / Java）	§官方 SDK
签名 / Agent / msgpack	signing
JSON-RPC / 错误码	系统与约定
45 Action schema	write-actions
46 读方法	读方法分册 · 行情/历史读方法
WS 协议	websocket
读侧契约	schemas

阅读路径​

官方 SDK​

1. 单节点 API 分工​

1.1 一条规则（避免选错）​

1.2 重叠路径：契约族与选型​

1.3 按场景速查​

2. 接入流程总览​

3. 保证金与字段口径​

4. Nonce 与重试​

5. 订单与 WebSocket 状态机​

5.1 orderUpdates.{address}​

5.2 client_order_id​

5.3 改单​

6. 对账：链实时数据 ↔ 读侧历史​

6.1 数据源​

6.2 成交字段映射（摘要）​

6.3 索引新鲜度​

7. 运维约定​

8. 文档索引​