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

curl --request GET \
  --url https://data.kairos.trade/top-holders \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Api-Secret: <api-key>' \
  --header 'X-Client-Id: <api-key>'

import requests

url = "https://data.kairos.trade/top-holders"

headers = {
    "X-Client-Id": "<api-key>",
    "X-Api-Key": "<api-key>",
    "X-Api-Secret": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {
    'X-Client-Id': '<api-key>',
    'X-Api-Key': '<api-key>',
    'X-Api-Secret': '<api-key>'
  }
};

fetch('https://data.kairos.trade/top-holders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://data.kairos.trade/top-holders",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: <api-key>",
    "X-Api-Secret: <api-key>",
    "X-Client-Id: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://data.kairos.trade/top-holders"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Client-Id", "<api-key>")
	req.Header.Add("X-Api-Key", "<api-key>")
	req.Header.Add("X-Api-Secret", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://data.kairos.trade/top-holders")
  .header("X-Client-Id", "<api-key>")
  .header("X-Api-Key", "<api-key>")
  .header("X-Api-Secret", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://data.kairos.trade/top-holders")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Client-Id"] = '<api-key>'
request["X-Api-Key"] = '<api-key>'
request["X-Api-Secret"] = '<api-key>'

response = http.request(request)
puts response.read_body

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

{
  "detail": "Not authenticated"
}

{
  "detail": "Invite required"
}

{
  "detail": [
    {}
  ]
}

{
  "error": "Rate limit exceeded: 100 per 1 minute"
}

Authorizations

X-Client-Id

string

header

required

Credential client id (kairos_ck_...). Must be sent together with X-Api-Key and X-Api-Secret.

X-Api-Key

string

header

required

64-char hex API key.

X-Api-Secret

string

header

required

64-char hex API secret.

Query Parameters

market

string

required

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

provider

string

default:polymarket

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

limit

integer

default:20

Maximum number of holders to return per token.

Required range: 1 <= x <= 20

minBalance

integer

default:1

Minimum token balance a holder must have to be included.

Required range: 0 <= x <= 999999

Response

Top holders per requested token.

token

string

required

Outcome token id.

Example:

"10723948572...4"

holders

object[]

required

Show child attributes

Get top token holders for one or more markets

curl --request GET \
  --url https://data.kairos.trade/top-holders \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Api-Secret: <api-key>' \
  --header 'X-Client-Id: <api-key>'

import requests

url = "https://data.kairos.trade/top-holders"

headers = {
    "X-Client-Id": "<api-key>",
    "X-Api-Key": "<api-key>",
    "X-Api-Secret": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {
    'X-Client-Id': '<api-key>',
    'X-Api-Key': '<api-key>',
    'X-Api-Secret': '<api-key>'
  }
};

fetch('https://data.kairos.trade/top-holders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://data.kairos.trade/top-holders",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: <api-key>",
    "X-Api-Secret: <api-key>",
    "X-Client-Id: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://data.kairos.trade/top-holders"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Client-Id", "<api-key>")
	req.Header.Add("X-Api-Key", "<api-key>")
	req.Header.Add("X-Api-Secret", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://data.kairos.trade/top-holders")
  .header("X-Client-Id", "<api-key>")
  .header("X-Api-Key", "<api-key>")
  .header("X-Api-Secret", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://data.kairos.trade/top-holders")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Client-Id"] = '<api-key>'
request["X-Api-Key"] = '<api-key>'
request["X-Api-Secret"] = '<api-key>'

response = http.request(request)
puts response.read_body

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

{
  "detail": "Not authenticated"
}

{
  "detail": "Invite required"
}

{
  "detail": [
    {}
  ]
}

{
  "error": "Rate limit exceeded: 100 per 1 minute"
}

Overview

Market Data API

Data API

Execution API

Agora Auction API

REST Guides

Market Data Guides

RPC Guides

RFQ Guides

WebSocket Guides

Krisis Guides

Get top token holders for one or more markets

Authorizations

Query Parameters

Response