> For the complete documentation index, see [llms.txt](https://txnlab.gitbook.io/haystack-dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://txnlab.gitbook.io/haystack-dev/haystack-api/leaderboards.md).

# Leaderboards & Liftoff

Haystack's all-time trading and referral leaderboards, and the weekly Liftoff competition.

All paths are under `https://api.hay.app/api`. The full schemas are in the [OpenAPI specification](https://api.hay.app/info/openapi3.yaml). The prediction-market leaderboards are on [Prediction Markets](/haystack-dev/haystack-api/prediction-markets.md#leaderboards).

## All-time leaderboards

| Endpoint               | Ranks Haystack accounts by                                                                                                                |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /topTraderVolume` | Lifetime USD volume traded: `[{ account, nfd, nfdAvatar, totalTradedUsd }]`.                                                              |
| `GET /topReferrers`    | Referrals: `[{ account, nfd, nfdAvatar, referredCount, referredVolumeUsd }]`, how many accounts each referred and their total USD volume. |

Both take `limit` (1 to 40, default 40) and `offset` (0 to 160, default 0), so they reach the top 200. A larger `offset` gets `400`. Ties are ordered by account, so pages never repeat or skip one.

## Liftoff

Liftoff is Haystack's weekly HayLaunch competition. A round runs from Monday 00:00 UTC to the next Monday and counts bonding-curve trades in tokens launched during the round:

* The creators of the three tokens with the most volume win HAY.
* Haystack accounts get one raffle ticket per $1 they traded.

After the round, the raffle is drawn from a seed fixed by a later Algorand block.

Every endpoint takes `round`: the round's first day, a Monday (`2026-11-09`). Leave it out for the current round. Finished rounds keep answering. A day that isn't a Monday, a round before the first (2026-11-09) or a future round gets `400`.

| Endpoint                     | Returns                                                                                                                                                                                                   |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /points/liftoff`        | Raffle tickets: `[{ account, nfd, nfdAvatar, totalTradedUsd }]`, most first. `totalTradedUsd` is the ticket count.                                                                                        |
| `GET /points/liftoff/tokens` | The round's tokens by curve volume, including tokens with no trades: `[{ assetId, creator, score, traders, creatorVolume }]`. `score` is the USD volume and `creatorVolume` the creator's own part of it. |
| `GET /points/liftoff/round`  | The round's totals and prizes. See below.                                                                                                                                                                 |

The two lists take `limit` (20 to 100, default 100) and `offset` (0 to 10,000).

`points/liftoff/round` returns:

* `round`, `start`, `end` (exclusive), `final` (the round has ended) and `recorded` (results are recorded).
* `tokens`, `traders` and `volumeUsd`.
* The raffle: `rafflePoolHay`, `rafflePrizeHay` and `raffleDraws`. While the round runs, `nextPoolStepUsd` and `nextPoolHay` give the volume at which the pool next grows.
* `creatorPrizes`: `[{ place, assetId, creator, hay, txnId }]`, the standings so far until recorded.
* `raffle`, once drawn: `seed`, `seedRound`, `ticketsSha256`, `totalTickets`, `draws` and `winners`. The seed and the round's tickets reproduce the winners.

HAY amounts are in whole HAY. `txnId` appears once a prize is paid.

## Rate limits

| Endpoint                              | Requests per minute |
| ------------------------------------- | ------------------- |
| `points/liftoff`, `/tokens`, `/round` | 60                  |
| `topTraderVolume`, `topReferrers`     | 30                  |
