curl -sS \
-H "Authorization: Bearer $OXINSIDER_API_KEY" \
'https://api.0xinsider.com/api/v1/games/nba-bos-orl-2026-11-01/holders?condition_ids=0x5e1f...,0x9a7b...&limit=10'import requests
url = "https://api.0xinsider.com/api/v1/games/{event_slug}/holders"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.0xinsider.com/api/v1/games/{event_slug}/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://api.0xinsider.com/api/v1/games/{event_slug}/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 => [
"Authorization: Bearer <token>"
],
]);
$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://api.0xinsider.com/api/v1/games/{event_slug}/holders"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.0xinsider.com/api/v1/games/{event_slug}/holders")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.0xinsider.com/api/v1/games/{event_slug}/holders")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"object": "game_holders_batch",
"data": [
{
"index": 0,
"input": "0x5e1f0c2a9b7d4e83a6c1f2b09d8e7a6c5b4f3e2d1c0b9a8f7e6d5c4b3a291807",
"status": "ok",
"data": {
"data": [
{
"id": "pos_0x4b1c9a2e7d3f5a6b8c0d1e2f3a4b5c6d7e8f9a0b:0x5e1f0c2a9b7d4e83a6c1f2b09d8e7a6c5b4f3e2d1c0b9a8f7e6d5c4b3a291807:0",
"trader_id": "trd_0x4b1c9a2e7d3f5a6b8c0d1e2f3a4b5c6d7e8f9a0b",
"address": "0x4b1c9a2e7d3f5a6b8c0d1e2f3a4b5c6d7e8f9a0b",
"name": "courtside",
"side": "YES",
"token_id": "71321045679252212594626385532706912750332728571942532289631379312455583992563",
"grade": "S",
"shares": 18250,
"current_value_usd": 9672.5,
"last_traded_at": "2026-11-01T22:41:07Z",
"category_win_rate_status": "measured",
"category_win_rate": 0.6097,
"category_win_record": {
"wins": 214,
"decided": 351
}
}
],
"has_more": true,
"total": 14,
"market": {
"id": "mkt_0x5e1f0c2a9b7d4e83a6c1f2b09d8e7a6c5b4f3e2d1c0b9a8f7e6d5c4b3a291807",
"condition_id": "0x5e1f0c2a9b7d4e83a6c1f2b09d8e7a6c5b4f3e2d1c0b9a8f7e6d5c4b3a291807",
"protocol_version": "v1",
"title": "Celtics vs. Magic: O/U 219.5",
"slug": "nba-bos-orl-2026-11-01-total-219pt5",
"event_slug": "nba-bos-orl-2026-11-01",
"category": "Sports",
"outcome_yes": "Over",
"outcome_no": "Under",
"token_id_yes": "71321045679252212594626385532706912750332728571942532289631379312455583992563",
"token_id_no": "52114319501245915516055106046884209969926127482827954674443846427813813222426",
"end_date": "2026-11-02T03:00:00Z",
"status": "open"
},
"scan": {
"source": "cached",
"complete": true,
"fetched_at": "2026-11-01T23:02:11Z",
"wallet_count": 412
},
"totals": {
"graded_count": 14,
"yes_count": 9,
"no_count": 5,
"yes_shares": 61840,
"no_shares": 20115,
"yes_usd": 32775.2,
"no_usd": 9454.05,
"yes_grades": {
"s": 2,
"a": 3,
"b": 4
},
"no_grades": {
"s": 0,
"a": 2,
"b": 3
},
"yes_grade_usd": {
"s": 14210,
"a": 10380.5,
"b": 8184.7
},
"no_grade_usd": {
"s": 0,
"a": 5120.3,
"b": 4333.75
}
},
"computed_at": "2026-11-01T23:02:14Z",
"cached": true,
"stale": false
}
},
{
"index": 1,
"input": "0x9a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b",
"status": "error",
"error": {
"code": "rate_limit_unavailable",
"message": "This read model is still warming. Retry after 3s.",
"reason": "read_model_warming",
"retry_at": "2026-11-01T23:02:20Z",
"doc_url": "https://docs.0xinsider.com/api-reference/introduction"
}
}
],
"meta": {
"request_id": "req_example",
"cached": false,
"total_items": 2,
"successful_items": 1,
"failed_items": 1,
"request_cost": 2,
"rate_limit": {
"basis": "batch_items_per_minute",
"limit": 2500,
"remaining": 2489,
"reset": 1790047440
}
}
}Game holders
Get the S, A, and B wallets holding up to 25 markets of one game, in the order you request them.
curl -sS \
-H "Authorization: Bearer $OXINSIDER_API_KEY" \
'https://api.0xinsider.com/api/v1/games/nba-bos-orl-2026-11-01/holders?condition_ids=0x5e1f...,0x9a7b...&limit=10'import requests
url = "https://api.0xinsider.com/api/v1/games/{event_slug}/holders"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.0xinsider.com/api/v1/games/{event_slug}/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://api.0xinsider.com/api/v1/games/{event_slug}/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 => [
"Authorization: Bearer <token>"
],
]);
$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://api.0xinsider.com/api/v1/games/{event_slug}/holders"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.0xinsider.com/api/v1/games/{event_slug}/holders")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.0xinsider.com/api/v1/games/{event_slug}/holders")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"object": "game_holders_batch",
"data": [
{
"index": 0,
"input": "0x5e1f0c2a9b7d4e83a6c1f2b09d8e7a6c5b4f3e2d1c0b9a8f7e6d5c4b3a291807",
"status": "ok",
"data": {
"data": [
{
"id": "pos_0x4b1c9a2e7d3f5a6b8c0d1e2f3a4b5c6d7e8f9a0b:0x5e1f0c2a9b7d4e83a6c1f2b09d8e7a6c5b4f3e2d1c0b9a8f7e6d5c4b3a291807:0",
"trader_id": "trd_0x4b1c9a2e7d3f5a6b8c0d1e2f3a4b5c6d7e8f9a0b",
"address": "0x4b1c9a2e7d3f5a6b8c0d1e2f3a4b5c6d7e8f9a0b",
"name": "courtside",
"side": "YES",
"token_id": "71321045679252212594626385532706912750332728571942532289631379312455583992563",
"grade": "S",
"shares": 18250,
"current_value_usd": 9672.5,
"last_traded_at": "2026-11-01T22:41:07Z",
"category_win_rate_status": "measured",
"category_win_rate": 0.6097,
"category_win_record": {
"wins": 214,
"decided": 351
}
}
],
"has_more": true,
"total": 14,
"market": {
"id": "mkt_0x5e1f0c2a9b7d4e83a6c1f2b09d8e7a6c5b4f3e2d1c0b9a8f7e6d5c4b3a291807",
"condition_id": "0x5e1f0c2a9b7d4e83a6c1f2b09d8e7a6c5b4f3e2d1c0b9a8f7e6d5c4b3a291807",
"protocol_version": "v1",
"title": "Celtics vs. Magic: O/U 219.5",
"slug": "nba-bos-orl-2026-11-01-total-219pt5",
"event_slug": "nba-bos-orl-2026-11-01",
"category": "Sports",
"outcome_yes": "Over",
"outcome_no": "Under",
"token_id_yes": "71321045679252212594626385532706912750332728571942532289631379312455583992563",
"token_id_no": "52114319501245915516055106046884209969926127482827954674443846427813813222426",
"end_date": "2026-11-02T03:00:00Z",
"status": "open"
},
"scan": {
"source": "cached",
"complete": true,
"fetched_at": "2026-11-01T23:02:11Z",
"wallet_count": 412
},
"totals": {
"graded_count": 14,
"yes_count": 9,
"no_count": 5,
"yes_shares": 61840,
"no_shares": 20115,
"yes_usd": 32775.2,
"no_usd": 9454.05,
"yes_grades": {
"s": 2,
"a": 3,
"b": 4
},
"no_grades": {
"s": 0,
"a": 2,
"b": 3
},
"yes_grade_usd": {
"s": 14210,
"a": 10380.5,
"b": 8184.7
},
"no_grade_usd": {
"s": 0,
"a": 5120.3,
"b": 4333.75
}
},
"computed_at": "2026-11-01T23:02:14Z",
"cached": true,
"stale": false
}
},
{
"index": 1,
"input": "0x9a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b",
"status": "error",
"error": {
"code": "rate_limit_unavailable",
"message": "This read model is still warming. Retry after 3s.",
"reason": "read_model_warming",
"retry_at": "2026-11-01T23:02:20Z",
"doc_url": "https://docs.0xinsider.com/api-reference/introduction"
}
}
],
"meta": {
"request_id": "req_example",
"cached": false,
"total_items": 2,
"successful_items": 1,
"failed_items": 1,
"request_cost": 2,
"rate_limit": {
"basis": "batch_items_per_minute",
"limit": 2500,
"remaining": 2489,
"reset": 1790047440
}
}
}condition_id values from List game markets, and check each result’s status, because individual markets can fail.
Each ok result is what Market holders returns for that market with no outcome or min_grade filter, cut to limit. To read the next page of one market, or to filter by side or grade, call Market holders with its condition_id.
Parameters
| Parameter | Description |
|---|---|
event_slug | Required. The game’s event slug, for example nba-bos-orl-2026-11-01. Matching is case-insensitive. |
condition_ids | Required. 1 to 25 market ids, comma-separated or repeated: Polymarket’s condition_id or the mkt_ form. Duplicates are allowed, and each one gets its own result row. |
limit | Optional. How many holders to return per market, from 1 to 100. The default is 20, and a value outside the range is clamped. |
400 before any market is read. A slug with no stored market is a 404, as on List game markets.
Key response fields
| Field | Meaning |
|---|---|
data[].index | Where this market sat in condition_ids, counting from 0. |
data[].input | The id exactly as you sent it. |
data[].status | ok, with data, or error, with error.code, error.message, and error.param. |
data[].data | The market’s holders: data (the holder rows), has_more, total, market, scan, totals, category_records_as_of, computed_at, cached, and stale. Each field but stale means what it means on Market holders. |
data[].data.market.protocol_version | The Polymarket protocol the market trades on: v1 (CTF) or v2 (Protocol V2), as on GET /api/v1/market/{condition_id}/holders. |
data[].data.stale | true when the market’s fresh holder list was not ready in time and this is the last list computed for it, up to 15 minutes old. Read computed_at for its age. false on a fresh list. |
data[].error.code | not_found when the market is not one of this game’s markets, bad_request when an id is malformed, rate_limit_unavailable with error.reason read_model_warming when the market has no holder list from the past 15 minutes and its scan did not finish in time, and rate_limited with error.reason cold_read_limited when the market needed a fresh Polymarket scan over your account’s share and has no recent list. Branch on error.reason: the code of read_model_warming is kept for compatibility. The HTTP response remains 200 in each case. |
meta.request_cost | The batch item units charged: 1 for every id you sent, duplicates and bad ids included. |
meta.rate_limit | Your remaining batch item budget: basis, limit, remaining, and reset. |
Markets that are not ready
A market whose holder list is not cached needs a Polymarket scan, and the request waits for it only briefly. When the scan is still running, the market comes back with the last holder list computed for it in the past 15 minutes, markedstale: true. The scan keeps running, so the same request a few seconds later returns the fresh list.
A market with no list from the past 15 minutes comes back as a read_model_warming error with a retry time instead. A market over your account’s scan share is served its last list the same way, and is a cold_read_limited error only without one. Uncached markets count against the same scan share as Market holders.
Item budget
This route spends from the batch item budget that the batch routes share: 2,500 units a minute per account on Pro, or 10,000 on Max, alongside the request allowance. Going over returns429 with a Retry-After before any market is read.
Example
curl -sS \
-H "Authorization: Bearer $OXINSIDER_API_KEY" \
'https://api.0xinsider.com/api/v1/games/nba-bos-orl-2026-11-01/holders?condition_ids=0x123...,0x456...&limit=10'
get_game_holders MCP tool and the SDK’s getGameHolders method call this endpoint.
What it does not return
- Holders of a market from another game. Its row is
not_found. - An
ETag. This route has no conditional read. - More than
limitholders per market. Page past it with Market holders.
Authorizations
Legacy default or named integration API key, or OAuth 2.1 access token, in the Authorization header as Bearer oxi_sk_live_... or Bearer oxi_at_.... Default keys retain full access; integration keys are limited to their approved read, webhooks, export and usage scopes and expire within 90 days. All credentials share the owner's account limits. Data calls require an active Pro subscription and return live data. A 401 carries WWW-Authenticate: Bearer resource_metadata="https://api.0xinsider.com/.well-known/oauth-protected-resource" (RFC 6750 section 3, RFC 9728).
Scopes
Headers
Opt into strict query-name validation. The default is compatible: unknown names are ignored and reported in X-Query-Ignored. With strict, an unknown name returns 400 bad_request with error.reason unknown_query_parameter before the handler runs, including when its percent escape is incomplete.
strict Path Parameters
Query Parameters
kickoff: each market's roster as it stood at the game's kickoff, as GET /api/v1/market/{condition_id}/holders?as_of=kickoff serves it (#34064), read for every market in one query with no wait, no walk and no cold-read share. Each ok item carries as_of and data_quality, computed_at is its capture, cached is true and stale is false. A market until 30 s after kickoff is an item error with reason kickoff_roster_pending and retry_at at that instant; a market with no stored kickoff roster is an item error with reason kickoff_roster_not_captured. Omit it for the current rosters; any other value is 400 bad_request with param=as_of.
kickoff Was this page helpful?