API Schemas（完整数据契约）

本文档是历史与审计分册的权威 Schema 参考。对接方无需阅读服务端源码；所有 REST / WebSocket 响应字段、类型、枚举与端点映射均在此定义。

接口行为（分页默认值、过滤语义、示例）见 REST API；WebSocket 协议见 WebSocket。

接口行为见 REST API；WebSocket 见 WebSocket。

1. 全局约定

1.1 Base URL

Item	Value
Default（生产）	`https://rpc.auroran.io` · `https://api.auroran.io`（功能一致，任选其一）
Auth	无（公开只读 API，无 API Key）
Content-Type	成功响应均为 `application/json`

1.2 地址与哈希

类型	格式
账户 / 签名者	`0x` + 十六进制
交易 hash / 区块 digest	`0x` + 十六进制
路径 `{id}`（区块）	数字高度或 digest
路径 `{hash}`（交易）	交易 hash

1.3 数值与 decimal

规则	说明
价格、数量、余额、手续费、成交量	JSON string（decimal），不是 number
区块高度、序号、时间戳 ms	JSON number（整数）
`market_id`、`order_id`	JSON number（整数）

1.4 可选字段与 JSON 省略

服务端使用 skip_serializing_if：值为 null 或未设置的 optional 字段可能从 JSON 中完全省略（不出现 "field": null）。对接方应将所有未在「必填」列标注为 yes 的字段视为 optional，缺失时等价于 null。

1.5 事件溯源（Event provenance）

由链上 event 物化的记录，可通过 (height, seq) 关联回产生该 event 的 L2 envelope（已签名交易）：

(height, seq) → event.envelope_idx → envelope.tx_hash

字段	类型	说明
`envelope_idx`	`number \| omitted`	区块内 envelope 索引（0-based）
`tx_hash`	`string \| omitted`	产生该 event 的 L2 交易 hash

语义：maker 手续费等流水的 tx_hash 可能是对手方 taker 交易，不一定是本账户自己的挂单 tx。

订单聚合（OrderRecord）不使用 event 溯源字段，而使用 placed_tx_hash / closed_tx_hash（derive 时写入）。

跨链流水（BridgeFlowRecord）额外有 external_tx_hash（L1 链上 hash，来自 event body）。

1.6 排序

接口	排序
blocks、envelopes、fills、fund-flows、bridge-flows、positions、account/events、referral/events、referral/referees、rebate/events	区块高度新→旧
block `{id}/events`	区块内 `seq` 小→大
orders	默认仅已关闭订单；按 `closed_at_ms` 新→旧（同时间 `order_id` 大→小）
candles	bucket 时间旧→新
referral/leaderboard	邀请人数多→少（`n_referrals` desc）

1.7 索引延迟

节点内异步流水线：ingest → derive → candle → stats。账户历史与排行榜依赖 derive/stats，可能落后于链 tip。对接方应读取 GET /api/v1/status 中的 *_watermark 与 *_lag_blocks 判断数据新鲜度。

2. 公共包装类型

Page

分页元数据。

Field	Type	Required	Description
`offset`	`number`	yes	本次请求偏移
`limit`	`number`	yes	本次请求页大小
`total`	`number`	no	精确总数；仅 `include_total=true` 时返回（leaderboard 上限 500）
`next_cursor`	`string \| null`	no	游标模式下一页游标；offset 模式为 `null`
`has_more`	`boolean \| null`	no	游标模式是否还有下一页；offset 模式为 `null`

Paged<T>

{ "data": [ /* T[] */ ], "page": { "offset": 0, "limit": 50, "total": 100, "next_cursor": null, "has_more": null } }

DataOnly<T>

{ "data": { /* T */ } }

ErrorResponse

{ "error": "human-readable message" }

HTTP	场景
`400`	`POST /info` 未知 `type`；`GET /api/v1/leaderboard` 无效 `metric`/`period`；`GET /api/v1/rebate/events` 无效 `role`（均为 JSON `{ "error" }`）
`404`	区块、交易不存在；`GET /api/v1/candles` symbol 不在 market cache；热读未知 symbol
`503`	实时行情 Feed seeding（`Retry-After: 2`，JSON `{ "error" }`）
`500`	存储错误；缺少必填 query 参数（当前实现，非标准 400）

HealthResponse

GET /health

Field	Type	Required	Description
`status`	`string`	yes	恒为 `"ok"`

ExplorerStatus

GET /api/v1/status

Field	Type	Required	Description
`watermark`	`number \| null`	yes	已完全 ingest 的最高区块；首块前为 `null`
`block_count`	`number`	yes	本地区块总数
`node_tip`	`number \| null`	yes	链节点 tip；不可达为 `null`
`behind`	`number \| null`	yes	落后区块数
`derive_watermark`	`number \| null`	yes	二级索引（成交/委托/流水等）已处理高度
`derive_lag_blocks`	`number`	yes	ingest 领先 derive 的区块数
`derive_index_version`	`string \| null`	yes	derive 索引 schema 版本（如 `"2"`）
`candle_watermark`	`number \| null`	yes	K 线聚合已处理高度
`candle_lag_blocks`	`number`	yes	derive 领先 candle 的区块数
`stats_watermark`	`number \| null`	yes	排行榜冷统计已处理高度
`stats_lag_blocks`	`number`	yes	derive 领先 stats 的区块数
`hot_feed`	`HotFeedStatus`	yes	实时行情 Feed 状态
`markets`	`MarketRouteCounts`	yes	路由表市场计数

HotFeedStatus

ExplorerStatus.hot_feed

Field	Type	Required	Description
`native_ready`	`boolean`	yes	热数据 feed seed 完成
`hl_ready`	`boolean`	yes	热数据 feed seed 完成
`stale`	`boolean`	yes	上游 stale
`chain_height`	`number`	yes	热缓存链高度
`book_updated_at_ms`	`number`	yes	盘口最近更新时间（ms）

MarketRouteCounts

ExplorerStatus.markets

Field	Type	Required	Description
`native`	`number`	yes	路由计数（对接可忽略）
`external_peg`	`number`	yes	路由计数（对接可忽略）

3. 枚举与常量

LeaderboardMetric

GET /api/v1/leaderboard?metric=…（必填）

Value	说明
`volume`	成交量
`realized_pnl`	已实现盈亏
`realized_roi`	已实现 ROI
`balance`	余额
`equity`	净值

LeaderboardPeriod

Value	说明
`24h`	24 小时窗口
`7d`	7 天窗口
`30d`	30 天窗口
`all`	全量（默认）

OrderStatus

OrderRecord.status

Value	说明
`open`	挂单中（默认列表不包含；当前委托请查链 RPC）
`filled`	完全成交
`partial_cancelled`	部分成交后撤/过期
`cancelled`	未成交撤单
`expired`	IOC/GTD/FOK 过期

EnvelopeStatus

Value	说明
`accepted`	执行成功
`kept-reject`	保留但拒绝（见 `reason`）

OrderSide

Value	说明
`Bid`	买
`Ask`	卖

FundFlowReason（常见）

TakerFee · MakerFee · RealizedPnl · BridgeDeposit · BridgeWithdrawDebit · BridgeWithdrawRefund · Liquidation · ImRelease · ImAutoAllocate · ImManualAllocate · MakerFeeRefund · FeeRecipientCredit · OracleTrade · Withdrawal · BankruptcyFloor · RebateToInviter · RebateToInvitee

BridgeEventType

DepositRecorded · DepositCredited · WithdrawRequested · WithdrawSettled · WithdrawRefunded

PositionEventType

Updated · Flattened · ForceClosedAtMark

EventKind（常见）

Exec · Core · Bridge · Trigger · Liquidation · Ops · Oco · Unknown

CandleInterval

1m · 3m · 5m · 15m · 30m · 1h · 2h · 4h · 8h · 12h · 1d · 3d · 1w · 1M（UTC 日历月）

4. 核心实体 Schema

BlockHeader

Field	Type	Required	Description
`parent`	`string`	yes	父区块 digest
`height`	`number`	yes	区块高度
`timestamp_ms`	`number`	yes	区块时间戳（ms）
`digest`	`string`	yes	区块 hash
`envelope_count`	`number`	yes	envelope 数量
`event_count`	`number`	yes	event 数量
`state_root`	`string`	yes	状态根
`envelopes`	`EnvelopeView[]`	yes	列表/仅头响应中恒为 `[]`

EnvelopeView

Field	Type	Required	Description
`height`	`number`	yes	所在区块高度
`envelope_idx`	`number`	yes	区块内 envelope 索引
`tx_hash`	`string`	yes	交易 hash
`signer`	`string`	yes	签名者地址
`nonce`	`number`	yes	账户 nonce
`status`	`string`	yes	见 EnvelopeStatus
`action_kind`	`string`	yes	action JSON 顶层 key，如 `PlaceOrder`、`AmendOrder`、`AmendTriggerOrder`
`market_id`	`number`	no	从 action 提取的市场 ID
`symbol`	`string`	no	读取时从 market cache 解析
`action`	`object`	yes	原始 action JSON
`reason`	`object`	no	`status == "kept-reject"` 时的拒绝详情
`timestamp_ms`	`number`	yes	区块时间戳（读取时 join；缺省为 `0`）

EventView

Field	Type	Required	Description
`height`	`number`	yes	区块高度
`seq`	`number`	yes	区块内 event 序号
`envelope_idx`	`number`	yes	产生该 event 的 envelope 索引
`kind`	`string`	yes	事件大类
`sub_kind`	`string`	yes	事件子类型
`market_id`	`number`	no	关联市场 ID
`symbol`	`string`	no	market cache 解析
`tx_hash`	`string`	no	L2 交易 hash（读取时 join）
`account`	`string`	no	关联账户（尽力提取）
`timestamp_ms`	`number`	yes	区块时间戳（ms）
`body`	`object`	yes	节点原始 event JSON（decimal 字符串）

MarketInfo

GET /api/v1/markets 响应 data 数组元素（热读包装，见行情 — /markets）

Field	Type	Required	Description
`market_id`	`number`	yes	链上市场 ID
`symbol`	`string`	yes	交易对，如 `BTC-USDT`
`price_decimals`	`number`	yes	价格小数位
`size_decimals`	`number`	yes	数量小数位

做市商：本 schema 为读侧热读展示。交易接入请用 Chain getMarkets （POST /api/v1/query）——本路径为热读包装，见做市商对接指南 §1.2。

TxLocalResponse

GET /api/v1/tx/{hash}，source == "local"

Field	Type	Required	Description
`data`	`EnvelopeView` + `events`	yes	见下
`source`	`"local"`	yes	本地索引

data 在 EnvelopeView 全部字段基础上额外包含：

Field	Type	Required	Description
`events`	`EventView[]`	yes	该 envelope 产生的全部 events

source == "node" 时 data 为链节点 getTx 结构，不保证与 EnvelopeView 字段完全一致。

5. 账户历史 Schema

FillRecord

GET /api/v1/fills

Field	Type	Required	Description
`height`	`number`	yes	区块高度
`seq`	`number`	yes	源 `Filled` event 序号
`is_taker`	`boolean`	yes	是否为 taker 侧
`timestamp_ms`	`number`	yes	区块时间戳（ms）
`market_id`	`number`	yes	市场 ID
`order_id`	`number`	yes	本参与者 order ID
`account`	`string`	yes	本参与者地址
`counterparty`	`string`	yes	对手方地址
`price`	`string`	yes	成交价
`qty`	`string`	yes	成交量
`notional`	`string`	yes	`price × qty`
`fee`	`string`	yes	本参与者手续费
`position_action`	`string`	no	开/平仓效果：`open_long` / `open_short` / `close_long` / `close_short`；无法判定时省略
`realized_pnl`	`string`	no	本笔成交 attributed 已实现盈亏（SCALE_6）
`realized_pnl_pct`	`string`	no	盈利率（百分比，两位小数，如 `"1.64"`；开仓/加仓为 `"0.00"`）
`symbol`	`string`	no	market cache 解析
`envelope_idx`	`number`	no	源 event envelope 索引
`tx_hash`	`string`	no	源 event L2 tx hash
`trigger_id`	`number`	no	触发单促成的成交关联的 trigger_id

每笔链上 Filled event 产生 2 行（taker + maker）。

derive worker 在同 envelope 内为每个 fill 关联 Exec::PositionUpdated（同 market_id、同 owner）：优先 seq 在 fill 之后的最近一条，若无则取之前的最近一条（强平等场景 PositionUpdated 常先于 Filled）。关联成功后按仓位变化计算 position_action（open_long / open_short / close_long / close_short）。

realized_pnl / realized_pnl_pct 来自匹配的 PositionUpdated.realized_pnl；盈利率按平仓 cost basis 计算（多仓 (realized / (notional - realized)) × 100；空仓 (realized / (notional + realized)) × 100）；开仓/加仓时 realized_pnl_pct 为 "0.00"。若无 PositionUpdated 但存在同 envelope 的 Liquidation::Liquidated（同 market_id、同 target），则取 total_realized_pnl，position_action 为 close 方向，realized_pnl_pct = "0.00"。均无匹配时 PnL 为 "0" / "0.00"，position_action 省略。

变更：derive index v4 起以 position_action 取代 aggressor_side / position_old_size / position_new_size / is_close；需要 taker 方向请用 Chain getUserFills / WS userFills，需要持仓前后尺寸请用 GET /api/v1/positions。

OrderRecord

GET /api/v1/orders — 历史委托（已关闭订单）。默认 status != open；未关闭挂单不在此接口，请通过链 RPC 查当前委托。显式 status=open 可单独查挂单（读侧索引用途，非产品主路径）。

Field	Type	Required	Description
`order_id`	`number`	yes	链上 order ID
`owner`	`string`	yes	订单 owner
`market_id`	`number`	yes	市场 ID
`side`	`string`	yes	`Bid` / `Ask`
`price`	`string`	no	限价（市价单可为 null/省略）
`qty`	`string`	yes	原始委托数量
`filled_qty`	`string`	yes	已成交量
`avg_fill_price`	`string`	no	成交均价
`status`	`string`	yes	见 OrderStatus
`close_reason`	`string`	no	链上 DoneReason 等
`placed_height`	`number`	yes	下单区块高度
`placed_at_ms`	`number`	yes	下单时间（ms）
`closed_height`	`number`	no	终态区块高度
`closed_at_ms`	`number`	no	终态时间（ms）；默认列表项必有（`status != open`）
`symbol`	`string`	no	market cache 解析
`placed_tx_hash`	`string`	no	下单 L2 tx hash
`closed_tx_hash`	`string`	no	终态 L2 tx hash

derive 事件：OrderAccepted 建单；OrderResting 更新挂簿快照（改价/改量，刷新 price / qty / filled_qty，状态保持 open）；Filled 累计成交量与均价；OrderDone 及 OCO/平仓等特殊 event 写终态。索引层仍物化 open 行，但 /orders 默认不返回。

FundFlowRecord

GET /api/v1/fund-flows

Field	Type	Required	Description
`height`	`number`	yes	区块高度
`seq`	`number`	yes	源 `BalanceChanged` event 序号
`timestamp_ms`	`number`	yes	区块时间戳（ms）
`account`	`string`	yes	账户地址
`delta`	`string`	yes	余额变动（可负）
`new_balance`	`string`	yes	变动后余额
`reason`	`string`	yes	见 FundFlowReason
`market_id`	`number`	no	部分 reason 带市场
`envelope_idx`	`number`	no	源 event envelope 索引
`tx_hash`	`string`	no	源 event L2 tx hash

BridgeFlowRecord

GET /api/v1/bridge-flows

Field	Type	Required	Description
`height`	`number`	yes	区块高度
`seq`	`number`	yes	源 bridge event 序号
`timestamp_ms`	`number`	yes	区块时间戳（ms）
`event_type`	`string`	yes	见 BridgeEventType
`account`	`string`	yes	账户地址
`amount`	`string`	yes	金额
`new_balance`	`string`	no	变更后余额
`deposit_seq`	`number`	no	充值序号
`request_id`	`number`	no	提现 request ID
`chain_id`	`number`	no	外链 chain ID
`reason_code`	`number`	no	退款原因码
`envelope_idx`	`number`	no	源 event envelope 索引
`tx_hash`	`string`	no	L2 envelope tx hash
`external_tx_hash`	`string`	no	L1 链上 tx hash

PositionHistoryRecord

GET /api/v1/positions

Field	Type	Required	Description
`height`	`number`	yes	区块高度
`seq`	`number`	yes	源 position event 序号
`timestamp_ms`	`number`	yes	区块时间戳（ms）
`owner`	`string`	yes	持仓 owner
`market_id`	`number`	yes	市场 ID
`event_type`	`string`	yes	见 PositionEventType
`old_size`	`string`	no	变动前仓位
`new_size`	`string`	no	变动后仓位
`new_entry_vwap`	`string`	no	新 entry VWAP
`realized_pnl`	`string`	no	已实现 PnL
`mark_price`	`string`	no	标记价格（强平等）
`symbol`	`string`	no	market cache 解析
`envelope_idx`	`number`	no	源 event envelope 索引
`tx_hash`	`string`	no	源 event L2 tx hash

6. 推荐关系 Schema（Referral）

链事件源：Core::ReferrerRegistered（owner, code）、Core::ReferrerBound（owner, code）。由 derive worker 写入 referral_event / referral_account / referral_code_index。

ReferralSummary

GET /api/v1/referral?address=…

Field	Type	Required	Description
`address`	`string`	yes	查询账户
`referral_code`	`string`	no	自有推荐码（未注册时省略）
`referred_by_code`	`string`	no	绑定的上级推荐码（未绑定时省略）
`referrer_address`	`string`	no	上级码主地址（由 `referred_by_code` 解析）
`n_referrals`	`number`	yes	绑定本账户推荐码的人数（链 `getReferral.n_referrals`）
`registered_height`	`number`	no	注册推荐码区块高度
`registered_at_ms`	`number`	no	注册时间（ms）
`bound_height`	`number`	no	绑定推荐码区块高度
`bound_at_ms`	`number`	no	绑定时间（ms）

ReferralCodeView

GET /api/v1/referral?code=…

Field	Type	Required	Description
`referral_code`	`string`	yes	推荐码
`owner`	`string`	yes	码主地址
`n_referrals`	`number`	yes	邀请人数
`last_bound_ms`	`number`	no	最近一次被绑定时间（ms）

ReferralEventRecord

GET /api/v1/referral/events

Field	Type	Required	Description
`height`	`number`	yes	区块高度
`seq`	`number`	yes	块内 event 序号
`timestamp_ms`	`number`	yes	区块时间（ms）
`event_type`	`string`	yes	`ReferrerRegistered` \| `ReferrerBound`
`account`	`string`	yes	event body `owner`
`code`	`string`	yes	推荐码
`envelope_idx`	`number`	no	源 event envelope 索引
`tx_hash`	`string`	no	源 event L2 tx hash

ReferralReferee

GET /api/v1/referral/referees

Field	Type	Required	Description
`address`	`string`	yes	被邀请账户
`referred_by_code`	`string`	yes	绑定的推荐码
`bound_height`	`number`	yes	绑定区块高度
`bound_at_ms`	`number`	yes	绑定时间（ms）
`bound_tx_hash`	`string`	no	绑定交易 hash

空结果： 使用 address 查询且该账户未注册 referral_code 时，HTTP 200，data: []，page.total: 0（不是 4xx/5xx）。

ReferralLeaderboardEntry

GET /api/v1/referral/leaderboard

Field	Type	Required	Description
`rank`	`number`	yes	排名（1-based，随 offset 递增）
`referral_code`	`string`	yes	推荐码
`owner`	`string`	yes	码主地址
`n_referrals`	`number`	yes	邀请人数
`last_bound_ms`	`number`	no	最近绑定时间（ms）

7. 返佣 Schema（Rebate）

链事件源：Core::RebatePaid（trader, inviter, referral_code, total_amount, inviter_share, invitee_share）。入账对应 Core::BalanceChanged{RebateToInviter/RebateToInvitee}（见 §5 FundFlowRecord.reason）。由 derive worker 写入 rebate_event / rebate_account_stats。

RebateSummary

GET /api/v1/rebate?address=…

Field	Type	Required	Description
`address`	`string`	yes	查询账户
`total_received`	`string`	yes	累计已返佣（SCALE_6）
`as_inviter_total`	`string`	yes	作为邀请者累计
`as_invitee_total`	`string`	yes	作为交易者回分累计
`event_count`	`number`	yes	参与返佣事件数
`last_rebate_ms`	`number`	no	最近一次返佣时间（ms）

RebateEventRecord

GET /api/v1/rebate/events

Field	Type	Required	Description
`height`	`number`	yes	区块高度
`seq`	`number`	yes	块内 event 序号
`timestamp_ms`	`number`	yes	区块时间（ms）
`trader`	`string`	yes	产生 fee 的交易者
`inviter`	`string`	yes	邀请者
`referral_code`	`string`	yes	推荐码
`total_amount`	`string`	yes	返佣池总量
`inviter_share`	`string`	yes	邀请者份额
`invitee_share`	`string`	yes	交易者回分
`role`	`string`	yes	查询账户角色：`Inviter` \| `Invitee`
`amount`	`string`	yes	查询账户入账金额
`envelope_idx`	`number`	no	源 event envelope 索引
`tx_hash`	`string`	no	源 event L2 tx hash

8. 账户累计统计 Schema（Account stats）

由 stats worker 从 derive 索引增量写入 account_trade_stats / account_pnl_stats / account_capital_stats（见 stats_agg_version）。

AccountStatsSummary

GET /api/v1/account-stats?account=…

Field	Type	Required	Description
`account`	`string`	yes	查询账户
`period`	`string`	yes	v1 固定 `"all"`
`total_deposits`	`string`	yes	`DepositCredited` 累计（SCALE_6）
`total_withdrawals`	`string`	yes	`WithdrawSettled` 累计（SCALE_6）
`net_deposits`	`string`	yes	充值 − 提现申请 + 退款（ROI 分母）
`total_volume`	`string`	yes	账户成交额
`trade_count`	`number`	yes	成交笔数
`total_fees`	`string`	yes	账户支付手续费
`gross_profit`	`string`	yes	已实现盈利（正 `RealizedPnl` 之和）
`gross_loss`	`string`	yes	已实现亏损（负 `RealizedPnl` 绝对值之和）
`net_pnl`	`string`	yes	净已实现盈亏；不含手续费
`as_of_height`	`number`	no	stats 截至高度
`as_of_timestamp_ms`	`number`	no	索引库最新区块时间（ms）
`stale`	`boolean`	no	stats 滞后时为 `true`

8.5 Chain proxy Schema（链上实时只读）

ChainPosition

Field	Type	Required	Description
`market_id`	`number`	yes	市场 ID
`symbol`	`string`	yes	交易对
`size`	`string`	yes	仓位（signed decimal）
`entry_vwap`	`string`	yes	开仓均价
`mark_price`	`string`	yes	标记价
`margin_mode`	`string`	yes	`Cross` / `Isolated`
`leverage`	`number`	yes	杠杆
`isolated_margin`	`string`	yes	逐仓保证金
`unrealized_pnl`	`string`	yes	未实现盈亏
`notional`	`string`	yes	名义值
`liquidation_price`	`string`	no	强平价
`margin_used`	`string`	yes	占用保证金
`roe`	`string`	no	ROE

ChainAccountView

GET /api/v1/chain/account

Field	Type	Required	Description
`address`	`string`	yes	账户地址
`balance`	`string`	yes	余额（SCALE_6）
`nonce`	`number`	yes	nonce
`account_value`	`string`	yes	账户净值
`total_margin_used`	`string`	yes	已用保证金
`total_notional`	`string`	yes	总名义值
`withdrawable`	`string`	yes	展示用可提额
`cross_cash_available`	`string`	yes	全仓 cash 可用
`cross_trading_available`	`string`	yes	全仓交易可用
`positions`	`ChainPosition[]`	yes	持仓列表（由链上 map 展开）

响应外层：{ "height": number, "data": ChainAccountView }。

ChainOpenOrder

Field	Type	Required	Description
`order_id`	`number`	yes	订单 ID
`owner`	`string`	yes	owner
`market_id`	`number`	yes	市场 ID
`symbol`	`string`	yes	交易对
`side`	`string`	yes	`Bid` / `Ask`
`price`	`string`	yes	限价
`qty`	`string`	yes	原始数量
`remaining`	`string`	yes	剩余量
`filled`	`string`	yes	已成交量
`tif`	`string`	yes	TIF
`reduce_only`	`boolean`	yes	仅减仓
`client_order_id`	`string`	no	cloid
`placed_at_ms`	`number`	yes	挂单时间
`expires_at_ms`	`number`	no	GTD 过期
`order_type`	`string`	yes	`Limit` / `Market`

ChainOpenOrdersView

GET /api/v1/chain/open-orders

Field	Type	Required	Description
`address`	`string`	yes	账户地址
`orders`	`ChainOpenOrder[]`	yes	当前挂单

响应外层：{ "height": number, "data": ChainOpenOrdersView }。

9. 排行榜 Schema

LeaderboardEntry

Field	Type	Required	Description
`rank`	`number`	yes	排名（1-based）
`account`	`string`	yes	账户地址
`value`	`string`	yes	排行主指标
`trade_count`	`number`	no	仅 `metric=volume`
`auxiliary`	`string`	no	ROI 附带 PnL；balance/equity 附带余额等

LeaderboardMeta

Field	Type	Required	Description
`metric`	`string`	yes	请求的 metric
`period`	`string`	yes	请求的 period
`source`	`string`	yes	`local` 或 `node`
`as_of_height`	`number`	no	数据截至高度
`as_of_timestamp_ms`	`number`	no	数据截至时间（ms）
`stale`	`boolean`	yes	热数据节点不可达时为 `true`；`false` 时可能省略

LeaderboardResponse

{
  "data": [ /* LeaderboardEntry[] */ ],
  "meta": { /* LeaderboardMeta */ },
  "page": { /* Page */ }
}

page.total 上限 500。

10. K 线 Schema

:::info 与 §12 实时行情 Schema 的区别

§10（本节）：K 线 Candle — OHLCV；SQLite + 内存当前根。
§12：实时行情 — 盘口 / 成交 / BBO / Mark；仅内存；见 实时行情。

:::

CandleRecord（内部 / candle worker 内存态）

K 线 worker 内存中的开口 bucket；REST 响应通过 merge 转为 Candle。实时推送走 candles.{symbol}.{interval} 主题（见 WebSocket）。

Field	Type	Required	Description
`market_id`	`number`	yes	市场 ID
`interval_ms`	`number`	yes	bucket 宽度（ms）
`open_time_ms`	`number`	yes	bucket 开盘时间
`close_time_ms`	`number`	yes	bucket 收盘时间
`open`	`string`	yes	开盘价
`high`	`string`	yes	最高价
`low`	`string`	yes	最低价
`close`	`string`	yes	收盘价
`volume`	`string`	yes	成交量
`trades`	`number`	yes	成交笔数
`symbol`	`string`	no	market cache 解析

Candle（REST `GET /api/v1/candles` 与 `POST /info` 响应）

裸数组 Candle[]，按 t 升序：

Field	Type	Required	Description
`t`	`number`	yes	bucket 开盘时间（ms）
`T`	`number`	yes	bucket 收盘时间（ms）
`s`	`string`	yes	市场 symbol
`i`	`string`	yes	interval 字符串
`o`	`string`	yes	open
`h`	`string`	yes	high
`l`	`string`	yes	low
`c`	`string`	yes	close
`v`	`string`	yes	volume
`n`	`number`	yes	trades

11. WebSocket Schema（摘要）

统一协议（op / topics 订阅制）与完整帧见 统一 WebSocket · 实时行情 §6。

BlocksLivePush（`topic: "blocks.live"`）

Field	Type	Required	Description
`topic`	`"blocks.live"`	yes	固定值
`block`	`BlockHeader`	yes	新区块头（`block.envelopes` 为空）
`envelopes`	`EnvelopeView[]`	yes	该块全部 envelope
`watermark`	`number`	yes	ingest watermark
`block_count`	`number`	yes	区块总数
`node_tip`	`number`	no	节点 tip
`behind`	`number`	no	落后区块

需订阅 blocks.live 后才会推送（旧协议连接即推 block_ingested 已删除）。与 K 线 / 行情主题 同一连接可并存。

CandlesPush（`topic: "candles.{symbol}.{interval}"`）

{ "topic": "candles.BTC-USDT.1h", "data": { /* Candle */ } }

BookPush / TradesPush / BboPush / MarksPush（行情主题）

统一主题帧（book.{symbol} / trades.{symbol} / bbo.{symbol} / marks）见实时行情 §6.3 与统一 WebSocket。

12. 实时行情 Schema

:::info 与 §10 K 线 Schema 的区别

§12（本节）：实时盘口 / 成交 / BBO / Mark — 内存；未完成 seed 时 REST 503。
§10：K 线 OHLCV — SQLite；就绪看 candle_watermark。

:::

权威行为说明见 实时行情。以下为 REST / WS 字段契约。

HotReadResponse<T>

热读 REST 成功响应（meta 与 data 扁平于同一 JSON 对象）：

Field	Type	Required	Description
`chain_height`	`number`	yes	热缓存链高度
`book_updated_at_ms`	`number`	yes	盘口最近更新时间（ms）
`stale`	`boolean`	yes	上游 stale；仍为 200
`ready`	`boolean`	yes	Feed ready
`data`	`T`	yes	业务载荷

响应 Header（optional）：X-Chain-Height · X-Book-Updated-At-Ms · X-Market-Data-Stale: true（当 stale）

OrderbookLevel

Field	Type	Required	Description
`price`	`string`	yes	档位价格
`qty`	`string`	yes	档位数量
`cumulative_qty`	`string`	no	累计量；常为空字符串

OrderbookSnapshot

GET /api/v1/market/orderbook/{symbol} → HotReadResponse.data

Field	Type	Required	Description
`symbol`	`string`	yes	Zepto symbol
`height`	`number`	yes	关联链高度
`state_hash`	`string`	yes	链 state hash；无链关联时可为 `""`
`source`	`string`	yes	内部来源字符串；不对调用方语义分流
`bids`	`OrderbookLevel[]`	yes	买盘，价降序
`asks`	`OrderbookLevel[]`	yes	卖盘，价升序

每侧最多 50 档（部分市场服务端 cap 可能更低）。

RecentTrade

GET /api/v1/market/trades/{symbol} → HotReadResponse.data 数组元素

Field	Type	Required	Description
`block_height`	`number`	yes	链区块高度；无链关联时可为 `0`
`event_seq`	`number`	yes	链 event 序号
`timestamp_ms`	`number`	yes	成交时间（ms）
`market_id`	`number`	yes	market ID
`symbol`	`string`	yes	Zepto symbol
`price`	`string`	yes	成交价
`qty`	`string`	yes	成交量
`notional`	`string`	yes	名义值
`side`	`string`	yes	`"Bid"` \| `"Ask"`
`hl_tid`	`number`	no	可选 trade id（dedup）

Ring cap 10_000 / market；REST 默认 limit=50，max 1000；排序 新→旧。

BboItem

GET /api/v1/bbos → HotReadResponse.data[]

Field	Type	Required	Description
`symbol`	`string`	yes	Zepto symbol
`bid`	`string`	no	最优买价
`ask`	`string`	no	最优卖价
`spread`	`string`	no	ask − bid（可计算 omit）

MarksMap

GET /api/v1/marks → HotReadResponse.data

JSON object：{ [symbol: string]: mark_price string }（BTreeMap 序列化，键按 symbol 排序）。

MarketSummary

GET /api/v1/markets/{symbol}/summary → HotReadResponse.data

Field	Type	Required	Description
`symbol`	`string`	yes	Zepto symbol
`mark_price`	`string`	yes	链 mark
`best_bid`	`string`	no	orderbook 顶档
`best_ask`	`string`	no	orderbook 顶档
`spread`	`string`	no	价差
`open_interest`	`string`	no	OI
`open_interest_notional`	`string`	no	OI 名义值
`fills_in_block`	`number`	no	本块成交笔数
`bid_levels`	`number`	yes	bid 档数
`ask_levels`	`number`	yes	ask 档数
`open_orders`	`number`	yes	resting 订单数
`prev_day_price`	`string`	no	24h 前 mark
`day_ntl_volume`	`string`	no	24h 名义成交量
`day_base_volume`	`string`	no	24h 币本位成交量

WsBookLevel

Field	Type	Required	Description
`px`	`string`	yes	价格
`sz`	`string`	yes	数量
`n`	`number`	yes	订单数（常为 `1`）
`cumulative_qty`	`string`	no	可省略或 `""`

WsL2BookData / WsL2BookPush

{ "channel": "l2Book", "data": { "coin": "BTC", "time": 0, "levels": [[/* bids */], [/* asks */]] } }

WsTrade / WsTradesPush

Field	Type	Required	Description
`coin`	`string`	yes	WS coin
`side`	`string`	yes	`"B"` \| `"A"`
`px`	`string`	yes	价格
`sz`	`string`	yes	数量
`time`	`number`	yes	ms
`hash`	`string`	no	常为 `""`
`tid`	`number`	yes	trade id

{ "channel": "trades", "data": [ /* WsTrade[] */ ] }

WsBboData / WsBboPush

data.bbo: [best_bid | null, best_ask | null]，元素为 WsBookLevel。

WsMarksData / WsMarksPush

Field	Type	Required	Description
`height`	`number`	yes	链高度
`timestamp_ms`	`number`	yes	更新时间
`marks`	`MarksMap`	yes	symbol → mark

13. 端点 → Schema 映射

Method	Path	Success HTTP	Response Schema
GET	`/health`	200	`HealthResponse`
GET	`/api/v1/status`	200	`ExplorerStatus`
GET	`/api/v1/blocks`	200	`Paged<BlockHeader>`
GET	`/api/v1/blocks/{id}`	200 / 404	`DataOnly<BlockHeader>`
GET	`/api/v1/blocks/{id}/events`	200 / 404	`Paged<EventView>`
GET	`/api/v1/blocks/{id}/envelopes`	200 / 404	`DataOnly<EnvelopeView[]>`
GET	`/api/v1/envelopes`	200	`Paged<EnvelopeView>`
GET	`/api/v1/tx/{hash}`	200 / 404	`TxLocalResponse` 或 `{ data: node, source: "node" }`
GET	`/api/v1/markets`	200	热读包装 `{ chain_height, book_updated_at_ms, stale, ready, data: MarketInfo[] }`
GET	`/api/v1/chain/account`	200 / 400 / 502	`{ height, data: ChainAccountView }`
GET	`/api/v1/chain/open-orders`	200 / 400 / 502	`{ height, data: ChainOpenOrdersView }`
GET	`/api/v1/fills`	200	`Paged<FillRecord>`
GET	`/api/v1/orders`	200	`Paged<OrderRecord>`
GET	`/api/v1/fund-flows`	200	`Paged<FundFlowRecord>`
GET	`/api/v1/bridge-flows`	200	`Paged<BridgeFlowRecord>`
GET	`/api/v1/positions`	200	`Paged<PositionHistoryRecord>`
GET	`/api/v1/account/events`	200	`Paged<EventView>`
GET	`/api/v1/referral`	200 / 404	`DataOnly<ReferralSummary>` 或 `DataOnly<ReferralCodeView>`
GET	`/api/v1/referral/events`	200	`Paged<ReferralEventRecord>`
GET	`/api/v1/referral/referees`	200	`Paged<ReferralReferee>`
GET	`/api/v1/referral/leaderboard`	200	`Paged<ReferralLeaderboardEntry>`
GET	`/api/v1/rebate`	200	`DataOnly<RebateSummary>`
GET	`/api/v1/rebate/events`	200	`Paged<RebateEventRecord>`
GET	`/api/v1/account-stats`	200	`DataOnly<AccountStatsSummary>`
GET	`/api/v1/leaderboard`	200 / 400	`LeaderboardResponse`
GET	`/api/v1/candles`	200 / 404	`Candle[]`
POST	`/info`	200 / 400	`Candle[]`（`candleSnapshot`）
GET	`/api/v1/market/orderbook/{symbol}`	200 / 404 / 503	`HotReadResponse<OrderbookSnapshot>`
GET	`/api/v1/market/trades/{symbol}`	200 / 404 / 503	`HotReadResponse<RecentTrade[]>`
GET	`/api/v1/bbos`	200 / 503	`HotReadResponse<BboItem[]>`
GET	`/api/v1/marks`	200 / 503	`HotReadResponse<MarksMap>`
GET	`/api/v1/markets/{symbol}/summary`	200 / 404 / 503	`HotReadResponse<MarketSummary>`
GET	`/api/v1/ws`	101	WebSocket，见 WebSocket

14. Query 参数速查（必填项）

Path	Required query	Optional query
`/api/v1/fills`	`account`	`market_id`, `from_block`, `to_block`, `offset`, `limit`
`/api/v1/orders`	`owner`	`market_id`, `status`（默认排除 `open`）, `offset`, `limit`
`/api/v1/fund-flows`	`account`	`reason`, `market_id`, `from_block`, `to_block`, `offset`, `limit`
`/api/v1/bridge-flows`	`account`	`event_type`, `from_block`, `to_block`, `offset`, `limit`
`/api/v1/positions`	`owner`	`market_id`, `event_type`, `from_block`, `to_block`, `offset`, `limit`
`/api/v1/account/events`	`account`	`kind`, `sub_kind`, `market_id`, `from_block`, `to_block`, `offset`, `limit`
`/api/v1/referral`	`address` 或 `code`（二选一）	—
`/api/v1/referral/events`	`account`	`event_type`, `from_block`, `to_block`, `offset`, `limit`
`/api/v1/referral/referees`	`code` 或 `address`（二选一）	`offset`, `limit`
`/api/v1/referral/leaderboard`	—	`offset`, `limit`
`/api/v1/rebate`	`address`	—
`/api/v1/rebate/events`	`account`	`role`（`Inviter` \| `Invitee`，无效 → `400`）, `from_block`, `to_block`, `offset`, `limit`
`/api/v1/account-stats`	`account`	—
`/api/v1/chain/account`	`address`	—
`/api/v1/chain/open-orders`	`address`	—
`/api/v1/leaderboard`	`metric`	`period`, `offset`, `limit`
`/api/v1/candles`	`symbol`	`interval`, `from`, `to`, `limit`
`/api/v1/market/orderbook/{symbol}`	—	`depth`
`/api/v1/market/trades/{symbol}`	—	`offset`, `limit`
`/api/v1/envelopes`	—	`signer`, `action_kind`, `market_id`, `from_block`, `to_block`, `offset`, `limit`

分页默认与上限见分页契约。

15. 对接清单

主题	说明
总览	做市接入做市商对接指南（含 §1.2 重叠路径选型）；签名签名与鉴权
实时行情	实时行情 — WS 主题 `book.` / `trades.` / `bbo.*` / `marks`
K 线	§10 · K 线 — WS 主题 `candles.{symbol}.{interval}`
无认证	所有接口公开只读；生产环境请自行加网关 / 限流
索引延迟	读 `status` 的 `derive_lag_blocks` / `stats_lag_blocks`
实时行情 seeding	`hot_feed.` 均为 `true` 后再依赖实时 REST；否则 503*
Chain proxy	`/api/v1/chain/account` · `/open-orders` 透传链 RPC；写与 WS 仍走链读写
WebSocket 主题	`blocks.live` · `candles.` · `book.` · `trades.` · `bbo.` · `marks`（统一 `/api/v1/ws`，订阅制）
版本	当前无 URL 版本前缀变更策略；`/api/v1/` 为稳定前缀

1. 全局约定​

1.1 Base URL​

1.2 地址与哈希​

1.3 数值与 decimal​

1.4 可选字段与 JSON 省略​

1.5 事件溯源（Event provenance）​

1.6 排序​

1.7 索引延迟​

2. 公共包装类型​

Page​

Paged<T>​

DataOnly<T>​

ErrorResponse​

HealthResponse​

ExplorerStatus​

HotFeedStatus​

MarketRouteCounts​

3. 枚举与常量​

LeaderboardMetric​

LeaderboardPeriod​

OrderStatus​

EnvelopeStatus​

OrderSide​

FundFlowReason（常见）​

BridgeEventType​

PositionEventType​

EventKind（常见）​

CandleInterval​

4. 核心实体 Schema​

BlockHeader​

EnvelopeView​

EventView​

MarketInfo​

TxLocalResponse​

5. 账户历史 Schema​

FillRecord​

OrderRecord​

FundFlowRecord​

BridgeFlowRecord​

PositionHistoryRecord​

6. 推荐关系 Schema（Referral）​

ReferralSummary​

ReferralCodeView​

ReferralEventRecord​

ReferralReferee​

ReferralLeaderboardEntry​

7. 返佣 Schema（Rebate）​

RebateSummary​

RebateEventRecord​

8. 账户累计统计 Schema（Account stats）​

AccountStatsSummary​

8.5 Chain proxy Schema（链上实时只读）​

ChainPosition​

ChainAccountView​

ChainOpenOrder​

ChainOpenOrdersView​

9. 排行榜 Schema​

LeaderboardEntry​

LeaderboardMeta​

LeaderboardResponse​

10. K 线 Schema​

CandleRecord（内部 / candle worker 内存态）​

Candle（REST GET /api/v1/candles 与 POST /info 响应）​

11. WebSocket Schema（摘要）​

BlocksLivePush（topic: "blocks.live"）​

CandlesPush（topic: "candles.{symbol}.{interval}"）​

BookPush / TradesPush / BboPush / MarksPush（行情主题）​

12. 实时行情 Schema​

HotReadResponse<T>​

OrderbookLevel​

OrderbookSnapshot​

RecentTrade​

BboItem​

MarksMap​

MarketSummary​

WsBookLevel​

WsL2BookData / WsL2BookPush​

WsTrade / WsTradesPush​

WsBboData / WsBboPush​

WsMarksData / WsMarksPush​