---
title: "Get top token holders for one or more markets"
method: GET
path: "/top-holders"
tags: ["Trader Analytics"]
---

# Get top token holders for one or more markets

`GET /top-holders`

## Request

- Base URL: `https://data.kairos.trade`
- URL: `https://data.kairos.trade/top-holders`
- Auth: API key in header `X-Client-Id` and API key in header `X-Api-Key` and API key in header `X-Api-Secret`

Fetches the largest holders of each outcome token for the given market IDs from the provider-specific upstream source, including Polymarket's data-api and Predict.fun's public GraphQL API. `market` accepts a comma-separated list (up to 50 IDs, each capped at 128 chars); Predict.fun requires numeric market IDs. An empty or missing value is rejected with 400. Results are grouped per token/outcome and include public profile fields (username, verification badge, avatar) alongside the held `amount`. This is a live upstream read, not served from a local cache; a downstream 4xx/5xx from the provider surfaces as 404 (market/token not found) or 502 (provider error). **Auth**: accepts an admin secret (`X-Admin-Secret`), an API key (`X-Client-Id` + `X-Api-Key` + `X-Api-Secret`), or a first-party JWT (Authorization header or `turnkey_session_jwt` cookie). No API-key scope is required — any valid credential can read holders. Rate-limited by the `heavy` group at 10 requests/minute, the same budget the `/trader-stats` endpoints carry, because every call is a live upstream provider read.

## Query parameters

- `market` string, required
- `provider` string
- `limit` integer
- `minBalance` integer

## Response `200`

Top holders per requested token.

- TraderTopHoldersToken[]: Top holders grouped by outcome token, one entry per requested market/token combination returned by the provider. The endpoint returns this array directly as the response body (not wrapped in an object).
  - `token` string, required: Outcome token id.
  - `holders` TraderTopHolder[], required
    - `proxyWallet` string, required: Holder's wallet address.
    - `amount` number, double, required: Token amount held.
    - `outcomeIndex` integer, required: Index of the outcome token held (0 = first outcome, 1 = second, ...).
    - `displayUsernamePublic` boolean, required: Whether the holder has opted to publicly display their username.
    - `verified` boolean, required: Whether the holder has a verified badge.
    - `name` string: Present only when the provider returned a display name.
    - `pseudonym` string
    - `bio` string
    - `asset` string: Underlying asset identifier for the held token, when the provider supplies one.
    - `profileImage` string
    - `profileImageOptimized` string

## Other responses

- `400`: Missing/empty `market`, too many market IDs, an oversized market ID, an invalid `provider`, or an invalid request accepted by the provider client.
- `401`: No valid credential presented — missing/invalid API-key headers, or an invalid/expired session token.
- `403`: Authenticated but not permitted. Three distinct causes: the session user is not invited (`Invite required`), the API key lacks the operation's scope, or API-key access to the requested venue is switched off (`API access is disabled for <provider>`). Admin and API-key callers bypass the invite check; session and admin callers bypass scope and venue checks.
- `404`: Market or token not found by the upstream provider.
- `422`: Request failed FastAPI parameter validation.
- `429`: Rate limit exceeded for this route's sliding window, keyed on the session `sub` when authenticated and on the trusted client IP otherwise. Honor `Retry-After`. A per-API-key data ceiling (set per credential) rejects with `{"detail": "API key data rate limit exceeded"}` instead of the `error` envelope below.
- `502`: Upstream provider error fetching top holders.

---

[API](https://skmtc.dev/kairos/apis/kairos-data-api.md) - [All operations](https://skmtc.dev/kairos/apis/kairos-data-api/llms.txt) - [OpenAPI document](https://skmtc.dev/kairos/apis/kairos-data-api/revisions/cf6b76079e38?raw)