---
title: "Get top traders leaderboard"
method: GET
path: "/v4/data/prediction/top-traders"
tags: ["Prediction API"]
---

# Get top traders leaderboard

`GET /v4/data/prediction/top-traders`

/v4/data/prediction/top-traders

**200 credits per API call**

Ranked leaderboard of top traders, scoped by category and time period. Each row carries the trader's wallet, display fields (username, X handle, profile image), verified-badge status, and the metrics used for ranking (volume and PnL within the requested window).

**Platform support**

*   Polymarket only.

**Filtering, sorting and pagination**

*   `category` selects the leaderboard slice — one of `OVERALL`, `POLITICS`, `SPORTS`, `CRYPTO`, `CULTURE`, `MENTIONS`, `WEATHER`, `ECONOMICS`, `TECH`, `FINANCE`. Defaults to `OVERALL`.
*   `timePeriod` sets the lookback window — `DAY`, `WEEK`, `MONTH`, `ALL`. Defaults to `DAY`.
*   `orderBy` chooses the ranking metric: `PNL` (realised + unrealised profit) or `VOL` (trading volume). Defaults to `PNL`.
*   `user` filters the leaderboard to a single wallet — useful for "where does this trader rank" lookups. `userName` filters by trader display name (substring match).
*   Pagination is offset-based — `limit` (1..50, default 25) and `offset` (0..1000, default 0). Higher offsets are not supported by the upstream leaderboard.

**Other notes**

*   `rank` is the continuous 1-indexed position given the requested filters — `rank = 1` is the leader for the chosen category and time period.
*   `proxyWallet` is returned lowercased.
*   `vol` and `pnl` are USD figures, scoped to the requested `category` and `timePeriod`.

## Query parameters

- `category` 'OVERALL' | 'POLITICS' | 'SPORTS' | 'CRYPTO' | 'CULTURE' | 'MENTIONS' | 'WEATHER' | 'ECONOMICS' | 'TECH' | 'FINANCE' — Leaderboard category slice.
- `timePeriod` 'DAY' | 'WEEK' | 'MONTH' | 'ALL' — Leaderboard lookback window.
- `orderBy` 'PNL' | 'VOL' — Leaderboard ranking metric. `PNL` = realised + unrealised profit; `VOL` = trading volume.
- `limit` integer
- `offset` integer
- `user` string
- `userName` string

## Response `200`

OK

- PredictionTopTradersResponse — Paginated top-traders leaderboard response.
  - `data` PredictionTopTrader[], required
    - `rank` integer, required — Continuous 1-indexed position in the leaderboard given the requested filters.
    - `proxyWallet` string, required — Trader wallet (0x + 40 hex, lowercased).
    - `userName` string, nullable, required — Trader display name, when set.
    - `xUsername` string, nullable, required — Trader's X (Twitter) handle, when linked.
    - `verifiedBadge` boolean, required — Whether the trader has a verified-badge on their profile.
    - `vol` number, required — Trading volume (USD) within the requested `timePeriod` for the requested `category`.
    - `pnl` number, required — Realised + unrealised PnL (USD) within the requested `timePeriod` for the requested `category`.
    - `profileImage` string, nullable, required — Trader profile image URL, when set.
  - `pagination` PredictionPageSizePagination, required — Minimal pagination metadata used by endpoints that paginate via `offset` + `limit` and don't surface a derived `pageNumber`.
    - `pageSize` integer, required — Page size of the call that produced this response.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized. Not valid or inactive subscription key present in the HTTP Header.
- `403` — Forbidden. The request is authenticated, but it is not possible to perform the operation due to logical error or invalid permissions.
- `500` — Internal server error. There was an error on the server during the processing of the request.

---

[API](https://skmtc.net/tatum/apis/blockchain-data.md) · [All operations](https://skmtc.net/tatum/apis/blockchain-data/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tatum/blockchain-data/versions/8622ee4b8fae/schema)