> ## 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.

# Affiliate challenge leaderboards

> Read your challenge standings and prize pool through the public REST API.

Affiliates can use the public REST API to display their own challenge standings on their websites. These routes are publicly documented but require a signed [API key](https://docs.qfex.com/api-reference/api-keys.md) request with the `view_balance` permission. The API key's user must own the challenge. Keep the secret key on your server and serve standings only to your intended audience.

## Routes

| Route | Returns |
| - | - |
| `GET /affiliate-challenges/owned` | The authenticated affiliate's challenges in a `challenges` array, including each challenge's ID and configuration. |
| `GET /affiliate-challenges/{challenge_id}/owner-leaderboard` | One owned challenge's configuration, prize pool, payout distribution, and ranked participants. |

Use a challenge ID from the first route when requesting its leaderboard. The list route returns `403` if the API key's user owns no challenges. The leaderboard route returns `404` if the challenge does not exist or belongs to another affiliate, including when the caller is a participant.

## Leaderboard data

The leaderboard response includes `title`, `description`, `starts_at`, `expires_at`, `as_of`, `auto_enroll`, `volume`, `base_prize_usd`, `max_volume_usd`, `max_prize_usd`, `prize_pool_usd`, and `payouts`. The `data` array contains one row per ranked participant:

| Field | Meaning |
| - | - |
| `rank`, `user_id`, `username` | Participant position and identity. |
| `maker_volume_usd`, `taker_volume_usd`, `volume` | Maker, taker, and total traded volume. |
| `pnl`, `score` | Challenge PnL and ranking score. |
| `payout_usd` | Projected prize at the current pool size and payout distribution. |

Participants are ranked by `sqrt(max(volume, 0)) * max(pnl, 0)`. The prize pool starts at `base_prize_usd` and increases linearly with challenge volume until it reaches `max_prize_usd` at `max_volume_usd`. The `payouts` array provides the configured percentage for each winning rank; `payout_usd` is a projection, not a completed payment.

Trade metrics include complete UTC hours only and stop advancing at challenge expiry. Use `as_of` to show when the standings were last calculated. Fetch fresh standings after an hour boundary rather than on every page view.

## Website access

Call these routes from your website's backend. Never put the API secret in browser code or expose the raw API response to unauthorized visitors. QFEX checks that the API caller owns the challenge; your website must restrict its displayed standings to the affiliate and the affiliate's directly referred participants. Responses include `Cache-Control: private, no-store`.


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