系统端点

本页是健康 / 状态 / 配置 / 限流 / 审计 等系统类端点：GET /api/v1/health、GET /api/v1/status 与对应 JSON-RPC 读方法。

健康检查

GET /api/v1/health

纯 REST 就绪探针（不走 JSON-RPC）。HTTP 200 = 就绪；503 = halted / 回补中（recovering）/ state store dirty（degraded）。

GET /api/v1/health/live

纯 REST 存活探针：halt 仍 503，回补中 / degraded 仍 200。k8s/LB 建议 readiness 用 /health、liveness 用 /health/live。

响应示例：

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

字段	类型	说明
status	String	"ok" / "recovering"（回补/水印落后）/ "degraded"（state store dirty，需重启修复）
height	u64	当前链高度
store_dirty	bool	state store 是否 dirty（丢批后冻结、待重启修复）

---

getHealth

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

请求：

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

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

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": { "status": "ok", "height": 12345 }
  }
}

getExchangeConfig

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

响应 data：

字段	类型	说明
action_version	u32	Wire 协议版本（当前 2）
max_decimals	u32	SCALE_6 精度上限
max_tx_per_block	usize	每块最大交易数
settlement_paused	bool	全局 Bridge 结算闸门
global_rebate_ratio_bps	u32	全局默认返佣比例（bps；1 000 = 10 %）
market_count	usize	活跃市场数

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": {
      "action_version": 2,
      "max_decimals": 6,
      "max_tx_per_block": 1024,
      "settlement_paused": false,
      "global_rebate_ratio_bps": 1000,
      "market_count": 3
    }
  }
}

getActionsMeta

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

响应 data：

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

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": {
      "action_version": 2,
      "actions": [
        { "name": "PlaceOrder", "auth": "master_or_agent_with_role", "role": "Trader", "master_only": false },
        { "name": "WithdrawRequest", "auth": "user_signed_master", "role": null, "master_only": true },
        { "name": "CreateMarket", "auth": "master", "role": "Admin", "master_only": true }
      ]
    }
  }
}

---

getUserRateLimit

用户速率限制视图（index 滑动窗口统计，最近 10,000 块）。

参数	类型	必填	说明
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 块）

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": {
      "address": "0x1111222233334444555566667777888899990000",
      "cum_vlm": "1250000.000000",
      "n_requests_used": 42,
      "n_requests_cap": 1024,
      "window_blocks": 10000
    }
  }
}

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)

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": [{
      "block_height": 12340,
      "event_seq": 2,
      "timestamp_ms": 1717199000000,
      "signer": "0x2222333344445555666677778888999900001111",
      "event": {
        "Ops": {
          "GlobalRebateRatioChanged": {
            "old_ratio_bps": 1000,
            "new_ratio_bps": 2000
          }
        }
      }
    }],
    "page": { "offset": 0, "limit": 100, "total": null }
  }
}

系统端点（REST）

GET /health

已移除：合并后节点不再提供裸 /health 路由。存活 / 就绪探针请用 GET /api/v1/health。

Response 200

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

status 取值：ok / recovering / degraded（链停机时 HTTP 503）。

---

GET /api/v1/status

索引同步进度与链滞后情况。

Response 200

{
  "watermark": 12345,
  "block_count": 12346,
  "node_tip": 12350,
  "behind": 5,
  "derive_watermark": 12340,
  "derive_lag_blocks": 5,
  "derive_index_version": "2",
  "candle_watermark": 12338,
  "candle_lag_blocks": 2,
  "stats_watermark": 12335,
  "stats_lag_blocks": 5,
  "hot_feed": {
    "native_ready": true,
    "hl_ready": true,
    "stale": false,
    "chain_height": 12345,
    "book_updated_at_ms": 1717200000123
  },
  "markets": {
    "native": 1,
    "external_peg": 4
  }
}

Field	Type	Description
watermark	number | null	已完全 ingest 的最高区块高度；首个区块前为 null
block_count	number	本地存储的区块总数
node_tip	number | null	链节点当前 tip（节点不可达时为 null）
behind	number | null	落后区块数。两者皆有：node_tip - watermark；仅 tip：node_tip + 1；否则 null
derive_watermark	number | null	二级索引（成交/委托/流水等）已处理到的最高区块
derive_lag_blocks	number	ingest watermark 领先 derive_watermark 的区块数
derive_index_version	string | null	derive 索引 schema 版本（如 "2"）；未写入时为 null
candle_watermark	number | null	K 线聚合已处理到的最高区块
candle_lag_blocks	number	derive_watermark 领先 candle_watermark 的区块数
stats_watermark	number | null	排行榜冷统计已处理到的最高区块
stats_lag_blocks	number	derive_watermark 领先 stats_watermark 的区块数（0 = 统计已追上）
hot_feed.native_ready	boolean	热数据 feed seed 完成
hot_feed.hl_ready	boolean	热数据 feed seed 完成
hot_feed.stale	boolean	上游 WS 断开或长时间未更新
hot_feed.chain_height	number	热缓存关联链高度
hot_feed.book_updated_at_ms	number	盘口最近更新时间（ms）
markets	object	服务端路由计数（对接可忽略）

索引流水线（异步，不阻塞 ingest）：

ingest (watermark) → derive → candle → stats

---

---

服务端行为

行为	值
写路由超时	同步 admit-execute，写请求在共识轮次内返回
HTTP 状态码	错误亦返回 HTTP 200（JSON-RPC 规范），GET /api/v1/health 除外（200=就绪；503=halted/recovering/degraded）
Journal 扫描窗口	最多回溯 10,000 块（getAdminAuditLog / getCandles）
成交流 ring buffer	最近约 10k 块（getRecentTrades）
Fill archive	getUserFills / getOrderFills / getUserFillsSince：永久存储，启动 journal backfill
终态订单 archive	getOrderStatus closed：内存 24h 热缓存 + 硬盘永久点查（O(log N)）
单块最大交易数	max_tx_per_block（见 getExchangeConfig）
Action 版本	当前 action_version: 2