Chain API Reference

JSON-RPC 2.0 over HTTP · 37 读方法 + 39 写 Action + 7 REST 别名 + 10 WS 主题所有数值字段输出 canonical decimal string（ADR-0026）基准 HEAD bfb4137 · 2026-06-14

文档导航

文档	内容
概述（本页）	JSON-RPC 信封、错误码、Envelope 签名、鉴权体系
读方法	健康检查、REST 别名、37 个 JSON-RPC 读方法
写操作	39 个 Action 参数 schema、EIP-712 签名、响应格式
WebSocket	连接协议、10 个推送主题、推送帧格式
事件投影	7 个事件域、全部变体及字段
枚举速查	枚举类型 wire 编码及取值
数值精度	Decimal String、地址类型、分页约定

服务端点

环境	Base URL
生产（链层）	`https://rpc.auroran.io`
本地开发	以链节点部署配置为准

用途	方法	完整 URL
读（JSON-RPC）	POST	`https://rpc.auroran.io/api/v1/query`
写（JSON-RPC）	POST	`https://rpc.auroran.io/api/v1/action`
健康检查	GET	`https://rpc.auroran.io/api/v1/health`
WebSocket	GET → WS	`wss://rpc.auroran.io/api/v1/ws`

浏览器与历史索引接口见 Explorer API（https://api.auroran.io），与本页 Chain API 为不同产品线。

1. 入口路由

路由	方法	用途	Batch
`POST /api/v1/query`	POST	读（37 个 QueryMethod）	支持
`POST /api/v1/action`	POST	写（39 个 ActionKind）	禁止
`GET /api/v1/health`	GET	裸 REST 存活探针	—

另有 7 个 REST 缓存别名和 1 个 WebSocket 入口 GET /api/v1/ws。

2. JSON-RPC 2.0 信封

全部读写（除 GET /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,
    "data": { "symbol": "BTC-USDT", "mark_price": "97225.00" },
    "page": { "offset": 0, "limit": 100, "total": 243 }
  }
}

字段	类型	说明
`result.height`	u64	index 快照高度标签（非版本选择器）
`result.data`	T	端点具体数据
`result.page`	Object?	仅分页端点：`offset`/`limit`(实际生效值)/`total`。`total` 可为 `null`——journal 扫描类端点（getRecentTrades/getUserFills/getAdminAuditLog 等）真实总量不可知

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 窗口值）

3. 错误码

3.1 JSON-RPC 标准错误

码	名称	含义
`-32700`	PARSE_ERROR	JSON 解析失败
`-32600`	INVALID_REQUEST	非对象 / jsonrpc≠"2.0" / 写路由 batch / 空 batch
`-32601`	METHOD_NOT_FOUND	未知方法
`-32602`	INVALID_PARAMS	参数非法（缺字段 / 类型错 / 格式错 / 资源不存在）
`-32603`	INTERNAL_ERROR	Journal / IO / 序列化异常

3.2 zepto-chain 自定义错误

码	名称	含义
`-32000`	SERVER_BUSY	背压 / state actor 不可用 / 链已停机
`-32001`	NONCE_REPLAY	Nonce 重放或不在窗口（`error.data` 含 `account_nonce/got/window`）
`-32002`	LEADER_UNREACHABLE	Follower 无法连接 Leader
`-32003`	LEADER_TIMEOUT	Follower 请求 Leader 超时
`-32004`	RESOURCE_NOT_FOUND	资源不存在（well-formed 参数指向的市场/订单/仓位等解析不到；例外：`getAccount` 对从未出现的合法地址返回零值壳，不抛此码）。REST 别名映射 404
`-32010`	AUTH_FAILED	签名/agent/权限不足（`error.data` 含 `reason: RejectReason`）

3.3 RejectReason 枚举（kept-reject 的业务拒因）

写操作在 auth 通过但业务校验失败时返回 status: "kept-reject"，result.reason 为以下变体之一（externally-tagged JSON）：

RejectReason 变体	含义	携带字段
`InsufficientBalance`	余额不足	`required`(raw i128), `have`(raw i128)
`ChainIdMismatch`	envelope.chain_id 不匹配	—
`UnsupportedActionVersion`	action_version 不支持	当前仅支持 `2`
`SignerNotFound`	signer 对应账户不存在	—
`NonceMismatch`	nonce 不在窗口内	`account_nonce`, `got`, `window`
`BadMasterSignature`	secp256k1 签名 verify 失败	—
`AgentNotRegistered`	agent 地址未在 master 账户注册	—
`AgentExpired`	agent 委托已过期	`expires_at_ms`
`AgentRoleMissing`	agent 缺少所需角色	—
`MasterOnlyAction`	该 Action 只允许 master 直签	—
`AccountRoleMissing`	签名者缺少所需角色	—
`SymbolNotFound`	action 中的 symbol 不存在	—
`MarketNotFound`	market_id 解析不到	—
`MarketNotActive`	市场非 Active 状态	—
`AccountNotFound`	target 账户不存在	—
`PriceNonPositive`	限价 ≤ 0	—
`QtyNonPositive`	数量 ≤ 0	—
`DecimalPrecisionExceeded`	decimal string 超精度或非法格式	—
`PriceQtyOverflow`	价量乘法溢出	—
`NotionalOverflow`	名义值溢出	—
`FeeOverflow`	手续费溢出	—
`PostOnlyRejected`	PostOnly 单会立即成交	—
`FokRejected`	FOK 无法完全成交	—
`MarketEmergencyHalt`	市场处于紧急熔断	—
`PositionNotFound`	无对应持仓	—
`ReduceOnlyRejected`	reduce_only 单会增加净持仓	—
`DuplicateLiveOrderId`	order_id 重复	—
`EventBudgetExceeded`	单笔交易事件数超限	—
`BatchSizeExceeded`	批量操作子项数超限	—
`InvalidCommand`	matcher 引擎拒收	—
`SelfReferral`	不能绑定自己的推荐码	—
`ReferralAlreadyBound`	已绑定推荐码（只能绑一次）	—
`ReferralCodeTaken`	推荐码已注册	—
`GtdExpiryInPast`	GTD 过期时刻在过去	—
`TriggerPriceInvalid`	触发价非法	—
`OcoLegCountInvalid`	OCO 腿数非法	—

注意：result.reason 中的数值字段为 raw i128（整型），未做 decimal 投影。同一笔交易中 result.events[] 内的对应 Rejected 事件已经过 ADR-0026 投影为 decimal string。

4. 签名信封（SignedActionEnvelope）

所有写操作 body 的 params 格式为：

{
  "envelope": {
    "chain_id": 1,
    "domain_chain_id": 1,
    "action_version": 2,
    "nonce": 42,
    "signer": "0x1111222233334444555566667777888899990000",
    "credential": {
      "Secp256k1": {
        "signature": [27, 95, 83, 94, ...]
      }
    },
    "action": {
      "PlaceOrder": {
        "owner": "0x1111222233334444555566667777888899990000",
        "symbol": "BTC-USDT",
        "side": "Bid",
        "limit_price": "97100.00",
        "qty": "1.00000",
        "tif": "Gtc",
        "reduce_only": false
      }
    }
  }
}

4.1 Envelope 字段

字段	类型	说明
`chain_id`	u64	Zepto 链标识（来自 `ChainConfig.chain_id`）。auth 层校验 `envelope.chain_id == 节点 chain_id`，不匹配 → `ChainIdMismatch`。防跨 Zepto 网络重放（如 Mainnet envelope 不可在 Testnet 重放）
`domain_chain_id`	u64	EIP-712 domain 的 chainId。User-Signed 操作（WithdrawRequest/RegisterAgent/RevokeAgent）的钱包 `eth_signTypedData_v4` 签名的 domain 中 `chainId` 取此值——必须与用户钱包当前连接的 EVM 网络 ID 一致。L1 通道操作此字段仅参与 txid 计算，与签名无关
`action_version`	u32	Wire 协议版本，当前固定 `2`
`nonce`	u64	账户 nonce，必须严格单调递增（见 §4.4）
`signer`	Address20	签名者的 master 账户地址（20 字节 hex，`0x` 前缀）。不参与签名 digest
`credential`	SigCredential	签名凭证 `{"Secp256k1": {"signature": [byte, ...]}}`。65 字节 secp256k1 签名（`v
`action`	Action	具体操作（externally-tagged，变体名 = 写 method 名）

4.2 `chain_id` 与 `domain_chain_id`

两个字段语义不同，各自服务于不同的安全边界：

chain_id — Zepto 链网络标识。由链部署方在 ChainConfig.chain_id 中设定。用途：

auth 层校验 envelope.chain_id == 节点 chain_id，防跨 Zepto 网络重放（Mainnet ↔ Testnet）
L1 通道签名中的 EIP-712 domain chainId 参数
公共交易标识 txid 的输入

domain_chain_id — EIP-712 domain 中钱包可见的 chainId。User-Signed 操作（WithdrawRequest/RegisterAgent/RevokeAgent）的钱包签名时，钱包会校验 typed data 中 domain.chainId 是否匹配当前连接的 EVM 网络——不匹配则拒绝签名或显示警告。此值应设为用户钱包所在 EVM 网络的 chain ID（如 Ethereum Mainnet = 1、BSC = 56）。这就是 domain_chain_id 独立于 chain_id 存在的原因。

对于 L1 通道操作（非 User-Signed 的 36 个 Action），domain_chain_id 仅参与 txid 计算，不参与签名。通常设为与 chain_id 相同的值即可。

总结：

场景	`chain_id`	`domain_chain_id`
L1 通道（36 个 Action）	Zepto 链 ID	与 `chain_id` 相同（仅 txid 用到）
User-Signed（3 个 Action）	Zepto 链 ID	用户钱包的 EVM 链 ID（如 1、56、42161）

network_tag（又称 source）来自 ChainConfig.signing_network_tag，是 L1 签名路径中 phantom EIP-712 类型 L1Action(string source, bytes32 connectionId) 的 source 字段值（如 "Mainnet"）。对接方应从节点运维方获取。

当前 API 不提供查询 chain_id、domain_chain_id 或 network_tag 的端点。这些值是链级配置，由部署方在启动时注入。如无法获取，联系节点运维方。

4.3 Nonce 管理

nonce 从 0 开始，每次成功提交（含 kept-reject）严格 +1
不允许跳号：提交 nonce=N 时，链上期望 account_nonce == N
不匹配且超出容忍窗口 → NONCE_REPLAY（-32001），error.data 返回 {"account_nonce": X, "got": Y, "window": W}
建议：对接方先调 getAccount 获取当前 nonce，再基于该值构造交易。对并发提交场景，按 nonce 递增依次发送，收到回执后再发下一笔

4.4 Credential 格式

当前仅支持 secp256k1 单通道签名：

"credential": {
  "Secp256k1": {
    "signature": [27, 95, 83, 94, ...]
  }
}

signature 是 65 字节 JSON 数组（非 hex 字符串），格式为 v || r || s，其中 v ∈ {27, 28}（recovery id）。r 和 s 各 32 字节大端。与 eth_signTypedData_v4 等以太坊签名工具的字节输出一致。

4.5 鉴权通道

recover 出的地址 == envelope.signer → master 直签。 recover 出的地址 ≠ envelope.signer → 在 signer 账户的 agents 列表中按地址查找 → agent 委托签名。

通道	适用场景	签名 key
Master 直签	Admin / 敏感操作 / 低频用户	master 的 secp256k1 私钥
Agent 委托	程序化做市 / 高频交易	已注册的 API-wallet secp256k1 私钥

Agent 必须由 master 经 EIP-712 通道（RegisterAgent）预先授权，指定角色子集和过期时间。

4.6 签名算法

所有 39 个 Action 均走 EIP-712 签名。根据不同 Action，分为两个通道：

L1 通道（36 个交易/管理操作）

适用于除 WithdrawRequest、RegisterAgent、RevokeAgent 外的全部 Action。

L1 通道使用 phantom EIP-712 类型 L1Action(string source,bytes32 connectionId)，其构造分 3 步：

Step 1 — 计算 connectionId：

msgpack_bytes = rmp_serde::to_vec_named(action)
connectionId  = keccak256(msgpack_bytes || nonce.to_be_bytes(8))

对 action 对象做 msgpack 序列化（rmp_serde named map 模式），得到确定性字节串
拼接 nonce 的 8 字节大端表示
对整体求 keccak256，得到 32 字节 connectionId

msgpack 编码细节（确定性保证，跨语言可复现）：

i128 → msgpack 定长整数
Option::None → msgpack nil
Enum → msgpack map（外部 tag，key 为变体名字符串）
Address20 → msgpack 20 字节 bin
String → msgpack str
bool/u32/u64 → 对应 msgpack 类型

Step 2 — EIP-712 domain + struct hash：

domain = keccak256(
    typeHash("EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)")
    || enc_string("ZeptoSignTransaction")
    || enc_string("1")
    || enc_uint(chain_id)
    || enc_address(0x0000...0000)
)

struct_hash = keccak256(
    typeHash("L1Action(string source,bytes32 connectionId)")
    || enc_string(network_tag)
    || connectionId
)

typeHash(s) = keccak256(utf8_bytes(s))
enc_string(s) = keccak256(utf8_bytes(s))
enc_uint(v) = 32 字节大端，高位补零
enc_address(a) = 左侧补 12 个零字节，右对齐 20 字节地址

Step 3 — EIP-712 最终摘要：

digest = keccak256(0x19 || 0x01 || domain || struct_hash)

Step 4 — 签名：

对上述 32 字节 digest 做 secp256k1 recoverable 签名，得到 65 字节 [v, r_0..r_31, s_0..s_31]（v ∈ {27, 28}），填入 credential.Secp256k1.signature。

EIP-712 通道（WithdrawRequest / RegisterAgent / RevokeAgent）

走标准 eth_signTypedData_v4，由钱包直接构造 typed data 并签名。domain 与 L1 通道相同（ZeptoSignTransaction），但 primary type 按 Action 不同。typed data 结构和 domain JSON 见写操作 - EIP-712 签名。

SDK 构造参考：zepto_sdk::envelope（off-chain 独立 crate）封装了上述签名流程。建议对接方优先使用 SDK；如需自行实现，务必使用 msgpack 而非 JSON 序列化 action。

公共交易标识 txid

响应中的 tx_hash 是公共交易标识（txid），与签名彻底解耦。同一笔交易无论由 master 还是 agent 签名，txid 相同。其计算独立于签名 digest：

txid = SHA-256(
    b"zepto-txid-v1"       // domain-separation 标签
    || chain_id            // u64 BE (8 bytes)
    || domain_chain_id     // u64 BE (8 bytes)
    || action_version      // u32 BE (4 bytes)
    || nonce               // u64 BE (8 bytes)
    || signer              // 20 bytes raw address
    || SHA-256(msgpack(action))
)

注意：txid 使用 SHA-256 和 domain_chain_id，而签名 digest 使用 keccak256 和 EIP-712 结构。两者算法不同，不可混淆。

5. 鉴权体系

5.1 Action 鉴权一览

Action	鉴权通道	所需角色
PlaceOrder / CancelOrder	master_or_agent_with_role	Trader
BatchPlaceOrder	master_or_agent_with_role	Trader
AmendOrder / BatchModify / MassCancel / ClosePosition / ScheduleCancel	master_or_agent_with_role	Trader
SetLeverage / SetMarginMode / SetIsolatedMargin	master_or_agent_with_role	Trader
PlaceTriggerOrder / CancelTriggerOrder	master_or_agent_with_role	Trader
PlaceOco / CancelOco	master_or_agent_with_role	Trader
SetReferrer / RegisterReferrer	master_or_agent_with_role	Trader
SubmitOracleQuote / BatchSubmitOracleQuote	master_or_agent_with_role	Quoter
Liquidate	master_or_agent_with_role	Liquidator
RecordDeposit / CreditDeposit	master_or_agent_with_role	SettlementOperator
WithdrawSettle / WithdrawRefund	master_or_agent_with_role	SettlementOperator
SetSettlementPaused	master_or_agent_with_role	Admin
SetUserFeeRate	master_or_agent_with_role	Admin
CreateMarket / ActivateMarket / HaltMarket / ResumeMarket	master	—
RequestDelist / CompleteDelist	master	—
SetFeeRecipient / AmendMarketConfig / SetEmergencyHalt	master	—
SetAccountRole	master	—
WithdrawRequest	user_signed_master (EIP-712)	—
RegisterAgent / RevokeAgent	user_signed_master (EIP-712)	—

5.2 角色位掩码

角色	位值	说明
Trader	1	下单、撤单、改单、保证金管理
OracleOperator	2	保留
SettlementOperator	4	Bridge 充提操作
Admin	8	闸门、费率管理
Liquidator	16	清算执行
Quoter	32	预言机报价提交

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。

7. 服务端行为

行为	值
写路由超时	同步 admit-execute，Leader 在共识轮次内返回
HTTP 状态码	错误亦返回 HTTP 200（JSON-RPC 规范），`GET /health` 除外（200=ok, 503=halted）
Journal 扫描窗口	最多回溯 10,000 块（getRecentTrades / getUserFills / getAdminAuditLog / getCandles / getOrderStatus / getUserRateLimit）
单块最大交易数	`max_tx_per_block`（见 `getExchangeConfig`）
Action 版本	当前 `action_version: 2`

文档导航​

服务端点​

1. 入口路由​

2. JSON-RPC 2.0 信封​

2.1 请求格式​

2.2 成功响应（读）​

2.3 成功响应（写）​

2.4 错误响应​

3. 错误码​

3.1 JSON-RPC 标准错误​

3.2 zepto-chain 自定义错误​

3.3 RejectReason 枚举（kept-reject 的业务拒因）​

4. 签名信封（SignedActionEnvelope）​

4.1 Envelope 字段​

4.2 chain_id 与 domain_chain_id​

4.3 Nonce 管理​

4.4 Credential 格式​

4.5 鉴权通道​

4.6 签名算法​

L1 通道（36 个交易/管理操作）​

EIP-712 通道（WithdrawRequest / RegisterAgent / RevokeAgent）​

公共交易标识 txid​

5. 鉴权体系​

5.1 Action 鉴权一览​

5.2 角色位掩码​

6. 批量请求（读 only）​

7. 服务端行为​