> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qfex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 推广员挑战赛排行榜

> 通过公开 REST API 读取挑战赛排名和奖池。

推广员可以使用公开 REST API，在自己的网站上展示其拥有的挑战赛排名。这些接口公开列于文档，但请求仍须使用具有 `view_balance` 权限的 [API 密钥](https://docs.qfex.com/cn/api-reference/api-keys.md)签名。API 密钥所属用户必须是挑战赛的推广员。请将私密密钥保存在服务器上，并且只向预期受众展示排名。

## 接口

| 接口 | 返回内容 |
| - | - |
| `GET /affiliate-challenges/owned` | 已认证推广员拥有的挑战赛，位于 `challenges` 数组中，包含各挑战赛的 ID 和配置。 |
| `GET /affiliate-challenges/{challenge_id}/owner-leaderboard` | 指定挑战赛的配置、奖池、奖金分配比例和参赛者排名。 |

调用排行榜接口时，使用第一个接口返回的挑战赛 ID。若 API 密钥所属用户没有挑战赛，列表接口返回 `403`。若挑战赛不存在或属于其他推广员，排行榜接口返回 `404`；参赛者也不能调用该推广员专用接口。

## 排行榜数据

排行榜响应包含 `title`、`description`、`starts_at`、`expires_at`、`as_of`、`auto_enroll`、`volume`、`base_prize_usd`、`max_volume_usd`、`max_prize_usd`、`prize_pool_usd` 和 `payouts`。`data` 数组中的每一行代表一名已排名的参赛者：

| 字段 | 含义 |
| - | - |
| `rank`、`user_id`、`username` | 参赛者名次及身份。 |
| `maker_volume_usd`、`taker_volume_usd`、`volume` | 挂单、吃单及总交易量。 |
| `pnl`、`score` | 挑战赛盈亏及排名分数。 |
| `payout_usd` | 按当前奖池和分配比例计算的预计奖金。 |

排名分数为 `sqrt(max(volume, 0)) * max(pnl, 0)`。奖池从 `base_prize_usd` 开始，随挑战赛交易量线性增长；当交易量达到 `max_volume_usd` 时，奖池达到 `max_prize_usd`。`payouts` 数组包含各获奖名次的配置百分比。`payout_usd` 是预计金额，并不表示奖金已经发放。

交易指标只计入完整的协调世界时（UTC）小时，并在挑战赛到期后停止更新。可用 `as_of` 显示排名的计算时间。建议每过一个整点后获取一次新排名，无须每次加载页面都请求。

## 网站访问控制

请从网站后端调用这些接口。不要在浏览器代码中放入 API 私密密钥，也不要向未经授权的访客暴露原始 API 响应。QFEX 会验证 API 调用者是否拥有挑战赛；您的网站须将展示范围限制为推广员及其直接推荐的参赛者。响应包含 `Cache-Control: private, no-store`。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.