KAkairos
Trader Analytics

Get top token holders for one or more markets

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.

get/top-holders

Request

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

Query parameters

marketstring required

Comma-separated list of market/condition IDs (max 50 items, 128 chars each).

providerstring

Provider name, validated against the active provider registry. Examples include polymarket and predictfun.

limitinteger

Maximum number of holders to return per token.

minBalanceinteger

Minimum token balance a holder must have to be included.

Response

Top holders per requested token.

tokenstring required

Outcome token id.

Example response

[
  {
    "token": "10723948572...4",
    "holders": [
      {
        "proxyWallet": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
        "amount": 15230.5,
        "name": "whale_trader_99",
        "pseudonym": "SilentOwl-4821",
        "bio": "Prediction market degen.",
        "profileImage": "https://cdn.polymarket.com/avatars/abc.png",
        "profileImageOptimized": "https://cdn.polymarket.com/avatars/abc-opt.png"
      }
    ]
  }
]

Changes

No recorded changes to this operation across all 1 revision of this API.