REST 列表分页契约

适用于读侧 REST 的 GET 列表端点（历史 / 审计 / 行情列表等）。所有列表响应统一为 Paged：{ "data": [...], "page": {...} }。契约变更历史见接口变更清单 §4.2。

1. 通用分页参数（query string）

参数	默认	说明
`offset`	0	起始位置；深分页上限 `MAX_OFFSET = 1000`（超过返回 400，改用 `cursor`）
`limit`	见 §3 各端点	上限见 §3；超过会被截断到上限
`include_total`	false	为 `true` 时才计算并返回 `page.total`（精确计数，低频场景用）
`cursor`	无	上一页返回的 `page.next_cursor`，原样传回；传了 `cursor` 时 `offset` 被忽略

{
  "data": [],
  "page": {
    "offset": 0,
    "limit": 50,
    "total": 1234,
    "next_cursor": "123:45",
    "has_more": true
  }
}

字段	语义
`offset` / `limit`	实际生效的分页位置与页大小
`total`	仅 `include_total=true` 时出现；默认省略
`next_cursor`	游标模式下存在下一页时返回；offset 模式为 `null`
`has_more`	游标模式下返回 `true/false`；offset 模式为 `null`

端点	默认/上限 limit	游标格式	备注
`GET /api/v1/blocks`	50 / 200	`height`	—
`GET /api/v1/envelopes`	25 / 200	`height:idx`	—
`GET /api/v1/fills`	50 / 200	`height:seq:is_taker`	—
`GET /api/v1/orders`	50 / 200	`closed_at_ms:order_id`	`status=open` 列表不支持游标，走 offset 分页
`GET /api/v1/fund-flows`	50 / 200	`height:seq`	—
`GET /api/v1/bridge-flows`	50 / 200	`height:seq`	—
`GET /api/v1/positions`	50 / 200	`height:seq`	—
`GET /api/v1/account/events`	50 / 200	`height:seq`	—
`GET /api/v1/referral/events`	50 / 200	`height:seq`	—
`GET /api/v1/rebate/events`	50 / 200	`height:seq`	—
`GET /api/v1/blocks/{id}/events`	500 / 2000	无（offset 分页）	单块事件，天然有界
`GET /api/v1/referral/referees`	50 / 200	无（offset 分页）	—
`GET /api/v1/referral/leaderboard`	50 / 200	无（offset 分页）	—
`GET /api/v1/leaderboard`	100 / 500	无（offset 分页）	排名上限 500，见 §5

游标字符串是 opaque 的：客户端必须把上一页的 next_cursor 原样传回，不要自行拼接。

排名上限 LEADERBOARD_MAX_RANK = 500：total 与 offset 都被截断到 500 以内。
排行数据由物化快照服务（每小时刷新）：meta.as_of_timestamp_ms = 快照刷新时间；meta.as_of_height = 统计水位。
例外：metric=equity & period=all 走节点内存热缓存，meta.source = "node"，as_of 为热缓存刷新时间；其余 source = "local"。