推荐/返佣/排行

本页是推荐 / 返佣 / 排行榜 / 账户累计统计 相关接口：JSON-RPC 读方法与历史 REST。

getReferral

用户推荐关系。

参数	类型	必填	说明
address	Address20	是	账户地址

响应 data： address / referred_by_code(String?, 被谁推荐，null=未绑定) / referral_code(String?, 自己的推荐码，null=未注册) / n_referrals(u64)

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": {
      "address": "0x1111222233334444555566667777888899990000",
      "referred_by_code": "ALICE-001",
      "referral_code": "BOB-TRADE",
      "n_referrals": 12
    }
  }
}

返佣配置字段（inviter_rebate_ratio_bps、inviter_keep_ratio_bps）在 [getAccount../trading/account.md#getaccount 返回，不在本接口重复。

返佣流水： 无专用读方法。按块扫 [getBlockEvents../history/blocks.md#getblockevents，过滤 kind.Core.RebatePaid（字段见 events.md §2）；同块成对 BalanceChanged{RebateToInviter/RebateToInvitee} 可用于余额对账。Admin 改全局/档位审计见 [getAdminAuditLog../system/endpoints.md#getadminauditlog（Ops::GlobalRebateRatioChanged / AccountRebateRatioChanged）。

---

getTopAccounts

账户排行（有界全扫描 + 排序）。

参数	类型	必填	说明
sort_by	TopSortKey	是	"balance" 按余额 · "equity" 按权益
limit	usize	否	默认 50，最大 50

响应 data · TopAccountItem[]： address / balance(SCALE_6) / account_value(SCALE_6)

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": [{
      "address": "0x1111222233334444555566667777888899990000",
      "balance": "1000000.000000",
      "account_value": "1050000.000000"
    }],
    "page": { "offset": 0, "limit": 50, "total": 1024 }
  }
}

推荐关系（REST）

链上推荐由 SetReferrer / RegisterReferrer 写操作与 Core::ReferrerRegistered / ReferrerBound 事件驱动（见 Chain API）。节点在 derive worker 中物化推荐索引，语义对齐链节点 getReferral 与 listAccounts 的 referral_code / referred_by_code 过滤。

链层概念	读侧字段	说明
账户自有推荐码	referral_code	RegisterReferrer 注册，全局唯一
绑定的上级推荐码	referred_by_code	SetReferrer 绑定，每账户仅一次
上级地址	referrer_address	由 referred_by_code 反查码主地址
邀请人数	n_referrals	绑定本账户 referral_code 的用户数

链上返佣由 Core::RebatePaid 事件驱动；节点在 derive worker 中物化返佣明细与累计统计，语义对齐链层 event 文档（无专用 getRebateHistory 读方法）。

GET /api/v1/referral

查询账户推荐快照或按推荐码反查码主。

Query（二选一，必填其一）

Param	Type	Description
address	string	账户地址 → 返回 ReferralSummary（对齐链 getReferral + 上级地址解析）
code	string	推荐码 → 返回 ReferralCodeView（码主 + 邀请数）

Response 200（address）

{
  "data": {
    "address": "0xabc…",
    "referral_code": "ALICE",
    "referred_by_code": "BOB",
    "referrer_address": "0xdef…",
    "n_referrals": 12,
    "registered_height": 100,
    "registered_at_ms": 1700000000000,
    "bound_height": 50,
    "bound_at_ms": 1699999000000
  }
}

未注册/未绑定时对应字段省略；n_referrals 恒为 number（无邀请时为 0）。

Response 200（code）

{
  "data": {
    "referral_code": "ALICE",
    "owner": "0xabc…",
    "n_referrals": 12,
    "last_bound_ms": 1700000000000
  }
}

Response 404：推荐码不存在（code 查询）。

---

GET /api/v1/referral/events

账户推荐相关 event 历史（ReferrerRegistered / ReferrerBound）。

Query

Param	Type	Required	Default	Max	Description
account	string	yes	—	—	账户地址
event_type	string	no	—	—	ReferrerRegistered | ReferrerBound
from_block	number	no	—	—	最小区块高度（含）
to_block	number	no	—	—	最大区块高度（含）
offset	number	no	0	—	分页偏移
limit	number	no	50	200	页大小

Response 200：Paged<ReferralEventRecord>，含 envelope_idx / tx_hash 溯源字段。

Response 200

{
  "data": [{
    "height": 12340,
    "seq": 2,
    "timestamp_ms": 1717199000000,
    "event_type": "ReferrerBound",
    "account": "0x1111222233334444555566667777888899990000",
    "code": "ALICE-001",
    "envelope_idx": 1,
    "tx_hash": "0xabc…"
  }],
  "page": { "offset": 0, "limit": 50, "total": 3 }
}

---

GET /api/v1/referral/referees

某推荐码邀请的用户列表（对齐链 listAccounts?referred_by_code=）。

Query（二选一，必填其一）

Param	Type	Description
code	string	推荐码
address	string	账户地址（使用该账户的 referral_code 查邀请列表）

Param	Type	Default	Max	Description
offset	number	0	—	分页偏移
limit	number	50	200	页大小

Response 200：Paged<ReferralReferee>，按绑定区块高度 新→旧。

若 address 查询且该账户未注册推荐码，返回空列表 { "data": [], "page": { "total": 0, ... } }（非错误）。

Response 200

{
  "data": [{
    "address": "0x2222333344445555666677778888999900001111",
    "referred_by_code": "BOB-TRADE",
    "bound_height": 12340,
    "bound_at_ms": 1717199000000,
    "bound_tx_hash": "0xdef…"
  }],
  "page": { "offset": 0, "limit": 50, "total": 12 }
}

---

GET /api/v1/referral/leaderboard

推荐码邀请人数排行（n_referrals 降序）。

Query

Param	Type	Default	Max	Description
offset	number	0	—	分页偏移
limit	number	50	200	页大小

Response 200：Paged<ReferralLeaderboardEntry>

Response 200

{
  "data": [{
    "rank": 1,
    "referral_code": "BOB-TRADE",
    "owner": "0x1111222233334444555566667777888899990000",
    "n_referrals": 128,
    "last_bound_ms": 1717200000000
  }],
  "page": { "offset": 0, "limit": 50, "total": 42 }
}

---

返佣（REST）

链上返佣由成交 fee 抽成、Core::RebatePaid 汇总事件与成对 BalanceChanged{RebateToInviter/RebateToInvitee} 驱动（见 Chain API）。节点在 derive worker 中物化：

链层概念	读侧字段	说明
返佣分发	RebateEventRecord	每笔 RebatePaid 一行
邀请者入账	role=Inviter, amount=inviter_share	对应资金流水 RebateToInviter
交易者回分	role=Invitee, amount=invitee_share	对应资金流水 RebateToInvitee
累计已返佣	RebateSummary.total_received	邀请者 + 交易者回分之和

GET /api/v1/rebate

账户累计返佣快照。

Query

Param	Type	Required	Description
address	string	yes	账户地址

Response 200

{
  "data": {
    "address": "0xabc…",
    "total_received": "125.500000",
    "as_inviter_total": "100.000000",
    "as_invitee_total": "25.500000",
    "event_count": 42,
    "last_rebate_ms": 1700000000000
  }
}

无返佣记录时 total_* 为 "0"，event_count 为 0。

---

GET /api/v1/rebate/events

账户返佣明细（作为邀请者或交易者参与的分发记录）。

Query

Param	Type	Required	Default	Max	Description
account	string	yes	—	—	账户地址
role	string	no	—	—	Inviter | Invitee
from_block	number	no	—	—	最小区块高度（含）
to_block	number	no	—	—	最大区块高度（含）
offset	number	no	0	—	分页偏移
limit	number	no	50	200	页大小

Response 200：Paged<RebateEventRecord>，按区块高度 新→旧。

Response 200

{
  "data": [{
    "height": 12345,
    "seq": 5,
    "timestamp_ms": 1717200001000,
    "trader": "0x2222…",
    "inviter": "0x1111…",
    "referral_code": "BOB-TRADE",
    "total_amount": "10.000000",
    "inviter_share": "7.000000",
    "invitee_share": "3.000000",
    "role": "Inviter",
    "amount": "7.000000",
    "envelope_idx": 2,
    "tx_hash": "0xabc…"
  }],
  "page": { "offset": 0, "limit": 50, "total": 18 }
}

---

账户累计统计（REST）

由后台任务异步物化，不阻塞 ingest 主路径。数据来自本地 derive 索引（fill、fund_flow、bridge_flow），与 [GET /api/v1/leaderboard#get-apiv1leaderboard 共用 stats_watermark。

v1 仅支持 全量累计（period=all）；无历史记录的账户各字段为 "0"。

GET /api/v1/account-stats

Query

Param	Type	Required	Description
account	string	yes	账户地址

Response 200

{
  "data": {
    "account": "0xabcd…",
    "period": "all",
    "total_deposits": "500000.000000",
    "total_withdrawals": "1500.000000",
    "net_deposits": "498500.000000",
    "total_volume": "1050.000000",
    "trade_count": 6,
    "total_fees": "0.525000",
    "gross_profit": "120.000000",
    "gross_loss": "40.000000",
    "net_pnl": "80.000000",
    "as_of_height": 1824,
    "as_of_timestamp_ms": 1782445422805,
    "stale": false
  }
}

Field	Type	Description
period	string	v1 固定为 "all"
total_deposits	string	DepositCredited 累计（SCALE_6）
total_withdrawals	string	WithdrawSettled 累计（SCALE_6）
net_deposits	string	充值到账 − 提现申请 + 退款（ROI 分母，与 leaderboard 一致）
total_volume	string	账户成交额 SUM(fill.notional)（含 taker 与 maker 腿）
trade_count	number	成交笔数（fill 行数）
total_fees	string	账户支付手续费 SUM(fill.fee)
gross_profit	string	RealizedPnl 正数部分之和
gross_loss	string	RealizedPnl 负数部分绝对值之和
net_pnl	string	净已实现盈亏（gross_profit - gross_loss）；不含手续费
as_of_height	number | null	stats 聚合截至区块（stats_watermark）
as_of_timestamp_ms	number | null	索引库最新区块时间（ms）
stale	boolean	stats 未追上 derive 时为 true；false 时可能省略

指标口径

• 充提分项来自 bridge_flow；盈亏来自 fund_flow.reason = RealizedPnl；成交量/手续费来自 fill。
• 升级 stats 聚合版本（stats_agg_version）后会清空物化表并从 block 0 重算；无需删除 ingest 库，重启后等待 stats_lag_blocks 归零即可。
• 数据新鲜度：[GET /api/v1/status../system/endpoints.md#get-apiv1status 的 stats_watermark / stats_lag_blocks。

---

排行榜（REST）

排行榜由后台任务异步维护，不阻塞 ingest 主路径。 冷数据（成交量 / 已实现盈亏 / ROI）从本地索引聚合；热数据（余额 / 净值）定时从节点 getTopAccounts 刷新缓存。

GET /api/v1/leaderboard

Query

Param	Type	Required	Default	Max	Description
metric	string	yes	—	—	volume | realized_pnl | realized_roi | balance | equity
period	string	no	all	—	24h | 7d | 30d | all
offset	number	no	0	—	分页偏移
limit	number	no	100	500	页大小

所有排行榜最多返回 前 500 名（page.total 上限为 500）。

Period 支持矩阵

metric	24h / 7d / 30d	all
volume	✅	✅
realized_pnl	✅	✅
realized_roi	✅	✅
balance	✅（窗口内最近资金流水余额）	✅（全量索引最新余额）
equity	✅（节点快照历史）	✅（节点热缓存）

窗口语义

• balance（24h / 7d / 30d）：在窗口内有资金流水记录的账户，按其窗口内最后一次 new_balance 降序排名。
• balance（all）：全部已索引账户的当前最新余额。
• equity（24h / 7d / 30d）：窗口内节点净值快照历史，按账户窗口内最新 account_value 降序排名（stats worker 约 60s 写入一次快照，保留 31 天）。
• equity（all）：节点 getTopAccounts 热缓存（前 500 名）。

Response 200

{
  "data": [
    {
      "rank": 1,
      "account": "0xabcd…",
      "value": "1250000.00",
      "trade_count": 42,
      "auxiliary": null
    }
  ],
  "meta": {
    "metric": "volume",
    "period": "7d",
    "source": "local",
    "as_of_height": 12345,
    "as_of_timestamp_ms": 1717000000000,
    "stale": false
  },
  "page": { "offset": 0, "limit": 50, "total": 500 }
}

Field	Type	Description
rank	number	排名（1-based）
account	string	账户地址
value	string	排行主指标值
trade_count	number | null	仅 metric=volume 时返回
auxiliary	string | null	辅助指标（ROI 的区间 PnL；balance/equity 的余额等）

meta Field	Type	Description
metric	string	请求的 metric
period	string	请求的 period
source	string	local（SQLite 冷统计）或 node（节点热缓存，equity + all）
as_of_height	number | null	数据截至区块高度
as_of_timestamp_ms	number | null	数据截至时间（ms）
stale	boolean	热数据节点不可达时为 true

指标定义

• volume：每个账户 SUM(notional)（含 taker 与 maker 成交腿；全局不双计同一账户）
• realized_pnl：仅统计 fund_flow.reason = RealizedPnl 的账户（纯充值未交易者不会出现）
• realized_roi：realized_pnl / max(net_deposits, 1)，net_deposits 来自充提流水
• balance：全部有资金流水索引的账户最新余额（含充值、未交易者）
• balance / equity 窗口期语义见上

GET /api/v1/status 返回异步流水线各阶段 watermark 与 lag：derive_watermark、candle_watermark、stats_watermark 及对应 *_lag_blocks。

---