- Required: Yes means the field is always present. Its value can still be
nullwhen the type allows it. - Required: No means the field can be omitted. An omitted value is not zero or an empty result.
- Type names a scalar, a nested object, or the allowed alternatives. For a named object, find its heading on this page.
AccountIdentity
| Field | Type | Required | Description |
|---|---|---|---|
object | account | Yes | |
data | object (user_id, credential_id, credential_kind, credential_status, entitlement, scopes) | Yes | |
meta | ResponseMeta | Yes |
AgentRegistration
A sandbox key and the path to live access (#13959). Nothing is stored: the key cannot be listed or revoked and does not expire. Register again for a new one.| Field | Type | Required | Description |
|---|---|---|---|
api_key | string | Yes | The sandbox key. Send it as Authorization: Bearer <api_key> to the sandbox. The last 8 hex characters are a checksum (the first 4 bytes of SHA-256 over the rest of the key), so the sandbox can tell a mistyped key from a real one. It is not a secret and unlocks no production data. |
livemode | boolean | Yes | Always false: this key never reaches live data. |
environment | string | Yes | |
created_at | string | Yes | |
sandbox | object (api_base_url, first_request_url, openapi_url) | Yes | |
live_access | object (api_base_url, requirement, api_keys_url, oauth_authorization_server_metadata_url, oauth_registration_endpoint, pricing_url, auth_guide_url) | Yes | What live data needs, and where each credential comes from. Both need a person: an account with an active Pro subscription. |
AnalyticInteger
A computed count with its truth state; the same envelope as AnalyticNumber.| Field | Type | Required | Description |
|---|---|---|---|
state | computed | known_zero | not_computed | not_applicable | stale | unavailable | insufficient_data | Yes | |
source | provider | insert_time | cache | computed | Yes | |
value | integer | No | |
freshness_at | string | No |
AnalyticNumber
A computed number with its truth state. value is present when state is computed or known_zero and may be present when stale; any other state says why there is no number, never a stand-in zero.| Field | Type | Required | Description |
|---|---|---|---|
state | computed | known_zero | not_computed | not_applicable | stale | unavailable | insufficient_data | Yes | computed: a measured value. known_zero: a measured zero. stale: a value past its freshness window. not_computed: an input is unknown. not_applicable: the measure does not apply. unavailable: the source could not be read. insufficient_data: too few observations. |
source | provider | insert_time | cache | computed | Yes | Where the value came from, for diagnostics: cache is a stored aggregate, computed a request-time aggregate. Decide on state, not source. |
value | number | No | |
freshness_at | string | No | When the stored inputs behind the value were written or last confirmed (cache), or the request time (computed). |
ApiDiscovery
| Field | Type | Required | Description |
|---|---|---|---|
api_base_url | string | Yes | Canonical API origin for public V1 requests. |
docs_url | string | Yes | Full agent-readable API reference. |
openapi_url | string | Yes | Canonical web-origin OpenAPI JSON document. |
health_url | string | Yes | Unauthenticated API health endpoint. |
authentication | string | Yes | |
protected_resource_metadata_url | string | Yes | RFC 9728 protected-resource metadata for the API origin: the document every V1 401 names in its WWW-Authenticate challenge (resource, bearer_methods_supported, resource_documentation). The remote MCP server has its own document at /.well-known/oauth-protected-resource/api/v1/mcp. |
authenticated_routes | array of string | Yes | The complete authenticated route index: one entry per authenticated route this spec documents, in “<METHOD> <path>” form, not a representative subset. GET /api/v1 is the unauthenticated entrypoint an agent hits first, so it hands back the whole authenticated surface rather than a sample the caller would have to guess around. The example on GET /api/v1 is abridged for readability — the live response returns all of them. Kept in lockstep with this spec by review: it is a hand-maintained const in backend/src/api_v1/discovery.rs and no automated check compares the two, so treat this spec as authoritative if they ever disagree. |
ApiError
| Field | Type | Required | Description |
|---|---|---|---|
object | string | Yes | |
error | object (code, message, doc_url, param, retry_at, freshness, billing_url, reason) | Yes | |
meta | ResponseMeta | Yes |
ApiErrorBody
| Field | Type | Required | Description |
|---|---|---|---|
code | bad_request | invalid_api_key | subscription_required | forbidden | insufficient_scope | not_found | account_locked | rate_limited | rate_limit_unavailable | internal_error | request_timeout | endpoint_retired | Yes | FROZEN: an existing value never changes meaning. request_timeout (408, #16146) was added the way insufficient_scope was: the handler did not answer inside the server’s 30-second timeout. Retry-After and retry_at ride on it only for a safe method (GET, HEAD); a timed-out mutation may have completed, so check its state and reuse its Idempotency-Key. |
message | string | Yes | |
doc_url | string | No | |
param | string | No | |
retry_at | string | No | The recommended next retry instant (RFC3339). Present on every retryable error (reason=pick_not_released, code=rate_limited including reason=monthly_quota_exceeded, code=rate_limit_unavailable, reason=read_model_warming, reason=kickoff_roster_pending, whose retry_at is 30 s after kickoff) and omitted otherwise. Always in the future. For pick_not_released, the recommendation is advisory and can change before a pick becomes available. Schedule the next request from the returned value instead of inferring a release schedule or polling. Prefer Retry-After for the duration because it is immune to client clock skew. |
freshness | FreshnessFailure | No | |
billing_url | string | No | Where a person clears this 402 (#32592): pays the overdue invoice (reason payment_overdue) or reactivates the plan (reason subscription_inactive). Present on every 402 subscription_required, omitted on every other error. The message names the same URL; link this field instead of parsing the message. |
reason | cursor_expired | unknown_endpoint | pick_not_released | trader_not_tracked | market_out_of_scope | fill_history_too_large | kickoff_roster_pending | kickoff_roster_not_captured | read_model_warming | database_unavailable | request_accounting_unavailable | idempotency_in_progress | webhook_delivery_in_progress | webhook_secret_rotation_not_prepared | webhook_secret_rotation_overlap_active | sandbox_api_key | api_key_in_query | subscription_inactive | payment_overdue | monthly_quota_exceeded | invalid_query | unknown_query_parameter | invalid_path | invalid_body | unsupported_media_type | payload_too_large | method_not_allowed | ip_rate_limited | ip_throttled | cold_read_limited | export_expired | freshness_ceiling_unsatisfied | max_plan_required | endpoint_retired | No | ADDITIVE (#7209). The specific, actionable cause behind code, when there is one more specific than the code itself. code keeps its published values, so existing clients are unaffected; new clients branch on reason. Omitted when the code already says everything we know. pick_not_released: no Pick of the Day is published for the current product day; schedule one request against retry_at instead of polling. unknown_endpoint: the PATH is not a route on this API — read GET /api/v1, do not retry. trader_not_tracked: the wallet is real and the URL is right, but the trader is not on the warm sync tier (the wallets we sync most often) — stop asking for this wallet. market_out_of_scope (404 not_found, #27303): the market or event is real and the URL is right, but 0xinsider serves sports and esports markets only — stop asking for this market; neither a retry nor another URL for it can succeed. fill_history_too_large (404 not_found, #33245): the wallet and market are tracked, but the position timeline sums every earlier fill into its running totals and this wallet has more than 20,000 fills on the market before the requested page — stop asking for this pair; neither a retry nor another page can succeed. kickoff_roster_pending (404 not_found, #34064): as_of=kickoff on a game moneyline whose kickoff is still ahead or less than 30 s past, so its kickoff roster is not served yet; retry_at is 30 s after kickoff, and a read before it cannot succeed. kickoff_roster_not_captured (404 not_found, #34064): as_of=kickoff on a market with no stored kickoff roster (not a game moneyline, a game that kicked off before the capture shipped, a game whose live score showed play before its listed kickoff, or no complete holder population held before kickoff); terminal for that market, and the current roster is never served in its place. cursor_expired: pagination went stale mid-walk — re-request the first page and continue. read_model_warming: the requested endpoint cannot serve its read model yet; exact causes are endpoint-specific and can include a cold or contended refresh or a dependency that prevented refresh. database_unavailable: the API’s database or its connection pool is temporarily unreachable (a connection-class failure, not a query fault); code stays rate_limit_unavailable, nothing is rate-limited, retry after Retry-After / retry_at. idempotency_in_progress: retain the exact Idempotency-Key and request body, then retry shortly. webhook_delivery_in_progress: retry the URL or signing-secret configuration change after the destination’s active request completes. request_accounting_unavailable: accounting capacity is unavailable before the handler executes; retry after Retry-After / retry_at. sandbox_api_key: the credential is a sandbox key (oxi_sk_test_) from POST /api/v1/agents/register, which only the sandbox server accepts — call the sandbox base URL with it, or get a live key or OAuth access token; do not retry it here. api_key_in_query: the key was sent as a ?token= query parameter, which no route reads because URLs land in logs and history; the key itself was not checked — resend it as Authorization: Bearer. subscription_inactive: the key is valid but the account’s Pro subscription has lapsed (402 subscription_required); permanent until a person reactivates at https://0xinsider.com/billing, which the message names — stop retrying on a schedule and surface the link. The key owner is emailed once per lapse. payment_overdue (402 subscription_required, #32592): the key is valid and the account still has its plan, but its latest subscription invoice is unpaid (Stripe past_due or unpaid), so paid access is paused; permanent until a person pays at billing_url (https://0xinsider.com/billing) — stop retrying on a schedule and surface the link. The key works again the moment the invoice is paid. GET /api/v1/me and GET /api/v1/usage keep answering. monthly_quota_exceeded: the account has used the requests its plan includes for the UTC calendar month (429 rate_limited); retry_at and Retry-After name the first of next month, the only retry that can succeed, and the message names https://0xinsider.com/developers, where pay as you go for requests over the quota is turned on. The X-Monthly-Quota-Limit, X-Monthly-Quota-Remaining and X-Monthly-Quota-Reset headers on every authenticated response say how close the account is. invalid_query, invalid_path, invalid_body (400 bad_request, #16146): a query parameter, a path segment or the JSON body did not parse or does not fit the route’s schema, so no handler ran; param names the field when the parser named one (a query key, a path segment, a JSON path such as traders[0], or body); fix the request, never retry it as sent. unsupported_media_type (415 bad_request, param content-type): send the body with Content-Type: application/json. payload_too_large (413 bad_request, param body): the body is over 1048576 bytes. method_not_allowed (405 bad_request): the path is a route but not with this method; the Allow header names the methods it serves. ip_rate_limited (429 rate_limited, #16380): the per-address budget every caller behind one IP shares, counted before authentication, is spent; not the key’s own window, and the RateLimit-* headers describe that bucket. ip_throttled (429 rate_limited): the address is in a cooldown after sustained over-limit traffic; Retry-After is minutes to days, and a request before it does not shorten the cooldown. cold_read_limited (429 rate_limited, #28752, #34815): the account has used its share of cold reads on a route, requests whose answer is not cached, each of which reads Polymarket: GET /api/v1/market/{condition_id}/holders for a market whose roster is not cached (6 a minute, in bursts of up to 400), and GET /api/v1/market/{condition_id}/candles at 5m or 1h for a window not cached (6 a minute, in bursts of up to 30); not the per-minute window, so a cached answer still answers, and the next cold read is admitted at Retry-After. max_plan_required (403 forbidden, #23085): the key is valid and its account is on Pro, but the route is part of Max (GET /api/v1/edge-hunter); every Pro route keeps working with the same key, so do not disable it. The message names https://0xinsider.com/pricing, where the account upgrades; a retry never clears it. endpoint_retired (410): this legacy sports endpoint no longer serves data. Migrate to GET /api/v1/edge-hunter; retrying the retired path cannot succeed. |
BatchGameHoldersItem
| Field | Type | Required | Description |
|---|---|---|---|
index | integer | Yes | Zero-based request index. Duplicate inputs keep separate result rows. |
input | string | Yes | |
status | ok | error | Yes | |
data | GameHoldersItem | No | |
error | ApiErrorBody | No |
BatchMarketCloseItem
| Field | Type | Required | Description |
|---|---|---|---|
index | integer | Yes | Zero-based request index. Duplicate inputs keep separate result rows. |
input | string | Yes | |
status | ok | error | Yes | |
data | MarketClose | No | |
error | ApiErrorBody | No |
BatchMarketFlowItem
| Field | Type | Required | Description |
|---|---|---|---|
index | integer | Yes | Zero-based request index. Duplicate inputs keep separate result rows. |
input | string | Yes | |
status | ok | error | Yes | |
data | MarketFlow | No | |
error | ApiErrorBody | No |
BatchRateLimitMeta
| Field | Type | Required | Description |
|---|---|---|---|
basis | string | Yes | |
limit | integer | Yes | The batch item budget per minute for the caller’s plan: 2500 item units on Pro, 10000 on Max. The same number X-Batch-RateLimit-Limit reports. |
remaining | integer | Yes | |
reset | integer | Yes | Unix timestamp when the batch item window resets. |
BatchResponseMeta
| Field | Type | Required | Description |
|---|---|---|---|
request_id | string | Yes | Unique request ID (req_ prefix). The same value as the X-Request-Id response header, the request’s usage accounting row and its log lines. |
cached | boolean | Yes | |
total_items | integer | Yes | |
successful_items | integer | Yes | |
failed_items | integer | Yes | |
request_cost | integer | Yes | Number of batch item units reserved before execution. |
rate_limit | BatchRateLimitMeta | Yes |
BatchTraderItem
| Field | Type | Required | Description |
|---|---|---|---|
index | integer | Yes | Zero-based request index. Duplicate inputs keep separate result rows. |
input | string | Yes | |
status | ok | error | Yes | |
data | Trader | No | |
error | ApiErrorBody | No |
Candle
One bucketed OHLC price candle. Prices are in provider [0, 1] units: truncated to 4 decimals at 1d and 1w, unrounded at 5m and 1h. At 5m and 1h, basis says which Polymarket series the candle comes from: provider_bucket is Polymarket’s own bucket price, so open, high, low and close are equal; provisional_minutes is built from Polymarket’s 60-second prices in a bucket it has not published yet.| Field | Type | Required | Description |
|---|---|---|---|
t | integer | Yes | Bucket-start unix epoch (seconds): the five-minute or hour boundary for 5m and 1h, UTC midnight for 1d, the ISO-week Monday’s UTC midnight for 1w. |
o | number | Yes | Open price in provider [0, 1] units (first observed point in the bucket). |
h | number | Yes | High price in provider [0, 1] units (max observed in the bucket). |
l | number | Yes | Low price in provider [0, 1] units (min observed in the bucket). |
c | number | Yes | Close price in provider [0, 1] units (last observed point in the bucket). |
basis | provider_bucket | provisional_minutes | No | 5m and 1h only; absent at 1d and 1w. provider_bucket: Polymarket’s own five-minute or hourly bucket, one price, so o=h=l=c. provisional_minutes: a bucket after Polymarket’s newest published one, in a window that ended under 3 hours ago, built from Polymarket’s 60-second prices inside it: o the first minute’s price, h the highest, l the lowest, c the last. Provisional: a later read replaces it with Polymarket’s bucket once published (its price has equalled the first minute’s price, so o carries over and h, l and c collapse to it), and the bucket in progress gains minutes until it closes. A bucket with no 60-second price has no candle. |
CategoryLeader
| Field | Type | Required | Description |
|---|---|---|---|
address | string | Yes | |
as_of | string | Yes | |
category | string | Yes | |
edge_lower_bound | number | null | Yes | |
grade | object | Yes | |
id | string | Yes | |
independent_events | integer | Yes | |
n_resolved | integer | null | Yes | |
platform | polymarket | Yes | |
pnl | number | null | Yes | |
rank | integer | Yes | |
unresolved_events | integer | Yes | |
username | string | null | Yes | |
win_rate | number | null | Yes | |
category_numbers | CategoryNumbers | Yes | Whether n_resolved, win_rate and pnl take the wallet’s latest settlements (#36089). |
CategoryNumbers
Whether a wallet’s category figures take its latest settlements (#36089). The figures are updated from a queue as the wallet’s markets settle. state is behind when an update for this wallet has waited over an hour, because the whole queue is behind or because the wallet’s own updates wait until its settled record is complete; the figures then stay served, and as_of says when the oldest waiting update was queued. Read from a check the server runs about every three minutes, never on the request.| Field | Type | Required | Description |
|---|---|---|---|
as_of | string | null | Yes | When the oldest waiting update for this wallet was queued, UTC: the figures take nothing newer than about this instant. null unless state is behind. |
state | current | behind | unknown | Yes | current: no update of this wallet’s category figures has waited over an hour. behind: one has, since as_of. unknown: the check has no result from the last 375 seconds, so the figures are neither confirmed current nor known to be behind; treat them as unverified, not as current. |
CategorySkillModelReadiness
Model-wide readiness, read in the same database snapshot as category_records. Individual category rows retain their own status.| Field | Type | Required | Description |
|---|---|---|---|
status | live | insufficient | stale | unknown | degraded | Yes | |
model_version | string | Yes | |
taxonomy_version | string | Yes | |
observation_started_at | string | Yes | |
as_of | string | Yes | |
source_last_success_at | string | null | Yes |
CategorySkillV2
Forward-only category evidence from observed Polymarket taker fills. Status is category eligibility, not a global letter grade or a guarantee of positive edge. Scores are probability differences. Unknown and degraded rows withhold scores. Coverage is partial; observation counts are not lifetime market counts.| Field | Type | Required | Description |
|---|---|---|---|
status | live | insufficient | stale | unknown | degraded | Yes | |
model_version | string | Yes | |
taxonomy_version | string | null | Yes | |
platform | polymarket | Yes | |
scope | observed_goldsky_primary_taker_fill | Yes | |
source_coverage | partial_whale_threshold_fills | graded_wallet_fills | Yes | |
canonical_category | string | Yes | |
as_of | string | Yes | |
source_last_success_at | string | null | Yes | |
observation_started_at | string | Yes | |
latest_observation_at | string | null | Yes | |
independent_event_count | integer | Yes | |
resolved_condition_count | integer | Yes | |
unresolved_observation_count | integer | Yes | |
edge_mean | number | null | Yes | |
edge_sd | number | null | Yes | |
edge_se | number | null | Yes | |
edge_lower_95 | number | null | Yes | |
brier_event_avg | number | null | Yes |
Clv
| Field | Type | Required | Description |
|---|---|---|---|
condition_id | string | Yes | Polymarket condition id. |
status | measured | in_play | pending | unavailable | Yes | measured: clv carries the figures. in_play: placed_at is at or after kickoff, so the pre-game close does not grade it. pending: no close is stored yet. unavailable: no close will grade it; see unavailable_reason. |
unavailable_reason | object | Yes | Set exactly when status is unavailable: the close’s own unavailable_reason (GET /api/v1/market/{condition_id}/close), or anchor_stale when kickoff moved more than six hours after the close was captured. |
outcome | ClvOutcome | Yes | |
outcomes | array of ClvOutcome | Yes | Both outcomes of the market, the first (YES) then the second (NO). |
side | buy | sell | Yes | Which way the entry traded the outcome. A sell is measured as the buy of the other outcome. |
entry | object (price, from_odds, format, decimal_odds, placed_at) | Yes | The price the caller got. |
close | object (status, unavailable_reason, price, game_start_time, close_anchor_at, anchor_stale, observed_at, source) | Yes | The stored close of the outcome, as GET /api/v1/market/{condition_id}/close serves it. |
clv | object (cents, points, price_pct, ev_at_close_pct) | Yes | The CLV figures, set exactly when status is measured; every field null otherwise. Gross of fees. |
basis_version | string | Yes | The CLV definition, clv@v1, the large trades’ own. |
ClvOutcome
One outcome of the market.| Field | Type | Required | Description |
|---|---|---|---|
index | integer | Yes | Provider outcome index: 0 is the YES leg, 1 the NO leg. |
label | string | null | Yes | The outcome’s label. |
Combo
| Field | Type | Required | Description |
|---|---|---|---|
condition_id | string | Yes | Combo identifier: 0x followed by 62 lowercase hex characters. This differs from a binary market condition ID. |
leg_count | integer | null | Yes | |
prepared_at | string | null | Yes | |
legs_known | boolean | Yes | Whether the preparation event has been indexed. |
legs | array of ComboLeg | Yes | |
window | object | Yes | |
totals | object | Yes | |
status | pending | won | lost | unknown | Yes | Result of the YES conjunction, independent of the wallet side or its P&L. |
status_reason | string | null | Yes | Reason the conjunction result cannot be verified, when unknown. |
ComboCoverage
| Field | Type | Required | Description |
|---|---|---|---|
state | paused | uninitialized | stale | backfilling | live | Yes | |
ingest_enabled | boolean | Yes | |
cursors | array of ComboCoverageCursor | Yes | |
max_lag_blocks | integer | null | Yes | |
oldest_cursor_update | string | null | Yes | |
lifecycle_lag_blocks | integer | null | Yes | |
lifecycle_backfilling | boolean | Yes | |
computed_at | string | Yes | Time the coverage state was evaluated; not a market-price timestamp. |
ComboCoverageCursor
| Field | Type | Required | Description |
|---|---|---|---|
contract | string | Yes | Indexed contract. |
last_block | integer | Yes | |
seed_block | integer | Yes | |
seed_origin | string | Yes | |
chain_finalized_block | integer | null | Yes | |
lag_blocks | integer | null | Yes | |
updated_at | string | Yes |
ComboDetail
One combo with its newest 100 fills and all-time lifecycle totals. Paid API callers receive full access.| Field | Type | Required | Description |
|---|---|---|---|
access | full | Yes | |
combo | Combo | Yes | |
fills | array of ComboFill | Yes | |
lifecycle | object | Yes | |
coverage | ComboCoverage | Yes |
ComboFill
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Stable fill identity. |
block_number | integer | Yes | |
log_index | integer | Yes | |
block_timestamp | string | Yes | |
tx_hash | string | Yes | |
trader | string | null | Yes | Taker wallet address. |
trader_name | string | null | Yes | |
trader_grade | S | A | B | C | D | F | null | Yes | |
last_traded_at | string | null | Yes | Recorded wallet-wide trade time. |
action | buy | sell | Yes | |
condition_id | string | Yes | Combo identifier: 0x followed by 62 lowercase hex characters. This differs from a binary market condition ID. |
outcome_index | integer | Yes | 0 is YES, 1 is NO. |
shares | string | Yes | Exact decimal string from the stored chain or SQL value; preserve precision until display. |
collateral_usdc | string | Yes | Exact decimal string from the stored chain or SQL value; preserve precision until display. |
price | string | null | Yes | Execution price for the traded outcome; null for a zero-share event. |
price_yes | string | null | Yes | Execution price normalized to YES. |
fee_usdc | string | Yes | Exact decimal string from the stored chain or SQL value; preserve precision until display. |
leg_count | integer | null | Yes | |
status | pending | won | lost | unknown | Yes | Result of the YES conjunction, independent of the wallet side or its P&L. |
status_reason | string | null | Yes | |
won_legs | integer | Yes | |
payout_multiplier | string | null | Yes | Shares per dollar at execution; not a forecast or guaranteed return. |
legs | array of ComboLeg | Yes |
ComboFillsResponse
| Field | Type | Required | Description |
|---|---|---|---|
object | string | Yes | |
data | array of ComboFill | Yes | |
sort | recent | largest | payout | Yes | |
window | 24h | 7d | all | Yes | |
limit | integer | Yes | |
coverage | ComboCoverage | Yes | |
has_more | boolean | Yes | A continuation is available based on page fullness. Its next page may be empty. |
next_cursor | string | No | Exclusive block_number:log_index continuation for recent ordering. |
next_offset | integer | No | Continuation offset for largest or payout ordering. |
meta | ResponseMeta | Yes |
ComboLeg
| Field | Type | Required | Description |
|---|---|---|---|
leg_index | integer | Yes | |
outcome_index | integer | Yes | |
module_id | integer | Yes | |
state | pending | won | lost | void | unknown | Yes | |
market | object | Yes |
ComboLegMarket
| Field | Type | Required | Description |
|---|---|---|---|
source | markets | provider | Yes | Source of the leg facts. |
condition_id | string | Yes | Full binary CTF condition ID for this leg. |
title | string | null | Yes | |
slug | string | null | Yes | |
event_slug | string | null | Yes | |
polymarket_url | string | No | The leg’s event on Polymarket, carrying the 0xinsider tags: https://polymarket.com/event/<event_slug>?via=0xinsider&r=0xinsidercom. Present whenever event_slug is. |
outcome_label | string | null | Yes | |
image | string | null | Yes | |
category | string | null | Yes | |
winning_outcome | integer | null | Yes | Provider outcome index; negative sentinels describe void or unresolved states. |
resolved_at | string | null | Yes | |
market_closed | boolean | null | Yes | A closed market may still have no terminal outcome. |
pick_price_daily | number | null | Yes | Stored daily price for this leg outcome token; not a live quote. |
pick_price_as_of | string | null | Yes | Observation time of the stored daily price. |
pick_price_age_days | integer | null | Yes | Whole days since the stored daily bucket. |
provider_leg_status | string | null | Yes | Unmodified provider leg status when available. |
game_start_time | string | null | Yes | Kickoff stored on the local market, in UTC. Null when the leg has no local market or the market has no kickoff. |
kickoff_date_passed | boolean | Yes | True only when that kickoff’s calendar date is before today in UTC. False on the kickoff’s own date and false when there is no kickoff. True does not mean the game is over: a game that kicks off late in the UTC day is still in play after midnight UTC. Read game_ended for that. |
game_ended | boolean | null | Yes | Whether the game this market belongs to has ended, from the same stored game state GET /api/v1/games/{event_slug} reads. A market in a child event, such as a soccer game’s more-markets event, reads its parent game. False while the game is scheduled, in play or postponed. Null when no state is stored for the game, when the leg has no local market, or when the market has no event. Some games have no live feed, so null means unknown, not in play. A pending leg with game_ended or market_closed true is waiting on its result. |
ComboLifecycleStats
| Field | Type | Required | Description |
|---|---|---|---|
splits | integer | Yes | |
merges | integer | Yes | |
redeems | integer | Yes | |
compresses | integer | Yes | |
split_usdc | string | Yes | Exact decimal string from the stored chain or SQL value; preserve precision until display. |
merge_usdc | string | Yes | Exact decimal string from the stored chain or SQL value; preserve precision until display. |
redeemed_shares | string | Yes | Exact decimal string from the stored chain or SQL value; preserve precision until display. |
redeemed_usdc | string | Yes | Exact decimal string from the stored chain or SQL value; preserve precision until display. |
compressed_usdc | string | Yes | Exact decimal string from the stored chain or SQL value; preserve precision until display. |
last_event_at | string | Yes |
ComboLiveCount
| Field | Type | Required | Description |
|---|---|---|---|
count | integer | Yes | Traded combos whose YES conjunction remains pending. |
computed_at | string | Yes | Time the count was computed; check its age before using it. |
ComboResponse
| Field | Type | Required | Description |
|---|---|---|---|
object | string | Yes | |
data | ComboDetail | Yes | |
meta | ResponseMeta | Yes |
ComboTotals
| Field | Type | Required | Description |
|---|---|---|---|
fills | integer | Yes | |
volume_usdc | string | Yes | Exact decimal string from the stored chain or SQL value; preserve precision until display. |
largest_fill_usdc | string | Yes | Exact decimal string from the stored chain or SQL value; preserve precision until display. |
first_fill_at | string | Yes | |
last_fill_at | string | Yes | |
last_fill_price_yes | string | null | Yes | Last taker execution normalized to YES; not a current quote. |
last_fill_outcome_index | integer | Yes | |
last_fill_action | buy | sell | Yes |
ComboWindowStats
| Field | Type | Required | Description |
|---|---|---|---|
fills | integer | Yes | |
volume_usdc | string | Yes | Exact decimal string from the stored chain or SQL value; preserve precision until display. |
distinct_traders | integer | Yes | |
largest_fill_usdc | string | Yes | Exact decimal string from the stored chain or SQL value; preserve precision until display. |
CombosSummary
Stored live combo count. Null means the first count is unavailable, never zero.| Field | Type | Required | Description |
|---|---|---|---|
live | object | Yes |
CombosSummaryResponse
| Field | Type | Required | Description |
|---|---|---|---|
object | string | Yes | |
data | CombosSummary | Yes | |
meta | ResponseMeta | Yes |
ContentSearchResult
| Field | Type | Required | Description |
|---|---|---|---|
content_id | string | Yes | Backend-owned stable editorial content identifier. |
kind | learn | glossary | comparison | research | strategy | Yes | Editorial content kind. |
slug | string | Yes | Backend-owned content slug. |
title | string | Yes | Editorial title. |
excerpt | string | Yes | Search-result excerpt. |
url | string | Yes | Canonical first-party content URL. |
CounterpartyAnalysis
| Field | Type | Required | Description |
|---|---|---|---|
status | available | partial | unavailable | Yes | |
unavailable_reason | string | No | |
snapshot_id | string | No | Deterministic immutable membership snapshot for this detail response. |
analysis_id | string | No | Stable digest binding page cursors to one snapshot and execution set. |
execution_count | integer | Yes | |
available_execution_count | integer | Yes | |
unavailable_execution_count | integer | Yes | |
executions | array of CounterpartyExecution | Yes | |
executions_next_cursor | string | No | Stable cursor after the last execution included in the bounded inline page. |
CounterpartyExecution
| Field | Type | Required | Description |
|---|---|---|---|
execution_id | string | Yes | |
exchange_family | ctf_v2 | neg_risk_ctf_v2 | exchange_v3 | Yes | Polymarket exchange contract that emitted the execution: ctf_v2 the CTF Exchange v2, neg_risk_ctf_v2 the Neg Risk CTF Exchange v2, exchange_v3 ExchangeV3, which settles Polymarket Protocol V2 binary and neg-risk markets. Treat an unknown value as another exchange. |
transaction_hash | string | Yes | |
orders_matched_log_index | integer | Yes | |
taker | CounterpartyParticipant | Yes | |
makers | array of CounterpartyParticipant | Yes | |
makers_next_cursor | string | No | Stable cursor after the last maker included in the bounded inline page. |
CounterpartyMakerPage
| Field | Type | Required | Description |
|---|---|---|---|
analysis_id | string | Yes | |
snapshot_id | string | Yes | |
execution_id | string | Yes | |
items | array of CounterpartyParticipant | Yes | |
next_cursor | string | No | Cursor bound to the analysis, execution, last full-denominator share total, and wallet. |
CounterpartyMatchBreakdown
| Field | Type | Required | Description |
|---|---|---|---|
match_type | COMPLEMENTARY | MINT | MERGE | Yes | |
maker_fill_count | integer | Yes | |
filled_shares | string | Yes | Exact decimal shares. |
CounterpartyParticipant
| Field | Type | Required | Description |
|---|---|---|---|
counterparty_key | string | Yes | |
execution_wallet | string | Yes | Lowercase Polygon wallet from the exact OrderFilled log. |
identity_status | resolved | infrastructure | unavailable | Yes | |
resolved_user_id | string | No | |
wallet_family | string | No | |
resolution_block | integer | No | |
resolution_source | string | No | |
display_name | string | No | |
grade | string | No | |
last_traded_at | string | No | Latest nonfuture recorded wallet-wide trade time for the tracked trader supplying this participant’s grade. Omitted when unavailable; not the receipt time or the owner EOA’s activity. Trader context is read with the response and is not frozen by execution membership snapshots. |
profile_segment | string | No | 0xinsider profile path segment for this participant, present only when the execution wallet has a tracked trader: @<username> when that username resolves to the trader alone, otherwise the trader’s lowercase wallet. Percent-encode the part after @ and append to https://0xinsider.com/profile/. |
maker_fill_count | integer | Yes | |
filled_shares | string | Yes | Exact decimal shares. |
filled_usdc | string | Yes | Exact decimal USDC amount. |
share_pct | string | Yes | Participant share of the exact execution, from 0 through 100. |
match_breakdown | array of CounterpartyMatchBreakdown | Yes |
CreateWebhookRequest
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | |
url | string | Yes | Public HTTPS callback URL on the default port 443. Local, private, and internal targets are rejected, as is any explicit port other than 443 and any URL carrying credentials. Each user’s URLs are unique after normalizing HTTPS scheme/host case, trailing DNS dots and port 443; path/query case is preserved. Pending verification and PATCH-disabled endpoints still reserve their stored URL. The destination must answer the signed webhook.verification challenge with a 2xx before POST /api/v1/webhooks/{id}/verify can activate the endpoint. |
event_types | array of WebhookEventType | Yes | |
trade_filters | LargeTradeSubscriptionFilters | No | |
price_move_filters | PriceMoveSubscriptionFilters | No | |
settlement_filters | SettlementSubscriptionFilters | No |
CreateWebhookVerificationAttemptRequest
| Field | Type | Required | Description |
|---|---|---|---|
verification_token | string | Yes | The original one-time token returned by webhook creation or a URL change. Sent only in the request body and signed receiver challenge. |
DataQuality
Compact data age and coverage for a response body, always present on the operations that publish it. Read status and as_of to decide whether to use the body at all, and field_groups to see which part is weak. Everything here comes from stored observation clocks, and each clocked group is judged against its writer’s budget when the body is served, so a cached body reports the same ages and verdicts a freshly computed one does: meta.cached and meta.cache_age_s stay the only transport-time facts and neither makes this block newer. The per-field audit object is still available through expand=trust; this is the default summary of the same question.| Field | Type | Required | Description |
|---|---|---|---|
status | fresh | stale | partial | unknown | untracked | unavailable | Yes | fresh when every group is fresh, unavailable when every group is unavailable, stale when every group is fresh or stale and at least one is stale, and partial in every other case. |
as_of | string | No | The oldest as_of among the groups that carry one: the age of the weakest clock this body rests on. Omitted when no group carries a clock. |
field_groups | array of DataQualityGroup | Yes | One entry per field group. Entries may be added in later releases, so match on group rather than on position or length. |
DataQualityGroup
One group of response fields that share a writer and therefore share a clock.| Field | Type | Required | Description |
|---|---|---|---|
group | string | Yes | Stable snake_case group name. Names are additive across releases, so match on the ones you know and ignore the rest. |
owner | string | Yes | The table and column that write this group, named so the verdict can be audited (for example trader_rankings.computed_at). |
status | fresh | stale | partial | unknown | untracked | unavailable | Yes | fresh: served, as_of carries this group’s real observation or computation clock, and that clock is no older than max_age_s when the group carries one. stale: served and clocked, but as_of is older than max_age_s, so the writer has missed a refresh its schedule promises; or, on a group without max_age_s, the source changed after as_of and the group’s values leave that change out, which reason names (since 2026-11-15, #35587). partial: some of the group’s fields are served and some are missing. unknown: served, and this read has no clock for it, so no age may be inferred. untracked: 0xinsider does not track this group for this subject, by design. unavailable: the group could not be served. New values may be added; treat one you do not recognize as unknown. Neither fresh nor stale is a tolerance for your use: compare as_of against your own. |
as_of | string | No | When this group’s values were observed or computed. Omitted whenever the read cannot measure it, and never filled with the serialization time, the cache time, or another group’s clock. |
reason | string | No | Why the status is not fresh. Omitted when it is. |
max_age_s | integer | No | The longest gap in seconds this group’s writer leaves between refreshes on its schedule: the age past which the group reads stale instead of fresh. Omitted when the writer keeps no schedule its clock could fall behind (a clock stamped once, only on a change, or when a reader asks), and no age makes such a group stale; it is stale only when the read sees a change at the source after as_of, which reason names (since 2026-11-15, #35587). It is the writer’s promise, not a tolerance for your use. |
EdgeHunterBoard
The full Max-only Edge Hunter board. Defaults cover all sports and esports with B grade floor, 48-hour horizon and at most 30 rows; common selections, legacy category, min_grade and limit narrow that projection. No pagination or ETag. Rows add frozen market_context discovery metadata.| Field | Type | Required | Description |
|---|---|---|---|
as_of | string | Yes | When the ranked snapshot was computed. Date current quotes with their own ts values. |
horizon_hours | integer | Yes | |
min_grade | S | A | B | Yes | Requested holder-presence grade floor, S/A/B. A holder at that grade or better admits the row; other holders remain visible. |
ranking_source | live | db_only | Yes | live uses the current graded holder pile; db_only is a weaker stored-data fallback. |
directional_source | live | degraded | Yes | degraded means directional enrichment was unavailable. |
cached_age_seconds | integer | null | Yes | |
viewer | string | Yes | |
free_rank | integer | null | Yes | Always null: Edge Hunter has no free signal slot. |
total | integer | Yes | Ranked rows after normalized selections and grade filtering, before the view-specific limit cap. |
rows | array of EdgeHunterRow | Yes | |
unranked | object | Yes | Markets the window and selection evaluated without a row, by reason. Every one drew a large trade from an S, A or B wallet in the last 24 hours, as every row did, so total plus the three counts is every market evaluated, and total 0 with all three 0 means no market in the window drew such a trade. Null on a snapshot cached before the counts existed. |
EdgeHunterBoardResponse
| Field | Type | Required | Description |
|---|---|---|---|
object | string | Yes | |
data | EdgeHunterBoard | Yes | |
meta | ResponseMeta | Yes | |
selection | EdgeHunterSelection | No | Normalized axes requested with a selector or category; omitted on an unselected default read. |
EdgeHunterCategorySkill
Category evidence over the full uncapped piled-side S/A/B holder allocation. It never changes signal membership, ordering, routing, or sizing.| Field | Type | Required | Description |
|---|---|---|---|
status | live | insufficient | stale | unknown | degraded | Yes | |
model_version | string | Yes | |
taxonomy_version | string | null | Yes | |
platform | string | Yes | |
scope | string | Yes | |
source_coverage | partial_whale_threshold_fills | graded_wallet_fills | Yes | |
observation_started_at | string | Yes | |
as_of | string | Yes | |
canonical_category | string | null | Yes | |
eligible_holders | integer | Yes | |
covered_holders | integer | Yes | |
backed_sharp_usd | number | null | Yes | |
covered_backed_usd | number | null | Yes | |
coverage_pct | number | null | Yes | |
weighted_edge_mean | number | null | Yes | |
weighted_holder_lower_mean | number | null | Yes | |
specialist_backed_usd | number | null | Yes | |
specialist_backed_usd_pct | number | null | Yes | |
largest_holder_backed_usd_pct | number | null | Yes | |
minimum_holder_event_count | integer | null | Yes |
EdgeHunterFunnelReport
Per-sport accountable funnel for the full observation snapshot, returned on every page.| Field | Type | Required | Description |
|---|---|---|---|
sports | array of EdgeHunterSportFunnelReport | Yes |
EdgeHunterMarketContext
Metadata frozen with the read generation. Values are nullable when the provider/canonical source has no value; no title-based inference or current-clock fallback.| Field | Type | Required | Description |
|---|---|---|---|
league | string | null | Yes | Normalized machine/provider league identity. Known wire/tag aliases normalize; other provider identities match exact lowercase keys. |
series_slug | string | null | Yes | Exact provider series slug, usable in series_slugs selection. |
market_type | string | null | Yes | Exact provider sports_market_type, usable in market_types selection. |
metadata_updated_at | string | null | Yes | Exact local canonical metadata writer market_canonical.updated_at. This is not a provider observation clock; null means unavailable. |
EdgeHunterMostHeld48hCutoff
One sport’s most_held_48h cutoff: the last market the selection admitted and the values it was ranked by.| Field | Type | Required | Description |
|---|---|---|---|
sport | string | Yes | Canonical sport bucket, as on a row’s category. |
position | integer | Yes | The market’s place in the sport’s most_held_48h admission order, which is the number of markets most_held_48h admitted in the sport: 8 when the sport has 8 to admit. |
condition_id | string | Yes | The market. It may have no card in an admission=most_held_48h response when its holder read ended without one (a split pile, no read). |
indexed_graded_holders | integer | Yes | The first ranking value: S, A and B graded wallets in the 0xinsider index holding either outcome, as on a row’s indexed_graded_holders. |
volume | number | null | Yes | The second ranking value, as on a row’s volume. null only for a market without a stored volume, which the ranking never holds: such a market counts as invalid_market. |
game_start_time | string | Yes | The third ranking value: of two markets with equal holders and volume, the earlier kickoff ranks first, then the lower condition_id. |
indexed_graded_holders_min_25_usd | integer | No | admission=most_held_48h_min_25_usd only: the first ranking value of that selection, the market’s indexed_graded_holders_min_25_usd; volume and game_start_time follow it. Omitted on the other admissions, which rank by indexed_graded_holders. |
EdgeHunterObservation
One explicitly observation-only holder-pile measurement. It is evidence for cohort evaluation, not an execution instruction, and is isolated from the funded Edge Hunter signals view.| Field | Type | Required | Description |
|---|---|---|---|
side | string | null | Yes | The side profitable wallets hold, as a provider-backed display label. Canonical spelling of piled_side (#16310), same value: when provider group context is unavailable it may remain a bare Yes/No/Over/Under, so do not use it alone as participant identity. |
backing_score | number | Yes | Recorded side backing score; higher values indicate stronger backing. |
side_share | number | Yes | Signed share of graded money on the side, in [-1, 1]. Canonical spelling of smart_score (#16309, #16310), same value. |
condition_id | string | Yes | Raw Polymarket condition id. |
token_id | string | Yes | Provider-backed Polymarket CLOB token id for the piled outcome. Rows without a verified token terminate before emission. |
category | Basketball | Football | Baseball | Hockey | MMA | Boxing | Soccer | Cricket | Golf | Tennis | Esports | Racing | Table Tennis | Pickleball | Yes | Canonical sport bucket. |
raw_category | string | null | Yes | Raw provider category as stored. |
title | string | Yes | Provider-backed market title. |
event_slug | string | null | Yes | |
event_id | string | null | Yes | Provider event id when available. |
parent_event_id | string | null | Yes | Provider parent-event id used as the first event-cap identity when available. |
game_start_time | string | Yes | Provider-backed kickoff time in UTC. |
observed_at | string | Yes | UTC instant when this row finished provider/holder evaluation. |
cohort | wider_holder | in_play | emerging_pile | Yes | Source cohort or additive projection view. emerging_pile is projected from wider_holder after source computation, overlaps its funnel denominator, and uses the source row’s directional evidence. |
admitted_by | most_held | soonest_kickoff | most_held_48h | most_held_48h_by_type | most_held_48h_min_25_usd | Yes | Which evaluation place in its sport the row took this refresh. most_held: a wider_holder place for up to 8 markets per sport kicking off within 24 hours, most graded holders first, kept until kickoff while the holder page still shows a card or could not be read; also every in_play row, whose places go most graded holders first. soonest_kickoff: a wider_holder place among the sport’s 8 soonest kickoffs, which is not kept. emerging_pile rows carry their source wider_holder row’s value. Filter on most_held to keep the most-held selection. most_held_48h: every row of an admission=most_held_48h response, which is that opt-in selection (up to 8 markets per sport within 48 hours, most graded holders first, recomputed every refresh), including a market a default place also evaluates; it never appears on a default response. most_held_48h_min_25_usd: every row of an admission=most_held_48h_min_25_usd response, the same selection counting only graded holders with $25 or more in the market. |
observation_only | boolean | Yes | Always true. This row must not be routed to an order executor. |
piled_side | string | null | Yes | Nullable provider-backed piled-outcome display label. When provider group context is unavailable, it may remain a bare Yes/No/Over/Under; do not use it alone as participant identity. Deprecated (#16310): side is the canonical spelling and carries the same value; this key stays on the wire. |
piled_outcome_index | 0 | 1 | Yes | Provider binary-column selector: 0 selects outcome_yes/token_id_yes; 1 selects outcome_no/token_id_no. It does not identify home/away or a participant. Use piled_side together with title/event context for display. |
backed_price | number | Yes | Aggregate piled-side market midpoint recorded at observed_at. This is an observation price mark, not a wallet entry cost. |
sharp_pct | number | Yes | Piled-side graded-holder dollar concentration. |
backed_sharp_usd | number | Yes | Raw graded-holder USD on the piled outcome. |
s_count | integer | Yes | |
a_count | integer | Yes | |
b_count | integer | Yes | |
graded_holders | integer | Yes | Piled-side S/A/B holder count. |
top_grade | S | A | B | Yes | |
smart_score | number | Yes | Canonical signed holder-pile score. Deprecated (#16310): side_share is the canonical spelling and carries the same value; this key stays on the wire. |
volume | number | Yes | Cumulative provider taker volume in shares, not cash or dollars. |
conviction_score | number | Yes | Recorded conviction score; higher values indicate stronger conviction. |
provider_read_source | cached | live | Yes | Whether the provider holder page came from the shared cache or a live provider read. |
holder_scan_complete | boolean | Yes | True only when the provider page read for each outcome token listed every holder of that token. Observation collection reads one 100-row page per token; a token with more holders stays incomplete. False means holder counts and dollar totals measure the observed positive-holder subset. sharp_pct describes that observed subset and is not a lower bound on the full-population percentage. Incomplete scans cannot satisfy a future capital-promotion gate. |
holder_snapshot_at | string | null | Yes | Proven provider holder observation time. A warm cache hit uses only the original provider completion time from its companion metadata, never cache-read time. A wider_holder or emerging_pile row whose holder read did not finish or failed in the current pass may reuse that market’s last pregame holder page for up to 15 minutes; an in_play row may reuse its last in-play page, read after the provider reported the game live and never before that market’s own kickoff, for up to 10 minutes. Both ages are counted when the snapshot is computed. Either reuse carries that page’s original time here and provider_read_source cached. A pregame market more than an hour before kickoff reuses its last page the same way until that page is 10 minutes old, and only then is read again; while that market has had no trade since the page, it keeps reusing the page until it is 30 minutes old. Once that market’s own kickoff has passed, an in_play row with provider_read_source cached, a warm hit or a reuse, never carries a page read before it. Null, malformed, future, or stale holder time fails in-play closed. |
directional_status | available | unknown_ungrouped | unknown_stale | unavailable | Yes | Truthful state of the directional read, which classifies each graded holder by its fresh synced legs across the game’s markets and, when holder_scan_complete is true, by Polymarket’s currentValue on both outcomes of this market. A wider_holder row can remain emitted with unavailable and terminal wider_holder_emitted; in_play fails closed instead and terminates as in_play_directional_unavailable. |
one_way_holder_count | integer | null | Yes | |
hedged_holder_count | integer | null | Yes | |
one_way_graded_usd | number | null | Yes | |
directional_confidence | number | null | Yes | |
directional_rank_score | number | Yes | Recorded side ordering score; higher values sort first. |
rank | integer | Yes | 1-based rank within this observation cohort and snapshot: directional_rank_score descending, then conviction_score descending, then category and condition_id. Admission decides which markets a response holds, not their rank, so under admission=most_held_48h or most_held_48h_by_type rank does not follow indexed_graded_holders. |
market_context | EdgeHunterMarketContext or null | Yes | Required nullable frozen metadata context. Null only during the legacy-generation transition; selected reads require sidecar readiness and fail closed with 503 instead. |
indexed_graded_holders | integer | null | Yes | S, A and B graded wallets in the 0xinsider index holding either outcome of the market, as the stored market universe last counted them. Every most-held place ranks by this count: admission=most_held_48h and most_held_48h_by_type, the default selection’s most_held places and in_play slots. It can be larger or smaller than graded_holders, which counts the piled side of the provider’s holder page. Null only on a row of a generation computed before this field existed. |
most_held_48h_position | integer | null | No | admission=most_held_48h and most_held_48h_by_type only: the market’s 1-based place in its sport’s most_held_48h admission order, every market type ranked together, from the same refresh that admitted the row. The order is most indexed_graded_holders first, then most volume, then soonest game_start_time, then condition_id, skipping a market whose event (parent event first) already holds 4 markets of the order. Places 1 to 8 are the most_held_48h list; a place above 8 is the number of slots the sport would need for this market to take one, so compare it with most_held_48h_cutoffs[].position. null when the market has no place: its event already held 4 markets ranked above it, so no number of sport slots would admit it. A place stays taken by a market whose holder read ended without a card (a split pile, no read), so the cards of a most_held_48h response can skip places. On admission=most_held_48h_min_25_usd it is the place in that selection’s own order, most indexed_graded_holders_min_25_usd first. Omitted on a default read and on a snapshot computed before this field. |
indexed_graded_holders_min_25_usd | integer | No | admission=most_held_48h_min_25_usd only: of indexed_graded_holders, the S, A and B graded wallets whose position in the market is worth $25 or more, both outcomes together, at the value the 0xinsider index last read for the wallet. That selection ranks each sport by this count, then by most volume, then by soonest game_start_time, then by condition_id, at most 4 markets per event. It is never larger than indexed_graded_holders. Omitted on every other response. |
protocol_version | v1 | v2 | Yes | The Polymarket protocol the market trades on, Gamma’s market version: v1 (CTF, ConditionalTokens) or v2 (Protocol V2). Read from the condition id, the same value GET /api/v1/markets/settled serves. On a v2 market every token_id this object names is a V2 position id: sign its orders for ExchangeV3 and read its balance as CONDITIONAL-V2. |
EdgeHunterObservationCoverage
Measured coverage of the frozen canonical observation generation and this requested page. For sports and esports reads, the first four counts remain global through category, cohort and all selectors; with admission=most_held_48h they count that selection’s generation, where every wider_holder candidate it did not take is capacity_limited. They are neither a census of all provider markets nor a count of successfully evaluated holders. Selected and returned counts describe the requested projection. An unmappable legacy category synthesizes a zero-work empty generation with all six counts zero and no degradation reasons; it does not read the all-sports cache.| Field | Type | Required | Description |
|---|---|---|---|
input_markets | integer | Yes | Sum of canonical source-generation funnel input across all sports, before category, cohort or selector projection. |
capacity_limited_markets | integer | Yes | Canonical source-generation input assigned capacity_limited. These markets were intentionally outside the bounded holder-work admission and are not missing emitted rows. It includes the admitted pregame wider_holder markets of any sport no request named in the last 30 minutes, whose holders the generation did not read. |
emitted_observations | integer | Yes | All wider_holder and in_play observations emitted in the canonical source generation, before cohort, category or selector projection. Emerging pile is an overlapping projection and does not add source emissions. |
incomplete_holder_markets | integer | Yes | Canonical source-generation markets whose attempted holder scan did not establish complete coverage, including incomplete scans that did not emit an observation. Collection reads one 100-row page per token, so a market with more holders on a token counts here by design; this count does not by itself degrade the generation. |
selected_observations | integer | Yes | Observations matching the requested cohort, category, selectors and applicable pinned projection cutoff before pagination. |
returned_observations | integer | Yes | Observation rows on this page; equals data.length. |
EdgeHunterObservationDegradationReason
One observed cause of operational degradation in the canonical all-sports observation generation. Reasons are independent of the one-terminal-per-input funnel and remain unchanged through category, cohort and selector projection. Intentional capacity limits and an unconfigured upcoming source are not degradation reasons.| Field | Type | Required | Description |
|---|---|---|---|
reason | holder_scan_incomplete | live_source_stale | directional_unavailable | funnel_unreconciled | board_live_unavailable | board_upcoming_unavailable | provider_unavailable | holder_deadline_unavailable | holder_computation_unavailable | missing_stored_market | price_unavailable | in_play_stale_observed | in_play_directional_unavailable | internal_unclassified | board_source_unavailable | board_deadline_unavailable | Yes | Recorded producer cause. holder_scan_incomplete is retired and no longer emitted: the one-page holder read is an intentional bound, disclosed by each row’s holder_scan_complete and by coverage.incomplete_holder_markets, and it does not degrade a generation. directional_unavailable can accompany an emitted wider_holder row; live_source_stale means provider live evidence exceeded its freshness bound. Other values identify reconciliation, applicable board-source or terminal failure evidence. |
sport | string | null | Yes | Canonical sport for the recorded cause; null only for generation-wide evidence without a sport attribution. |
EdgeHunterObservationDeparture
A market whose wider_holder card left this selection before kickoff, with why it left.| Field | Type | Required | Description |
|---|---|---|---|
condition_id | string | Yes | Raw Polymarket condition id. |
event_slug | string | null | Yes | |
category | Basketball | Football | Baseball | Hockey | MMA | Boxing | Soccer | Cricket | Golf | Tennis | Esports | Racing | Table Tennis | Pickleball | Yes | Canonical sport bucket the departed card carried. |
admitted_by | most_held | soonest_kickoff | most_held_48h | most_held_48h_by_type | Yes | The departed card’s admitted_by: most_held_48h on an admission=most_held_48h response. |
game_start_time | string | Yes | Kickoff the departed card carried, in UTC. The entry leaves the list once it passes. |
last_observed_at | string | Yes | The departed card’s observed_at: when its last evaluation finished. |
departed_at | string | Yes | snapshot_as_of of the first snapshot of this selection without the card. |
reason | EdgeHunterObservationTerminalReason | Yes | Why the market has no card: its terminal in this selection’s funnel in the snapshot it left, and while that terminal reports a read that did not finish (holder_deadline_unavailable, provider_unavailable, holder_computation_unavailable, internal_unclassified), the terminal of each later snapshot until one answers; an answered reason stays, except as view=signals starts or stops listing the market. primary_slate_candidate: view=signals lists the market. While the entry stays, a later snapshot that read view=signals and no longer excludes the market replaces it with that snapshot’s terminal, one that excludes the market replaces any other reason with it, and one with signals_as_of null leaves it as it is. capacity_limited: it lost its evaluation place without another outcome. missing_stored_market: the market was no longer in the stored market universe. Any other value means what it means in the funnel, for example split_holder_pile, no_current_graded_holder or resolved. |
EdgeHunterObservationTerminalReason
Closed 25-value terminal-reason vocabulary for the accountable Edge Hunter observation funnel. capacity_limited is intentional bounded provider-work admission and does not itself set the snapshot degraded. board_source_unavailable is a completed board-source failure; board_deadline_unavailable means live-board work missed either an internal configured-scope deadline or the outer fair-wave deadline; both classify only already-started rows, so for the upcoming source read funnel.sports[].board_upcoming_status instead; provider_unavailable is reserved for a holder read sent to the provider that failed, with no reusable holder page; holder_deadline_unavailable is holder cache/provider absolute-deadline exhaustion or a holder read local capacity never sent, with no reusable holder page. String enum:outside_horizon, resolved, provider_closed, provider_excluded, invalid_market, missing_token, missing_stored_market, not_provider_live, board_source_unavailable, board_deadline_unavailable, primary_slate_candidate, zero_indexed_holder_research, capacity_limited, provider_unavailable, holder_deadline_unavailable, holder_computation_unavailable, holder_scan_incomplete, no_current_graded_holder, split_holder_pile, price_unavailable, wider_holder_emitted, in_play_emitted, in_play_stale_observed, in_play_directional_unavailable, internal_unclassified.
EdgeHunterObservationsResponse
Full Edge Hunter observations list envelope. Required degradation_reasons explains the source-generation verdict; required coverage distinguishes source input, intentional capacity exclusions, source emissions, incomplete holder scans, selection and the returned page. The view literal distinguishes advanced collections, including empty pages.| Field | Type | Required | Description |
|---|---|---|---|
object | string | Yes | |
view | string | Yes | |
data | array of EdgeHunterObservation | Yes | |
has_more | boolean | Yes | |
next_cursor | string | null | Yes | Pass as cursor for the next page. Always sent; null on the last page. |
snapshot_as_of | string | Yes | Completion time of the shared observation snapshot pinned by the cursor. |
degraded | boolean | Yes | True when an operational failure or unknown provider-board, holder, directional, reconciliation, or internal completeness state made this snapshot partial. This is snapshot-wide and can retain degradation that the funnel’s one-terminal-per-input accounting cannot represent. Inspect degradation_reasons for every recorded source-generation cause and its nullable canonical sport attribution. Intentional bounds do not by themselves set this field: capacity_limited rows remain fully accounted in the funnel, and a holder scan the one-page read leaves incomplete counts in coverage.incomplete_holder_markets; board_upcoming_status=not_configured is not a failure. |
degradation_reasons | array of EdgeHunterObservationDegradationReason | Yes | Sorted, deduplicated causes from the canonical all-sports generation, unchanged by category, cohort or selectors; with admission=most_held_48h, from that selection’s generation. Empty exactly when degraded is false. Capacity-limited input, the one-page holder bound (holder_scan_complete=false) and board_upcoming_status=not_configured do not by themselves add a reason. |
coverage | EdgeHunterObservationCoverage | Yes | |
funnel | EdgeHunterFunnelReport | Yes | |
meta | ResponseMeta | Yes | |
selection | EdgeHunterSelection | No | Normalized axes requested with a selector or category; omitted on an unselected default read. |
admission | most_held_48h | most_held_48h_by_type | most_held_48h_min_25_usd | No | Echoes the opt-in admission rule a request named; omitted on a default read. When present, data, funnel, coverage, degraded and degradation_reasons describe that selection, not the default one. |
departures | array of EdgeHunterObservationDeparture | No | cohort=wider_holder only, for the default selection and for admission=most_held_48h: markets that had a wider_holder card in an earlier snapshot of the same selection, have none in this one, and have not kicked off. Newest departed_at first. An entry stays until the game_start_time it carries passes, and leaves as soon as the market has a card again; while it stays, its reason changes only while it reports an unfinished read or when view=signals starts or stops listing the market (see reason), and a later departure of the same market is a new entry. Filtered by the same category and selectors as data, and identical on every page of one snapshot. At most 336 entries; when more are open, the oldest departures leave first. An empty array means no card of this selection is departed. Omitted on in_play and emerging_pile, and on a snapshot that could not establish its departures, never reported as an empty array. Tracking that restarts after its record is lost starts empty. |
signals_as_of | string | null | No | The ranked_at of the view=signals snapshot whose listed markets this snapshot excluded from wider_holder as primary_slate_candidate. The refresh that computed this snapshot read it as it started, so it can be one refresh older than the view=signals snapshot a reader sees at the same moment. null when no view=signals snapshot could be read: that refresh excluded no market, and the funnel counts no primary_slate_candidate. Omitted on an unmappable legacy category, which reads no generation. |
most_held_48h_cutoffs | array of EdgeHunterMostHeld48hCutoff | No | admission=most_held_48h and most_held_48h_by_type only: for each sport in the response’s category scope that most_held_48h admitted a market in, the last market it admitted in the same snapshot (the 8th when 8 are admitted) and the values it was ranked by. A row whose most_held_48h_position is greater than its sport’s position took no most_held_48h slot. Not narrowed by selectors other than category. On admission=most_held_48h_min_25_usd they are that selection’s own last markets, each with indexed_graded_holders_min_25_usd. Omitted on a default read and on a snapshot computed before this field. |
EdgeHunterOutcome
One provider outcome in fixed YES/NO order, including its frozen token identity and independently observed quote. Null current_price means no verified current quote is available.| Field | Type | Required | Description |
|---|---|---|---|
index | 0 | 1 | Yes | |
label | string | null | Yes | |
provider_id | integer | null | Yes | |
token_id | string | null | Yes | Frozen provider CLOB token ID for this exact outcome in YES/NO order. Null when unavailable; not a participant identity. |
current_price | EdgeHunterPrice or null | Yes |
EdgeHunterParticipant
| Field | Type | Required | Description |
|---|---|---|---|
provider_id | integer | No | |
logo | string | No | |
logo_mark_dark | boolean | No | |
color | string | No | |
headshot | string | No | |
headshot_revision | integer | No | |
tour | string | No | |
name | string | Yes | |
logo_mark_light | boolean | No | |
logo_mark_measured | boolean | No |
EdgeHunterPrice
| Field | Type | Required | Description |
|---|---|---|---|
price | string | Yes | Provider probability as a decimal string. Keep its precision until display. |
basis | midpoint | last_trade | Yes | |
ts | string | Yes | Source observation clock in epoch milliseconds, represented as a string. |
validated_at | string | No | Backend validation clock in epoch milliseconds. Omitted when no current-source validation is available. |
EdgeHunterRankedSignal
One ranked pre-game sports market where graded sharp money is piled on one side, with required-status category evidence from partial forward-observed Polymarket fills.| Field | Type | Required | Description |
|---|---|---|---|
side | string | null | Yes | The side profitable wallets hold, as a provider-backed display label. Canonical spelling of piled_side (#16310), same value: when provider group context is unavailable it may remain a bare Yes/No/Over/Under, so do not use it alone as participant identity. |
ranked_at | string | Yes | UTC time at which the snapshot that ranked this row was computed. Canonical spelling of signal_created_at (#16310), same value. |
backing_score | number | Yes | Recorded side backing score; higher values indicate stronger backing. |
side_share | number | null | Yes | Signed share of graded money on the side, (yes_usd - no_usd)/(yes_usd + no_usd) in [-1, 1] (side-yes positive, side-no negative). Canonical spelling of smart_score (#16309, #16310), same value. |
condition_id | string | Yes | Polymarket condition id. |
signal_created_at | string | Yes | UTC time at which the immutable signal snapshot was computed. Every row from one snapshot shares this value; it is not provider market creation time and is not rewritten at request time. Deprecated (#16310): ranked_at is the canonical spelling and carries the same value; this key stays on the wire. |
token_id | string | null | Yes | Polymarket CLOB token id (ERC1155 asset id, decimal string) for the PILED outcome; null when unavailable. |
category | Basketball | Football | Baseball | Hockey | MMA | Boxing | Soccer | Cricket | Golf | Tennis | Esports | Racing | Table Tennis | Pickleball | null | Yes | Canonical sport bucket (e.g. Basketball, Tennis); null when the raw category has no canonical mapping. |
raw_category | string | null | Yes | Raw provider category as stored (e.g. NBA, EPL). |
title | string | null | Yes | |
event_slug | string | null | Yes | |
game_start_time | string | null | Yes | Kickoff (UTC). In the future at SNAPSHOT time and within the requested horizon; because the response is served from a shared snapshot cached up to the ~180s TTL, a served kickoff can be up to ~180s in the past relative to the response time. Not a live guarantee that the game has not yet started. |
piled_side | string | null | Yes | Nullable provider-backed piled-outcome display label. When provider group context is unavailable, it may remain a bare Yes/No/Over/Under; do not use it alone as participant identity. Deprecated (#16310): side is the canonical spelling and carries the same value; this key stays on the wire. |
piled_outcome_index | integer | Yes | Provider binary-column selector: 0 selects outcome_yes/token_id_yes; 1 selects outcome_no/token_id_no. It does not identify home/away or a participant. Use piled_side together with title/event context for display. |
sharp_pct | number | null | Yes | Piled-side dollar concentration backed_usd / (yes_usd + no_usd), in (0.5, 1] for a real pile; null when there is no sharp USD. |
backed_sharp_usd | number | Yes | Raw piled-side sharp-money USD. |
s_count | integer | Yes | S-grade graded holders on the piled side. |
a_count | integer | Yes | A-grade graded holders on the piled side. |
b_count | integer | Yes | B-grade graded holders on the piled side. |
graded_holders | integer | Yes | Piled-side graded holder count (s_count + a_count + b_count). |
top_grade | S | A | B | null | Yes | Best grade present on the piled side; null when none. |
smart_score | number | null | Yes | Canonical sharp-money score (yes_usd - no_usd)/(yes_usd + no_usd) in [-1, 1] (piled-yes positive, piled-no negative). Deprecated (#16310): side_share is the canonical spelling and carries the same value; this key stays on the wire. |
volume | number | null | Yes | Cumulative provider taker volume in shares, not cash or dollars. |
net_side | BUY | SELL | null | Yes | Aggregate recent flow direction on the market; null when unavailable. |
conviction_score | number | Yes | Recorded conviction score; higher values indicate stronger conviction. |
one_way_holder_count | integer | null | Yes | Piled-side graded holders read one-way: their fresh open legs across the signal game’s markets (cross-market within the one game; moneyline+spread family only) all back the same team, or, when the market’s holder scan was complete, Polymarket’s currentValue shows no opposite leg on this market worth 10% of the backed leg and no fresh leg opposes it. Null when the directional read was not computed (no groupable game, no holder-level data on this ranking path, or the enrichment read failed) or classified nobody. |
hedged_holder_count | integer | null | Yes | Piled-side graded holders classified HEDGED across the game by fresh legs (they back two or more distinct teams). A wallet long both outcomes of this market is not one-way and not counted here. Null when the directional read was not computed or classified nobody. |
one_way_graded_usd | number | null | Yes | Piled-side graded USD held by one-way wallets (share-weighted allocation of backed_sharp_usd). Null when the directional read was not computed or classified nobody. |
directional_confidence | number | null | Yes | One-way fraction, in [0, 1], of the piled graded dollars the directional read classified: hedged and two-sided dollars count against it, unclassified ones are left out. Null when the read was not computed or over 10% of the pile is unclassified. |
directional_rank_score | number | Yes | Recorded side ordering score; higher values sort first. |
category_skill | EdgeHunterCategorySkill | Yes | |
rank | integer | Yes | 1-based rank within the (min_grade-filtered) ranked result. |
market_context | EdgeHunterMarketContext or null | Yes | Required nullable frozen metadata context. Null only during the legacy-generation transition; selected reads require sidecar readiness and fail closed with 503 instead. |
protocol_version | v1 | v2 | Yes | The Polymarket protocol the market trades on, Gamma’s market version: v1 (CTF, ConditionalTokens) or v2 (Protocol V2). Read from the condition id, the same value GET /api/v1/markets/settled serves. On a v2 market every token_id this object names is a V2 position id: sign its orders for ExchangeV3 and read its balance as CONDITIONAL-V2. |
EdgeHunterRow
One full Max row from Edge Hunter. signal is populated on every row this endpoint returns. Identity and quotes preserve provider values; unknown values stay null.| Field | Type | Required | Description |
|---|---|---|---|
rank | integer | Yes | |
state | string | Yes | |
free | boolean | Yes | |
condition_id | string | Yes | |
event_slug | string | null | Yes | |
title | string | null | Yes | |
category | Basketball | Football | Baseball | Hockey | MMA | Boxing | Soccer | Cricket | Golf | Tennis | Esports | Racing | Table Tennis | Pickleball | null | Yes | |
raw_category | string | null | Yes | |
game_start_time | string | null | Yes | |
volume | number | null | Yes | Cumulative provider taker volume in shares, not cash in USD. Null when unavailable. |
participants | array of EdgeHunterParticipant | Yes | |
image | string | null | Yes | |
outcomes | array of EdgeHunterOutcome | Yes | |
signal | EdgeHunterSignal or null | Yes | |
market_context | EdgeHunterMarketContext or null | Yes | Required nullable frozen metadata context. Null only during the legacy-generation transition; selected reads require sidecar readiness and fail closed with 503 instead. |
protocol_version | v1 | v2 | Yes | The Polymarket protocol the market trades on, Gamma’s market version: v1 (CTF, ConditionalTokens) or v2 (Protocol V2). Read from the condition id, the same value GET /api/v1/markets/settled serves. On a v2 market every token_id this object names is a V2 position id: sign its orders for ExchangeV3 and read its balance as CONDITIONAL-V2. |
EdgeHunterSelection
Normalized requested selection axes. Only requested axes appear; omitted for unselected defaults. Arrays are nonempty, sorted and deduplicated. OR within an axis, AND across axes.| Field | Type | Required | Description |
|---|---|---|---|
kind | sports | esports | No | |
category | string | No | Resolved legacy canonical bucket or non_sport for an unmappable category. |
sports | array of string | No | Canonical sport buckets, including Esports and Table Tennis, matched case-insensitively. Unknown names and league aliases such as NFL are rejected in sports; use category for legacy bucket aliases or leagues for exact league selection. Omission covers every sport admitted by the selected view. |
leagues | array of string | No | Normalized machine/provider league identities, such as nfl, cfb, nba, epl, cs2, lol, dota2 or valorant. Known wire/tag aliases normalize; other provider keys match exact lowercase identity. This is separate from category: category=NFL selects Football, while leagues=nfl selects NFL only. Read market_context.league for authoritative values. |
market_types | array of string | No | Exact provider sports_market_type values. This is an open provider taxonomy, distinct from exact market IDs. Read market_context.market_type; missing selected metadata excludes the row. |
condition_ids | array of string | No | Exact market selections. Raw provider condition IDs and the existing mkt_-prefixed aliases normalize to raw IDs. Unknown well-formed IDs return an empty result. |
event_slugs | array of string | No | Exact provider event slugs. Use event_slug returned on the row; no title or slug-prefix guessing. |
series_slugs | array of string | No | Exact provider series slugs. Read market_context.series_slug; a missing selected series excludes the row. |
EdgeHunterSignal
Backed-side analytics, token identity, frozen ranked_at and aggregate category evidence from the ranked snapshot, plus a separately dated current quote. Scores rank attention; they are not probabilities or order instructions.| Field | Type | Required | Description |
|---|---|---|---|
piled_side | string | null | Yes | |
piled_outcome_index | 0 | 1 | Yes | |
sharp_pct | number | null | Yes | Fraction of graded money on the backed side, not a percentage from 0 to 100. |
backed_sharp_usd | number | Yes | |
s_count | integer | Yes | |
a_count | integer | Yes | |
b_count | integer | Yes | |
graded_holders | integer | Yes | |
top_grade | S | A | B | null | Yes | |
smart_score | number | null | Yes | |
net_side | string | null | Yes | |
conviction_score | number | Yes | |
one_way_holder_count | integer | null | Yes | |
hedged_holder_count | integer | null | Yes | |
one_way_graded_usd | number | null | Yes | |
directional_confidence | number | null | Yes | |
directional_rank_score | number | Yes | |
current_price | EdgeHunterPrice or null | Yes | |
token_id | string | null | Yes | Frozen provider CLOB token ID for the backed outcome. Null when unavailable; matches outcomes[piled_outcome_index].token_id when the shared provider context is available. |
ranked_at | string | Yes | UTC computation time copied from this ranked row’s frozen signal_created_at. It dates the ranking, not the separately observed quote, metadata writer, or wallet entry. |
category_skill | EdgeHunterCategorySkill | Yes | Existing aggregate category evidence copied from the same ranked snapshot. Read its status, coverage and own clocks; it never changes admission or ordering and is not a predicted return. |
EdgeHunterSignalsResponse
Full Edge Hunter signals list envelope. The view literal distinguishes advanced collections, including empty pages.| Field | Type | Required | Description |
|---|---|---|---|
object | string | Yes | |
view | string | Yes | |
data | array of EdgeHunterRankedSignal | Yes | |
has_more | boolean | Yes | |
next_cursor | string | No | |
total | integer | No | |
meta | ResponseMeta | Yes | |
selection | EdgeHunterSelection | No | Normalized axes requested with a selector or category; omitted on an unselected default read. |
EdgeHunterSportFunnelReport
Independent sports-board supply plus stored-universe terminal accounting for one canonical sport.| Field | Type | Required | Description |
|---|---|---|---|
sport | Basketball | Football | Baseball | Hockey | MMA | Boxing | Soccer | Cricket | Golf | Tennis | Esports | Racing | Table Tennis | Pickleball | Yes | |
board_input | integer | Yes | Unique condition ids independently visible on the provider-first sports board. |
board_live_available | boolean | Yes | Whether the always-applicable live-board source completed as available. False can mean a completed source failure (board_source_unavailable) or live-board work missing an internal configured-scope deadline or the outer fair-wave deadline (board_deadline_unavailable); inspect terminals to distinguish them. |
board_upcoming_configured | boolean | Yes | Whether a provider-backed upcoming-board source is configured and applicable for this sport. False means not applicable, not provider failure. |
board_upcoming_available | boolean | Yes | Whether every configured upcoming-board scope completed as available. False with board_upcoming_configured=false means not applicable. When board_upcoming_configured is true and this flag is false, read board_upcoming_status for the cause (unknown means no cause was recorded, which no computed snapshot reports): the board_source_unavailable and board_deadline_unavailable terminals are assigned only to already-started rows (the live half) and are structurally 0 for the upcoming source, so they never explain this flag. |
board_upcoming_status | unknown | not_configured | available | capacity_limited | source_unavailable | cold_unavailable | deadline_unavailable | Yes | Why the upcoming-board source is (un)available. Board supply is one canonical-sport union: the bare category owns live truth and every configured composed league scope contributes upcoming rows; folded leagues without a configured board (currently CFL) are not in the upcoming union. available: every configured scope completed truthfully (a successful empty schedule still counts). capacity_limited: provider pagination or a configured upcoming cache published an intentionally bounded complete-event prefix; those rows are excluded from diagnostic-universe input and must not be treated as a complete upcoming universe. Cache-bound prefixes are limited to an exact 5,000,000-byte final envelope. source_unavailable: composition failed before a truthful union; resolved scope readers turn half failures into cold_unavailable, so fresh producers are whole-union identity reconciliation or a registry contract failure and carry zero rows. cold_unavailable: every scope completed but at least one reported its upcoming half unavailable because no servable entry was inside the stale-serve bound and the background warm did not land in time; it is not by itself proof of a provider outage. deadline_unavailable: an internal configured-scope deadline or the outer bounded fair wave expired. An internal deadline may retain healthy bare-category or sibling-scope rows; the outer wave records zero rows. These upcoming fields do not describe league live-membership availability. If the bare-category live scope fails, all live rows are dropped even when a league scope completed, because the bare category is the sole live-truth owner. not_configured: no upcoming scope applies to the sport. unknown: no cause was recorded; every computed snapshot reports a concrete status, so none reads unknown. board_upcoming_available is exactly board_upcoming_status == available. |
board_upcoming_unavailable_scopes | array of category | nfl | cfb | nba | wnba | euroleague-basketball | ncaa-basketball | cwbb | nhl | mls | valorant | league-of-legends | counter-strike-2 | dota-2 | registry | union | wave | Yes | Configured upcoming scopes that did not complete as available. Values are category, a provider league tag slug (nfl, cfb, nba, wnba, euroleague-basketball, ncaa-basketball, cwbb, nhl, mls, valorant, league-of-legends, counter-strike-2, or dota-2), registry when the compiled scope/projection contract drifted, union when cross-scope identity reconciliation failed, or wave when the outer fair-wave deadline expired before scope-level evidence returned. Empty means no unavailable upcoming scope was identified; this includes healthy/not-configured rows and a legacy cached row. Observation league scopes are upcoming-only and perform no live-membership read. |
input | integer | Yes | Stored-universe rows plus provider-board rows missing from storage. |
terminals | map of integer | Yes | Sparse counts over the closed 25-value terminal vocabulary: outside_horizon, resolved, provider_closed, provider_excluded, invalid_market, missing_token, missing_stored_market, not_provider_live, board_source_unavailable, board_deadline_unavailable, primary_slate_candidate, zero_indexed_holder_research, capacity_limited, provider_unavailable, holder_deadline_unavailable, holder_computation_unavailable, holder_scan_incomplete, no_current_graded_holder, split_holder_pile, price_unavailable, wider_holder_emitted, in_play_emitted, in_play_stale_observed, in_play_directional_unavailable, or internal_unclassified. primary_slate_candidate means the view=signals snapshot named by signals_as_of lists the market at its widest selection (horizon_hours=48, min_grade=B, no selector), so it is not a wider_holder candidate; when no view=signals snapshot could be read (signals_as_of null), no market takes it. capacity_limited is intentional bounded provider-work admission, is fully accounted here, and does not itself set degraded=true. board_source_unavailable means a completed board source was unavailable; board_deadline_unavailable means live-board work missed either an internal configured-scope deadline or the outer fair-wave deadline; provider_unavailable means a holder read sent to the provider failed and the market had no reusable holder page; holder_deadline_unavailable means holder cache/provider work missed the absolute request deadline, or local capacity never sent the holder read, and the market had no reusable holder page; holder_computation_unavailable means post-holder provider or DB-backed price/metadata evaluation was unavailable. |
terminal_total | integer | Yes | Sum of every sparse terminal count. |
reconciled | boolean | Yes | True exactly when input equals terminal_total. |
EventReplayEvent
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Opaque event identity: the ef_-encoded whale_alerts.id, stable across cursor formats. Deduplicate on this, never on cursor or sequence. |
type | whale_trades_inserted | Yes | |
cursor | string | Yes | Cursor positioned at this event: its (inserted_xid, id) commit-order position. Store the page’s next_cursor to continue; this one resumes from exactly this event. |
sequence | integer | Yes | whale_alerts.id of the event. Not monotonic across a replay: events arrive in commit order, so a lower id can follow a higher one when its write finished later. Order and resume by cursor, deduplicate by id. |
published_at | string | Yes | |
payload | object (count, whale_alert_id, condition_id, trader_id, platform) | Yes | What the event announces. Every field is present on every event; a field added later is additive, so a client tolerates keys it does not know. |
trade | LargeTrade or null | No | Present only with expand=trade: the base trade fields for this row, read at request time from one query per page. GET /api/v1/large-trades/{id} adds counterparty_analysis; replay does not include it. traded_at, side, size_usd, price, outcome, token_id, recorded_signal_score and trader.grade_at_trade with its status are the row’s event-time facts; trader.grade, trader.username, signal_score, suspicion_score, suspicion_track and market title/slug/category are enrichment that can move after the event. null when that route would answer 404 for the row (its trader or market is not synced yet). |
source | EventReplaySource | Yes | |
freshness | EventReplayFreshness | Yes |
EventReplayFreshness
| Field | Type | Required | Description |
|---|---|---|---|
status | string | Yes | |
observed_at | string | Yes |
EventReplayMeta
| Field | Type | Required | Description |
|---|---|---|---|
request_id | string | Yes | Unique request ID (req_ prefix). The same value as the X-Request-Id response header, the request’s usage accounting row and its log lines. |
cached | boolean | Yes | |
cost | integer | Yes | Advisory request weight (relative compute cost). 1 for simple reads; higher for heavier endpoints. Not a credit/price. |
replay | object (from_cursor, to_cursor, from_sequence, to_sequence, ordering, pending_beyond_horizon, filters, expand) | Yes | |
retention | object (status, retained_events, cursor_expired) | Yes | |
completeness | object (status, reason) | Yes |
EventReplaySource
| Field | Type | Required | Description |
|---|---|---|---|
kind | string | Yes | |
producer_family | whale_trades | Yes | |
owner | string | Yes | |
provider_fetch_at_request_time | boolean | Yes |
ExactDecimal
A lossless decimal atom rendered from the canonical NUMERIC or provider value. The value is a decimal string and must be parsed with a decimal library; it is never a display string and must not be converted through a binary float.scale is the source decimal scale. The field is omitted when its source is unavailable.
| Field | Type | Required | Description |
|---|---|---|---|
value | string | Yes | Plain decimal text at full source precision, including a minus sign for negative values and trailing zeros when the source scale carries them. Parse as an arbitrary-precision decimal. |
unit | string | Yes | Unit of the value, such as USD, USD/share, or shares. |
scale | integer | Yes | Number of digits after the decimal point in value’s source atom. |
basis | string | Yes | Backend-owned source or derivation basis. Treat it as provenance, not as a display label. |
ExploreEntry
One of:ExploreGroup, ExploreStandalone. Discriminated by type.
ExploreFacetValue
| Field | Type | Required | Description |
|---|---|---|---|
value | string | Yes | |
label | string | Yes | |
count | integer | Yes |
ExploreFacets
| Field | Type | Required | Description |
|---|---|---|---|
categories | array of ExploreFacetValue | Yes | |
platforms | array of ExploreFacetValue | Yes |
ExploreGroup
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | |
event_slug | string | Yes | |
parent_title | string | Yes | |
image | string | null | Yes | |
platform | polymarket | null | Yes | Provider platform. Always polymarket, or null when the row carries no stored value. |
category | string | null | Yes | |
markets | array of ExploreMarket | Yes | Markets in the event cluster, ranked by volume with condition_id as the tie-breaker. The selected representative is retained within the 12-market cap. |
rep_volume | number | null | Yes | The volume of the group’s highest-volume market, which is markets[0]: the same figure as that market’s volume, Polymarket’s cumulative taker volume in shares rather than cash. Null when unavailable. |
rep_large_trades | integer | null | Yes | Canonical key since #16304; rep_whales is its deprecated spelling, emitted beside it with the same value until its sunset on 2027-02-01 (#29352). |
rep_whales | integer | null | Yes | Deprecated spelling of rep_large_trades, emitted beside it with the same value. Sunset 2027-02-01 (#29352): removed from V1 on that date; read rep_large_trades. |
ExploreMarket
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | |
condition_id | string | Yes | |
title | string | Yes | Non-empty market title. |
slug | string | null | Yes | Provider-native market slug. |
url_slug | string | null | Yes | First-party market page slug used for internal links. |
image | string | null | Yes | |
icon | string | null | Yes | |
category | string | null | Yes | |
platform | polymarket | null | Yes | Provider platform. Always polymarket, or null when the row carries no stored value. |
status | active | closed | Yes | closed once Polymarket has closed trading or the market has resolved; active otherwise. The same rule labels a market on markets/search, markets/explore and market/{condition_id}/snapshot. |
volume | number | null | Yes | Polymarket’s traded-volume figure for the market, as last stored: cumulative taker volume in shares, each counted at its $1 settlement value, not the cash that changed hands (100 shares bought at $0.40 add 100, not 40). It can lag Polymarket’s current figure. sort=volume orders by it. Null when unavailable. |
liquidity | number | null | Yes | |
large_trade_count | integer | null | Yes | Canonical key since #16304 (Polymarket’s noun is large trade); whale_trade_count is its deprecated spelling, emitted beside it with the same value until its sunset on 2027-02-01 (#29352). |
whale_trade_count | integer | null | Yes | Deprecated spelling of large_trade_count, emitted beside it with the same value. Sunset 2027-02-01 (#29352): removed from V1 on that date; read large_trade_count. |
large_trade_distinct_wallets | integer | null | Yes | Canonical key since #16304; whale_distinct_wallets is its deprecated spelling, emitted beside it with the same value until its sunset on 2027-02-01 (#29352). |
whale_distinct_wallets | integer | null | Yes | Deprecated spelling of large_trade_distinct_wallets, emitted beside it with the same value. Sunset 2027-02-01 (#29352): removed from V1 on that date; read large_trade_distinct_wallets. |
large_trade_total_usd | number | null | Yes | Canonical key since #16304; whale_total_usd is its deprecated spelling, emitted beside it with the same value until its sunset on 2027-02-01 (#29352). |
whale_total_usd | number | null | Yes | Deprecated spelling of large_trade_total_usd, emitted beside it with the same value. Sunset 2027-02-01 (#29352): removed from V1 on that date; read large_trade_total_usd. |
large_trade_last_at | string | null | Yes | Canonical key since #16304; whale_last_trade_at is its deprecated spelling, emitted beside it with the same value until its sunset on 2027-02-01 (#29352). |
whale_last_trade_at | string | null | Yes | Deprecated spelling of large_trade_last_at, emitted beside it with the same value. Sunset 2027-02-01 (#29352): removed from V1 on that date; read large_trade_last_at. |
end_date | string | null | Yes | |
created_at | string | null | Yes | |
outcome_yes | string | null | Yes | |
token_id_yes | string | null | Yes | The Polymarket CLOB token id (ERC1155 asset id, decimal string) for the YES outcome; null when unavailable (e.g. unsynced markets). |
outcome_no | string | null | Yes | |
token_id_no | string | null | Yes | The Polymarket CLOB token id (ERC1155 asset id, decimal string) for the NO outcome; null when unavailable (e.g. unsynced markets). |
event_slug | string | null | Yes | |
smart_score | number | null | Yes | |
smart_count | integer | null | Yes | |
smart_label | string | null | Yes | The outcome graded money leans toward RELATIVE TO THE PRICE: named only when the graded money’s share of a side sits well past that side’s price-implied share, enough graded money backs the leaning side that a few small positions cannot name it, and the side is not a long shot holding nearly all of the graded money. Null when the money sits with the price (no lean), when there is no graded money, or when the price is unavailable. The same rule as the market page. |
sharp_money_as_of | string | null | Yes | When the oldest stored smart-money wallet behind this split (smart_score, smart_count and smart_label) last finished syncing. Graded wallets sync on different schedules, so this is often hours or days ago. Some holdings in the split can come from a Polymarket holder read cached for up to 3 minutes, which this time does not describe. Null when there is no split or a wallet’s sync time is unknown. |
outcome_yes_label | string | null | Yes | Display label for the YES/outcome_index=0 side, enriched from provider outcome metadata when available. |
outcome_no_label | string | null | Yes | Display label for the NO/outcome_index=1 side, enriched from provider outcome metadata when available. |
outcome_yes_provider_id | integer | null | Yes | Provider-owned YES/outcome_index=0 identifier when available for trade-ticket wiring. |
outcome_no_provider_id | integer | null | Yes | Provider-owned NO/outcome_index=1 identifier when available for trade-ticket wiring. |
open_interest | number | null | Yes | |
oi_change_pct | number | null | Yes | |
price_points | array of array of number | null | Yes | |
no_price_points | array of array of number | null | Yes | |
last_price | number | null | Yes | |
no_last_price | number | null | Yes | |
change_pct_24h | number | null | Yes | |
no_change_pct_24h | number | null | Yes | |
discover_score | number | null | Yes | Backend-owned deterministic market discovery score used by the hot sort. |
score_components | object (volume_signal, large_trade_signal, whale_signal, liquidity_signal, recency_signal, sharp_money_signal, smart_money_signal, price_move_signal, missing_price_penalty) | Yes | |
freshness | object (enrichment_status, price_status) | Yes | |
protocol_version | v1 | v2 | Yes | The Polymarket protocol the market trades on, Gamma’s market version: v1 (CTF, ConditionalTokens) or v2 (Protocol V2). Read from the condition id, the same value GET /api/v1/markets/settled serves. On a v2 market every token_id this object names is a V2 position id: sign its orders for ExchangeV3 and read its balance as CONDITIONAL-V2. |
ExploreStandalone
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | |
market | ExploreMarket | Yes |
ExportCompleteness
| Field | Type | Required | Description |
|---|---|---|---|
status | complete | partial | empty | Yes | |
reason | string | Yes | |
sync_coverage | number | Yes |
ExportCounts
| Field | Type | Required | Description |
|---|---|---|---|
pnl_days | integer | Yes | The days in the export file’s pnl section, the wallet’s sports and esports realized P&L by UTC day: the file’s export_metadata.pnl_rows, at most its earliest 3650 days. 0 while source_range.pnl_series_status is pending, and 0 with it ready for a wallet that traded no sports or esports market. |
exported_markets | integer | Yes | The wallet’s sports and esports markets: the rows of the export’s markets section, before its 50,000-row cap. |
estimated_trade_rows | integer | Yes | Estimated trades in the wallet’s sports and esports markets: the summed trade counts of those markets. The file counts its own rows in generation.source_watermarks.trades.rows. |
estimated_size_mb | number | Yes | Estimated file size from estimated_trade_rows and exported_markets. |
ExportJobCancelledData
export_job_cancelled data: the owner’s export stopped because its owner cancelled it.
| Field | Type | Required | Description |
|---|---|---|---|
job_id | integer | Yes | |
status | string | Yes | |
format | string | Yes | |
next_action | string | Yes |
ExportJobExpiredData
export_job_expired data: the owner’s ready export passed retention.
| Field | Type | Required | Description |
|---|---|---|---|
job_id | integer | Yes | |
status | string | Yes | |
format | string | Yes | |
next_action | string | Yes |
ExportJobFailedData
export_job_failed data: the owner’s asynchronous export reached a terminal failure.
| Field | Type | Required | Description |
|---|---|---|---|
job_id | integer | Yes | |
status | string | Yes | |
format | string | Yes | |
next_action | string | Yes | |
failure_reason | string | Yes |
ExportJobReadyData
export_job_ready data: the owner’s asynchronous export can be downloaded. Download authorization stays on the status and download routes.
| Field | Type | Required | Description |
|---|---|---|---|
job_id | integer | Yes | |
status | string | Yes | |
format | string | Yes | |
next_action | string | Yes | |
total_trades | integer | null | Yes | |
processed_trades | integer | null | Yes | |
file_size | integer | null | Yes | Artifact size in bytes. |
data_as_of | string | null | Yes |
ExportSourceRange
| Field | Type | Required | Description |
|---|---|---|---|
first_pnl_date | string | null | Yes | The first UTC day in the export file’s pnl section, the wallet’s sports and esports realized P&L by day: the file’s export_metadata.pnl_date_from. Null when that section has no day, including while pnl_series_status is pending. |
last_pnl_date | string | null | Yes | The last UTC day in the export file’s pnl section: the file’s export_metadata.pnl_date_to. Null when that section has no day. |
pnl_series_status | ready | pending | Yes | Whether the export file’s pnl section holds the wallet’s sports and esports day series, the file’s export_metadata.pnl_series_status. pending means 0xinsider has not computed the series yet: the dates are null and counts.pnl_days is 0, which then never means the wallet has no day. A wallet that traded no sports or esports market is ready with null dates and counts.pnl_days 0: it never gets a series, and with nothing stored completeness.status is empty (since 2026-10-29, #30620, #30657). |
latest_trade_at | string | null | Yes | The latest trade in the wallet’s sports and esports markets. Null when it has none. |
latest_market_activity_at | string | null | Yes | Same instant as latest_trade_at: the latest activity of the markets the export holds. |
ExportVolumeReconciliation
| Field | Type | Required | Description |
|---|---|---|---|
provider_lifetime_volume | number | null | Yes | Deprecated (#30499): always null since 2026-10-29. It held Polymarket’s volume across every market of the wallet, which reconciles nothing against the sports and esports exported_activity_volume; the key stays so existing V1 clients keep parsing. Read exported_activity_volume for the wallet’s sports and esports volume. |
exported_activity_volume | number | null | Yes | Volume in USD, buys and sells, in sports and esports markets, each fill’s size times its price with fees excluded, summed over the wallet’s stored daily volume rows (from the fills 0xinsider stores for the wallet): the export file’s summary.volume_reconciliation.exported_activity_volume, not the sum of its pnl[].total_volume, which is null on a day the trade rollups do not cover. Never Polymarket’s share count. Null when any of those rows has no volume: a sum over the other days would be a partial subtotal. |
exported_market_cost_basis | number | Yes | Cost basis in USD summed over the wallet’s sports and esports markets, the markets section of the export. |
provider_activity_volume_gap | number | null | Yes | Always null. provider_lifetime_volume covered every market and exported_activity_volume sports and esports markets only, so their difference measured nothing; the field stays so existing clients keep parsing the object. |
activity_volume_coverage | number | null | Yes | Always null, for the same reason as provider_activity_volume_gap. |
FairPrice
One game outcome’s Polymarket fair price, with the checks that say whether it is fit to price a bet against.| Field | Type | Required | Description |
|---|---|---|---|
status | ok | wide_spread | thin_book | stale_quote | closed | unavailable | Yes | ok: two-sided, within max_spread_c, at or above min_book_usd_within_2c where the depth is known, confirmed current within 60 seconds. closed: the market closed or resolved, so there is no price to take. unavailable: no midpoint, and unavailable_reason says why. Otherwise the first entry of failed_checks. |
unavailable_reason | object | Yes | Set exactly when status is unavailable. cache_miss: the cache holds no book for the outcome yet, and this read starts its live book, so a read a few seconds later may answer. cache_unavailable: the book cache could not be read; a read a few seconds later may answer. stream_capacity: the market is not streamed and API reads hold every live book they may open; read it less often. no_orderbook: the provider confirmed the outcome has no order book. missing_provider_token_id: the outcome has no provider token id. one_sided_book: the book holds bids or asks, not both. empty_book: the book holds no orders. other_outcome_unavailable: the outcome’s book is two-sided, but another outcome of its market (a 1X2 game’s other leg, or a two-way market’s other side) has no midpoint, so the midpoints cannot be normalised. |
failed_checks | array of wide_spread | thin_book | stale_quote | Yes | Every check the quote failed, in status order; empty when none did. wide_spread: the spread is above max_spread_c. thin_book: a side holds less than min_book_usd_within_2c within 2 cents of the midpoint. stale_quote: the book was last confirmed current more than 60 seconds before as_of (quote.confirmed_age_seconds above 60). |
condition_id | string | Yes | The market’s condition id. |
event_slug | string | Yes | The market’s own event: the game’s slug, or a child event’s (a soccer game’s spreads and totals sit under its -more-markets event). game.event_slug is always the game’s. |
market_type | object | Yes | moneyline, spread or total; null for another market type, priced by condition_id. |
sports_market_type | string | null | Yes | The provider’s sportsMarketType, verbatim: moneyline, spreads, totals or another type. |
title | string | null | Yes | The provider’s per-market display name, for example Albania on a 1X2 leg. |
line | number | null | Yes | The outcome’s own handicap on a spread (-3.5), the total on a total (222.5); null on a moneyline. |
three_way | boolean | Yes | Whether the market is a leg of a soccer 1X2 game: fair.prob is then normalised over the three legs’ Yes midpoints. |
outcome | object (index, label, token_id) | Yes | The priced outcome. |
quote | object (best_bid, best_ask, mid, spread_c, book_depth_within_2c, observed_at, age_seconds, confirmed_at, confirmed_age_seconds, source) | Yes | The outcome’s cached top of book. |
fee | object (basis, rate, exponent, observed_at, taker_fee_per_share, taker_all_in_ask) | Yes | The taker fee a buy at quote.best_ask pays: fee per share = rate x (p x (1 - p))^exponent, with p the ask. |
fair | object (prob, prob_mid, decimal_odds, american_odds, method) | Yes | The fair probability and the odds it implies. |
game | object (event_slug, start, started) | Yes | The game the market belongs to. |
thresholds | object (max_spread_c, min_book_usd_within_2c, max_quote_age_seconds) | Yes | The limits this answer was checked against. |
as_of | string | Yes | When this answer was read. |
protocol_version | v1 | v2 | Yes | The Polymarket protocol the market trades on, Gamma’s market version: v1 (CTF, ConditionalTokens) or v2 (Protocol V2). Read from the condition id, the same value GET /api/v1/markets/settled serves. On a v2 market an outcome’s token_id is its V2 position id: sign its orders for ExchangeV3 and read its balance as CONDITIONAL-V2. |
FreshnessFailure
| Field | Type | Required | Description |
|---|---|---|---|
max_age_s | integer | Yes | The caller’s requested whole-response freshness ceiling in seconds. |
actual_age_s | integer | No | Age in seconds of the oldest stored data_quality.as_of clock, when one is available. |
as_of | string | No | The oldest stored data-quality clock used to calculate actual_age_s, when one is available. |
data_quality_status | fresh | stale | partial | unknown | untracked | unavailable | Yes | The trader body’s whole-response data-quality status. Only fresh or stale can satisfy max_age_s: the ceiling replaces each writer’s own budget, so a stale body inside it is answered. |
Game
One sports or esports game: both sides, its schedule, provider status, its winner markets (the moneyline, or the soccer 1X2 legs) with their available provider moneyline price states and liquidity, and the game’s traded volume. The event’s other markets are on GET /api/v1/games/{event_slug}/markets. Assembled from the same provider-first live and upcoming projections the site’s boards use, with no request-time provider fan-out.| Field | Type | Required | Description |
|---|---|---|---|
object | string | Yes | |
event_slug | string | Yes | The game’s identity, for example mlb-mil-cin-2026-06-22. The same key the live_sports_updated webhook pulse carries and the same key /api/v1/games/{event_slug} takes. |
game_id | string | No | The provider’s Gamma gameId, as a string. Omitted when the canonical owner has no single value for this slug: the provider stamps one gameId across an event’s derivative siblings, so an ambiguous read is reported as unknown rather than guessed. |
sport | string | No | The canonical sport bucket, for example Soccer or Table Tennis. Omitted when neither the board scope nor the provider category names one. |
league | string | No | The league tag, for example nfl or epl. Omitted for a sport served as one whole bucket with no league scope. |
title | string | No | The provider’s event title. Omitted when the provider sent none. |
scheduled_at | string | No | Kickoff in UTC, as the provider supplied it. Omitted when the provider published none; coverage.schedule then reads unavailable. |
status | GameStatus | Yes | |
competitors | array of GameCompetitor | Yes | Both sides, in the provider’s own order. That order states no home or away: Polymarket lists the away team first in US leagues and the home team first in soccer. Read a market’s side for home and away. Empty when the provider identified neither side. |
series_format | string | No | The esports series length, for example Bo3. Omitted for everything else. |
draw_offered | boolean | Yes | Whether this read includes a market classified as paying on a draw, including soccer’s independent 1X2 draw leg. Read this instead of assuming a two-outcome moneyline. |
markets | array of GameMarket | Yes | The game’s winner markets the sports board binds to its sides (the moneyline, or a soccer game’s three 1X2 legs), ordered by condition_id. Spreads, totals, period lines and props are on GET /api/v1/games/{event_slug}/markets. |
freshness | GameFreshness | Yes | |
coverage | GameCoverage | Yes | |
url | string | Yes | The game’s page on 0xinsider. |
sharp_money | GameSharpMoney | No | |
volume | GameVolume | No | The game’s traded volume, with its source, basis, unit and observation clock. A client can rank or filter games by volume.value. A live or upcoming game carries the figure the sports board holds for it. A game read from its stored record (freshness.source stored) carries the game volume summed from the stored volumes of its markets, the same game-lines rule, with no observed_at; it can trail the provider’s final figure slightly. Omitted when neither holds a volume for the game, as for a match nobody traded; never 0 in place of a missing figure. |
tournament | GameTournament | No | A tennis game’s tournament edition: its tier, city and country, venue time zone and official dates, from 0xinsider’s reviewed registry, the same facts the game’s page states. Omitted outside tennis, on a finished game read from its stored record (freshness.source stored), and when the registry holds no single edition for the game’s competition label, players’ tour and kickoff; never a guessed value. |
map_state | GameMapState | No | An esports series’ maps, each with its score per competitor and its result, the map in play, and when the reading behind them was taken. The same per-map state the game’s page shows. Present on every esports game, omitted for every other sport. |
GameCompetitor
One side of the game.| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | The team as its moneyline outcome names it, the same before, during and after the game (Jaguars, Penn). Where no outcome names the team, for example a soccer game’s Yes/No win markets, the provider’s full name (FC Bayern München). To identify a team, prefer provider_id. |
provider_id | string | No | The provider’s league-scoped competitor id, as a string. Omitted when the provider has not identified this side; coverage.competitors then reads labels. |
logo | string | No | Provider crest or logo URL. Omitted when there is none. |
score | string | No | The provider’s score for this side, verbatim. A string because the provider sends one: a set score, a map score and a run total are not all integers. Omitted when no live-score frame carries a score. |
record | string | No | The provider’s season record for this side, for example 12-4. Omitted when the provider sent none. |
GameCoverage
What this game’s read actually supplied, so a client branches on coverage instead of on a missing key.| Field | Type | Required | Description |
|---|---|---|---|
scores | available | unavailable | Yes | available when a live-score frame supplied a score for this game. A game no live-score feed has reported yet, as most scheduled games are, reads unavailable. |
competitors | provider_ids | labels | unavailable | Yes | provider_ids when every side carries a provider id, labels when only the provider’s names identify them, unavailable when neither exists. Do not join on names when this reads labels. |
schedule | available | unavailable | Yes | available when the provider supplied a kickoff. |
GameFreshness
How current this game’s facts are. Independent per source: the board half that produced the game, and the live-score frame that produced its scores.| Field | Type | Required | Description |
|---|---|---|---|
source | live | upcoming | stored | Yes | What produced this game: live or upcoming, the board half that carried it, or stored, the stored record of a finished game that has left the board (GET /api/v1/games/{event_slug}, and GET /api/v1/games with a finished status). |
source_status | ok | unavailable | Yes | Whether that half returned a truthful source body for this read. |
source_availability | available | unavailable | not_applicable | Yes | Whether that half had a source body at all. not_applicable means the sport has no configured source for that half. |
source_freshness | fresh | stale | unknown | not_applicable | Yes | Freshness of the cached source body, never inferred from the response clock or the row count. not_applicable for a stored game, whose record is final. |
source_observed_at | string | No | The source body’s data vintage. Omitted when the read has no vintage anchor, which is not age zero. For a stored game, the later of its last live-score write and its last leg settlement. |
source_age_seconds | integer | No | Age of source_observed_at in seconds, capped at 600. Omitted past the cap or with no anchor. |
delayed | boolean | Yes | Whether a reader should be told these rows are behind. This applies the half’s own servable-age bar (15 s live, 120 s upcoming), which is not the same as source_freshness: a live board whose scores are seconds old reads stale for about half of every publish cycle and is not delayed. |
scores_observed_at | string | No | When this game’s score was last observed. A write that observed no score, such as recording the end of a game the live-score feed stopped reporting, does not move it; a game ended that way before November 15, 2026 reads the time of that write. Omitted when there is no frame. |
scores_source_at | string | No | The provider’s own frame clock. Omitted when the frame carries none. |
scores_age_seconds | integer | No | Seconds since this game’s last Sports WebSocket frame. The esports feed resends an unchanged series about every 20 seconds, so this dates the feed’s last frame, not the last score change. Omitted when no Sports WebSocket frame dates the score, which is not age zero: a score read from the provider’s event listing is re-read on a cadence whether or not the game moved. |
scores_freshness | fresh | stale | unknown | not_applicable | Yes | Whether this game’s score and clock are current, judged on how often this league’s feed sends a frame, and independent of source_freshness, which dates the board: a board can be seconds old while one game’s frame is frozen. not_applicable outside play (scheduled, final, postponed, cancelled), at halftime and in a break between periods (a period of HT or End …). stale when the last frame is older than the bound measured for its state: 180 seconds for a running soccer half before stoppage time (the provider sends a frame each match minute); 120 seconds for an in-progress cs2 or lol series (the feed resends each running series about every 20 seconds, so fresh means the provider resent it, not that the map score moved); 600 seconds for a running period of men’s and women’s college basketball (league cbb, cwbb) and NHL hockey (nhl), whose feeds send no frame while the clock is stopped for a timeout or review. fresh within the bound. unknown otherwise: no dated frame, soccer stoppage time, a period clock at 00:00, End OT in women’s college basketball (the end of the third quarter, after which the provider sends no frame until the final), tennis (frames land on points and stop for changeovers and breaks), and every league with no measured bound, including the NBA and NFL. |
GameHoldersItem
One market of a game holders batch: GET /api/v1/market/{condition_id}/holders unfiltered and cut to the batch limit.| Field | Type | Required | Description |
|---|---|---|---|
data | array of MarketHolder | Yes | The roster’s top holders by current value, at most limit. |
has_more | boolean | Yes | More graded holders than limit: page them on GET /api/v1/market/{condition_id}/holders. |
total | integer | Yes | Graded holders in the roster, across every page. |
market | MarketHoldersMarket | Yes | |
scan | MarketHoldersScan | Yes | |
totals | MarketHoldersTotals | Yes | |
category_records_as_of | string | No | When the daily pass behind the rows’ category win records and price edges began: the oldest any row’s record or edge can be. A row recounted since carries its own. Absent when no row of the roster carries a price edge or a hold. |
computed_at | string | Yes | When this roster was computed. A fresh cached roster is at most 60 seconds old; a stale one at most 15 minutes. On as_of=kickoff it is the capture, as_of.captured_at. |
cached | boolean | Yes | true when the roster came from the cache. |
stale | boolean | Yes | true when the market had no fresh roster at the batch deadline and this is the last roster published for it, up to 15 minutes old (read computed_at). The fresh one is still computing, so a read a few seconds later normally gets it; a market refused over the account’s cold-read share is served the same way. |
as_of | HoldersAsOf | No | |
data_quality | DataQuality | No |
GameMap
One map of an esports series.| Field | Type | Required | Description |
|---|---|---|---|
number | integer | Yes | The map’s number in the series, 1 for the first. Polymarket’s breakdown names no map, so the number is its identity. |
state | finished | current | Yes | finished: played to its end. current: the map in play, 0-0 before its first round. |
scores | array of integer | Yes | Each competitor’s score in this map, in competitors order: rounds in CS2 and Valorant, kills in League of Legends and Dota 2. |
results | array of win | loss | No | Each competitor’s result in this map, in competitors order. Kills do not decide a League of Legends or Dota 2 map, so read the winner here, never from scores. Present on a finished map whose winner is known; omitted on the current map. |
GameMapState
The per-map state of an esports series, read from 0xinsider’s stored composition of Polymarket’s per-map breakdown (the GRID data behind Polymarket’s own esports scoreboard), which 0xinsider checks against the series score every 5 to 10 seconds while the series is in play. No provider is read for this response. maps is present only when availability is available; a series with no map reading says why in reason and never carries an empty or guessed list.| Field | Type | Required | Description |
|---|---|---|---|
availability | available | unavailable | not_applicable | Yes | available: maps holds the series’ maps. unavailable: there is no map reading to serve; reason says why. not_applicable: the series has no per-map state to read: it has not started, or it is a single-map series whose map score is the series score. |
reason | not_started | single_map_series | no_map_reading | reading_unavailable | reading_disagrees | sides_unbound | store_unavailable | No | Why maps is absent. not_started: the series has not started. single_map_series: a best-of-1, or a series that ended after one map; competitors[].score is that map’s result. no_map_reading: no per-map reading is stored: most esports series have no per-map breakdown from Polymarket, and a series is read once it is in play. reading_unavailable: Polymarket’s per-map breakdown was absent or could not be read. reading_disagrees: the breakdown trails or runs ahead of the series score, so it is not served. sides_unbound: the reading’s two sides do not match this game’s competitors by provider id. store_unavailable: the stored state could not be read for this response; retry. Omitted when availability is available. |
maps | array of GameMap | No | The series’ maps in order: every finished map, then the map in play. Empty only while no map has finished or started. Present only when availability is available. |
current_map | integer | No | The number of the map in play, the last entry of maps. Omitted when no map is in play: before the series, after it, and while the deciding map has been played but the provider has not yet ended the series. |
quality | full | partial | unavailable | No | How complete the stored score is: full when it parsed and no map reading was unavailable or disagreed with the series score; partial when one was; unavailable when the provider score did not parse. Omitted when no stored score was read. |
observed_at | string | No | When the per-map reading behind this state was taken, never this response’s clock. A later reading that changed nothing does not move it, so a quiet map can show a reading minutes old. Omitted when no reading is stored. |
age_seconds | integer | No | Seconds from observed_at to the response’s as_of, measured as freshness.scores_age_seconds is; 0 when the reading is newer than as_of. Omitted with observed_at. |
GameMarket
One Polymarket market linked to this game.| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The mkt_-prefixed market id every other V1 response uses. |
condition_id | string | Yes | The raw provider condition id. |
protocol_version | v1 | v2 | Yes | The Polymarket protocol the market trades on: v1 (CTF) or v2 (Protocol V2), read from the condition id, as GET /api/v1/games/{event_slug}/markets serves it. On a v2 market each outcome_token_ids entry is a V2 position id. |
copy_event_slug | string | No | The game’s Protocol V2 copy event (polyv2…) this market belongs to, on a market GET /api/v1/games?protocol_version=v2 lists from that copy; GET /api/v1/games/{event_slug}/markets with this slug lists the copy’s other markets. Such a market takes side from the game’s market it copies and carries no prices, liquidity or yes_quote. Omitted on the game’s own markets. |
platform | polymarket | Yes | Always polymarket. |
slug | string | No | The provider’s market slug. Omitted when the provider sent none. |
sports_market_type | string | No | The provider’s own market type, for example moneyline or spread. Omitted when the provider sent none. Not an enum: the provider owns this vocabulary and adds to it. |
side | home | away | draw | other | No | Which side of the game this market’s YES leg pays. home and away are the provider’s own home/away designation of the team the YES leg names (Polymarket’s teams[].ordering), never its place in competitors. Soccer 1X2 legs are explicitly classified as home, draw or away by the provider projection. draw is a real value, not a competitor. Omitted when the provider projection cannot classify the leg or the provider designates neither team home or away, which is not the same as other. |
outcome_yes | string | No | The provider’s label for the YES outcome. Omitted when the provider sent none. |
outcome_no | string | No | The provider’s label for the NO outcome. Omitted when the provider sent none. |
outcome_token_ids | array of string | No | Polymarket CLOB token ids in the provider’s own outcome-index order. Omitted when the provider has published none for this market. |
prices | GameMarketPrices | No | Default provider moneyline state. Omitted when this market has no classified moneyline projection; incomplete and invalid projections remain explicit. |
liquidity | GameMarketLiquidity | No | Polymarket’s reported liquidity for this market. Omitted when the provider read carried none, and on a finished game read from its stored record; never 0 in place of a missing figure. |
settlement | object (expected_settlement_time, observed_at, oracle_status, payouts, proposed_answer, resolved_at, result, settled, settlement_time_basis, status, was_disputed, winning_outcome_index, oracle_updated_at) | No | How Polymarket’s oracle settled or is settling this market, the block GET /api/v1/games/{event_slug}/markets serves, from the same per-game store. Always present on GET /api/v1/games/{event_slug}; on GET /api/v1/games only with expand=settlement. It never waits for Polymarket: a settled market reads its recorded settlement on the first read, and any other market of a game not read lately reads status unavailable while its read starts. |
yes_quote | GameMarketQuote | No | Polymarket’s top of book for this market’s YES outcome (outcome_yes), on traded and untraded markets alike; on a market nobody has traded, where prices reads incomplete, it is the only price the game carries. Omitted when the provider read carried neither a bid nor an ask, and on a finished game read from its stored record. |
GameMarketLiquidity
One market’s liquidity as Polymarket reports it (Gamma liquidityNum), verbatim. Polymarket documents it only as reported market liquidity, with no unit. It describes the market’s resting order book, not traded volume.| Field | Type | Required | Description |
|---|---|---|---|
value | number | Yes | The provider’s figure at full precision. |
source | gamma | Yes | Always gamma: the Polymarket Gamma API. |
observed_at | string | No | When 0xinsider read the sports board body this figure came from, never a provider-authored timestamp. Omitted when that read has no clock. |
GameMarketPriceBindingProvenance
How the existing sports-board writer bound prices to competitors. String enum:provider_ids, exact_labels, containment_labels, elimination.
GameMarketPriceCompetitor
One competitor-bound provider moneyline price. No YES/NO inference is required.| Field | Type | Required | Description |
|---|---|---|---|
provider_id | integer | No | The provider competitor id when identity is available. |
label | string | Yes | The provider competitor label. |
price | number | Yes | Unrounded provider price in [0, 1]. |
price_provenance | gamma_outcome_prices | clob_display | Yes | Which provider price observation supplies this leg. |
GameMarketPriceIncomplete
The provider moneyline pair is incomplete; no numeric pair is invented.| Field | Type | Required | Description |
|---|---|---|---|
state | string | Yes | |
reason | outcome_prices_missing | outcome_price_leg_missing | zero_price_sentinel | display_price_pair_unavailable | outcome_identity_unavailable | final_score_unavailable | Yes | |
competitor_a_is_yes | boolean | No | Whether competitor A is the provider YES leg. |
competitor_a_provider_id | integer | No | The provider competitor id when identity is available. |
competitor_b_provider_id | integer | No | The provider competitor id when identity is available. |
binding_provenance | GameMarketPriceBindingProvenance | No |
GameMarketPriceInvalid
The provider moneyline pair is invalid; no numeric pair is invented.| Field | Type | Required | Description |
|---|---|---|---|
state | string | Yes | |
reason | team_cardinality | outcome_cardinality | price_cardinality | non_finite_price | out_of_range_price | non_complementary_prices | ambiguous_identity | final_identity_mismatch | Yes | |
competitor_a_is_yes | boolean | No | Whether competitor A is the provider YES leg. |
competitor_a_provider_id | integer | No | The provider competitor id when identity is available. |
competitor_b_provider_id | integer | No | The provider competitor id when identity is available. |
binding_provenance | GameMarketPriceBindingProvenance | No |
GameMarketPricePaired
A validated provider moneyline pair bound to the two competitors.| Field | Type | Required | Description |
|---|---|---|---|
state | string | Yes | |
competitor_a | GameMarketPriceCompetitor | Yes | |
competitor_b | GameMarketPriceCompetitor | Yes | |
competitor_a_is_yes | boolean | Yes | Whether competitor A is the provider YES leg. |
binding_provenance | GameMarketPriceBindingProvenance | Yes |
GameMarketPrices
Provider-owned moneyline state with the observation clock that can be compared with game freshness.| Field | Type | Required | Description |
|---|---|---|---|
provider | GameMarketProviderPrices | Yes | |
observed_at | string | null | Yes | Board cache vintage for Gamma or the older CLOB leg clock. Null when no reliable clock is available; never a Gamma-authored timestamp. |
observation_source | board_snapshot | clob_display | Yes | The clock used for observed_at. board_snapshot is this service’s cache observation, not a provider source timestamp. |
GameMarketProviderPrices
One of:GameMarketPricePaired, GameMarketPriceIncomplete, GameMarketPriceInvalid. Discriminated by state.
GameMarketQuote
The YES outcome’s best bid and best ask as Polymarket reports them (Gamma bestBid and bestAsk), verbatim; no midpoint is computed from them. In a binary market the NO outcome’s book mirrors this one (its bid is 1 minus this ask). Per-outcome CLOB books with depth are on GET /api/v1/games/{event_slug}/markets?expand=quotes.| Field | Type | Required | Description |
|---|---|---|---|
best_bid | number | null | Yes | The highest resting bid for the YES outcome, 0 to 1. null when Polymarket reports no bid. |
best_ask | number | null | Yes | The lowest resting ask for the YES outcome, 0 to 1. null when Polymarket reports no ask. |
source | gamma | Yes | Always gamma: the Polymarket Gamma API. |
observed_at | string | No | When 0xinsider read the sports board body this quote came from, never a provider-authored timestamp. Omitted when that read has no clock. |
GameSharpMoney
Event-level sharp money for one game. Every aggregate field is null unless status is computed, except lifecycle and at_kickoff, which describe the game; null means unknown, never zero.| Field | Type | Required | Description |
|---|---|---|---|
allocation | object | Yes | |
computed_at | string | null | Yes | |
event_slug | string | Yes | |
holders_partial | boolean | null | Yes | |
lifecycle | object | Yes | live: before the game started (before its scheduled start and before it was reported live), the only lifecycle whose outcomes carry pct and a leader. in_play: past its scheduled start, or reported live, and not over, a suspended, postponed or cancelled game included; whether the game is being played is status on GET /api/v1/games/{event_slug}. ended: over, markets not settled. settled: resolved; outcomes count the winning side’s wallets that redeemed in profit, the losing side reads 0, so no pct, no leader and a withheld verdict, with the split before the game started in at_kickoff. indeterminate: outcome facts are void, partial or contradictory. |
money_as_of | string | null | Yes | |
object | string | Yes | |
outcomes | array of object (is_leader, label, pct, side, usd, wallets) | Yes | |
status | computed | not_computed | unavailable | Yes | |
total_usd | number | null | Yes | |
trader_count | integer | null | Yes | |
unallocated_usd | number | null | Yes | |
verdict | object | Yes | |
at_kickoff | object | Yes | The split as the site last recorded it before the game started (before its scheduled start and before it was reported live), valued at the prices of that moment, while lifecycle is in_play, ended or settled, so outcomes[].pct keeps meaning now. as_of is when that state was recorded. For a game postponed or cancelled after its scheduled start it is still the split before that time. null on every other lifecycle and when no state with graded money was recorded before the game started. |
since_start | object | Yes | What S, A and B grade wallets bought on a game’s moneyline since its start, by side, in dollars, while lifecycle is in_play. since is the earlier of scheduled_at and the first live score, so a scheduled_at later than the real start does not start the window late. On a 1X2 it has three outcomes and counts buys of each outcome’s YES shares only: a NO buy is money against one outcome, so it is not counted. The verdict is their share alone, no price claim: in play, buys follow the score, so read avg_buy_price. as_of is when the trades were read. A read that found no buy since the start carries bought_usd 0, verdict no_sharp_money and every pct 0. null claims nothing: outside in_play, or with no reading available. |
GameSharpMoneyVerdict
One of: .GameStatus
Where the game is in its own life, as the provider reports it. A postponement, a cancellation and a suspension each keep their own state, so a client can tell a game that will be played later from one that never will be.| Field | Type | Required | Description |
|---|---|---|---|
state | scheduled | live | paused | ended | postponed | cancelled | suspended | delayed | unknown | Yes | scheduled: kickoff is ahead, or the provider still lists the game open and neither in play nor ended. With no live-score frame a game stays scheduled past its kickoff until the provider says otherwise. live: the provider reports it in play. paused: halftime or a provider-reported break. ended: the provider reported a final, an award or a forfeit. postponed, cancelled, suspended, delayed: the provider’s own verdict, kept distinct. A game that the provider still lists in play, with no live score feed and no change of period or score for 3 hours, also reads suspended in tennis, soccer, hockey, basketball, American football, cricket, CS2, Dota 2, League of Legends, Valorant, Mobile Legends: Bang Bang, Rainbow Six Siege, Overwatch and Call of Duty; any other sport keeps the provider’s flag. Outside tennis those 3 hours start no sooner than 2 hours after kickoff (6 for esports), so a game reads suspended only after the longest game measured in its sport; for cricket they start once the match’s scheduled days have passed (5 for a match with a draw market, 1 for a limited-overs match, one fewer when the score shows runs), so a multi-day match stays live overnight. unknown: no provider state reached this read. A kickoff in the past is never read as live on its own. |
match_status | scheduled | in_progress | halftime | penalty_shootout | delayed | suspended | final | final_overtime | final_shootout | awarded | forfeit | not_necessary | postponed | cancelled | unknown | No | The provider status folded onto one vocabulary across leagues. unknown means the provider sent a value this API has no meaning for; provider_status keeps that value verbatim. Omitted when no live-score frame carries a status, as for a listed game no live-score feed has reported yet, and on an ended game whose last status is one the provider sends only before the end (scheduled, in_progress, halftime, penalty_shootout, delayed). |
provider_status | string | No | The live-score feed’s status string, verbatim. Omitted when no live-score frame carries one. This API never puts a label of its own here, such as Scheduled for a listed game. Omitted with match_status on an ended game whose last status is from before the end. |
period | string | No | The period as readers read it, for example Q3, End Q2 or T5: the provider’s period label, except in women’s college basketball (league cwbb), whose feed names its four quarters with the men’s halves vocabulary; there H1, H2 and OT read Q1, Q2 and Q3, and each End frame likewise (End OT reads End Q3, after which the feed sends no frame until the final, so the game is in its 4th quarter at the 3rd quarter’s score). provider_period keeps the provider’s value. Omitted when the provider sent none. |
clock | string | No | The game clock as the provider spells it, never reformatted. Omitted when the provider sent none. |
live | boolean | No | Whether the game is in play. It is the provider’s own in-play flag, except that three cases read false: a game the provider reports suspended (period SUS), a game rescheduled to a later kickoff, and a game that the provider still lists in play with no live score feed and no change of period or score for 3 hours (state names the sports and when those 3 hours start). Omitted when no live-score frame exists, which is not the same as false. |
ended | boolean | Yes | Whether the game is over. Always present. |
ended_at | string | null | Yes | When the game ended (RFC 3339 UTC), as first observed. Always present. It is null unless state is ended and an end was observed. It is never inferred from the kickoff, the clock or the market’s resolution. Null on an ended game means the end time is unknown, and games that ended before this field shipped carry null. ended_at_source names who observed it. |
ended_at_source | object | Yes | Who observed ended_at. Always present, and null exactly when ended_at is null. sports_ws: the first Polymarket Sports WebSocket frame that reported the game final, at the time it was received. gamma_finished: for a game no such frame ended, Polymarket’s own event finish time, served only when it is earlier than the market’s resolution and never for a fight card (MMA, boxing). |
provider_period | string | No | The live-score feed’s period string, verbatim. Omitted when the provider sent none. |
GameTournament
The tennis tournament edition a game belongs to, curated from official ATP, WTA and ITF pages (source_urls), never from Polymarket, which supplies the competition label and tour only. Selected by the game’s provider competition label, the one tour both players carry, and the kickoff’s day at the venue. A fact no official page states is omitted.| Field | Type | Required | Description |
|---|---|---|---|
label | string | Yes | The provider competition label that selected this edition, verbatim, for example “Erste Bank Open, Qualification”. |
tour | atp | wta | itf | Yes | The edition’s tour. |
draw | main | qualification | No | The match’s draw. qualification when the provider competition label carries Polymarket’s qualifying mark (”, Qualification”, which 0xinsider also applies when Polymarket flags an ATP Challenger qualifying fixture); main for an unmarked ATP or WTA label. Omitted for an unmarked ITF label: Polymarket gives an ITF qualifying match the main draw’s label. |
tier | string | No | The edition’s verified category, for example “ATP Masters 1000”, “ATP Challenger 50”, “WTA 1000” or “ITF M25”. Omitted when no official page states it. |
location | GameTournamentLocation | No | The verified venue city and country. Omitted when no official page states it. |
timezone | string | No | The venue’s IANA time zone, for example “Europe/Rome”. Format the venue’s local time with it; it carries the daylight-saving rules. Omitted when the venue is unverified. |
edition_year | integer | Yes | The year of the edition. |
starts_on | string | Yes | The edition’s first official day, inclusive (YYYY-MM-DD). A qualifying match can be played up to two days before it. |
ends_on | string | Yes | The edition’s last official day, inclusive (YYYY-MM-DD). |
source_urls | array of string | Yes | The official tournament, tour, federation or time-zone pages the facts were taken from. |
checked_on | string | Yes | When those pages were checked: a catalogue verification date, not a score or price clock. |
GameTournamentLocation
A verified tournament venue.| Field | Type | Required | Description |
|---|---|---|---|
city | string | Yes | |
country | string | Yes | |
country_code | string | Yes | ISO 3166-1 alpha-2, for example “IT”. |
GameTrade
One fill in a game, as the game page’s activity list shows it.| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Stable fill identity: {transaction_hash}:{token_id}:{wallet}:{shares}. Deduplicate on it across polls. |
traded_at | string | Yes | When the fill happened, to the second. |
side | BUY | SELL | Yes | The provider’s side of the fill. |
outcome | string | null | Yes | The traded outcome’s label; null when the provider named none. |
outcome_index | integer | null | Yes | 0 for the first (Yes) outcome token, 1 for the second (No); null when the provider did not say. |
price | number | Yes | Fill price, 0 to 1. |
shares | number | Yes | Shares filled. |
size_usd | number | Yes | USDC notional of the fill. |
point | number | null | Yes | The signed handicap the fill’s side carries on a spread line, for example -1.5 or 1.5; null off spreads. |
trader | object (address, display_name, grade) | Yes | |
market | object (id, condition_id, title, slug, line_label) | Yes |
GameVolume
A game’s traded volume as Polymarket reports it, read by the sports board or, for a game read from its stored record, summed from its markets’ stored volumes, with no request-time provider call. A one-side taker share count, the number Polymarket’s own pages print behind a dollar sign, not the cash that changed hands.| Field | Type | Required | Description |
|---|---|---|---|
value | number | Yes | The volume at full precision, in unit. |
unit | taker_shares | No | taker_shares: cumulative one-side taker volume in shares. One share pays $1 at settlement, so this is not cash traded. Omitted only on a figure observed before units were recorded; never assume cash. |
basis | game_lines | event_total | No | game_lines: the game volume Polymarket’s game page states, summed over the game’s own lines. event_total: the whole event’s volume, stated when no game volume was readable. The two can differ in either direction. Omitted when the basis is unknown. |
source | polymarket_data | gamma | Yes | The Polymarket API the figure was read from: polymarket_data (the Data API’s live volume) or gamma (the Gamma API). |
observed_at | string | No | When 0xinsider read the figure from the provider, never a provider-authored timestamp. Omitted when no read time is held for it. |
fresh_for_seconds | integer | Yes | How long after observed_at 0xinsider treats the figure as current: 60 or 300 by source and basis, or 3600 for an older figure kept because a later read of the same total was lower or missing (a cumulative volume never falls). |
GamesCoverage
What this deployment covers, published with every page so a client never has to guess whether an empty list means no games or no coverage.| Field | Type | Required | Description |
|---|---|---|---|
sports | array of string | Yes | Canonical sport buckets served, sorted. |
leagues | array of string | Yes | League tags served, sorted. EuroLeague is euroleague, NCAA men’s college basketball cbb and NCAA women’s college basketball cwbb, all under the Basketball sport bucket. |
sources_unavailable | array of string | Yes | Scopes whose source half was unavailable for this read, as <sport>:<half>. Empty means every scope answered. |
HolderCategoryEvidence
Current category evidence, independent of the global grade. Pick of the Day stamps only the served display roster; frozen entry snapshots remain unchanged.| Field | Type | Required | Description |
|---|---|---|---|
status | live | insufficient | stale | unknown | degraded | Yes | |
canonical_category | string | No | |
skill | CategorySkillV2 | No |
HoldersAsOf
The instant a stored kickoff roster stands at, with each of its clocks (#34064). Present only on as_of=kickoff; every clock is before kickoff_at.| Field | Type | Required | Description |
|---|---|---|---|
basis | kickoff | Yes | Always kickoff. |
captured_at | string | Yes | When the roster was computed and stored. Its grades, badges and category records were read at this instant. |
kickoff_at | string | Yes | The kickoff the roster stands at: the market’s scheduled game start when the roster was stored, or its start now when that moved earlier since. A game moved to a later start is captured again for the new one. |
population_fetched_at | string | Yes | When the provider holder walk behind the holders and their shares finished, the same instant as scan.fetched_at. It can be up to about 4 hours before kickoff. |
population_source | snapshot | census | Yes | snapshot: a complete holder walk, with the provider’s display names. census: the pregame census, which keeps no names, so every holder’s name is null. |
population_started_at | string | null | Yes | When that walk started; null when its copy did not record it. |
LargeExportPolicy
| Field | Type | Required | Description |
|---|---|---|---|
mode | string | Yes | |
current_internal_route | string | Yes | |
v1_async | object (submit_route, status_route, download_route, cancel_route, formats, status_values, retention) | Yes | Programmatic API-key-gated export routes (submit/status/download/cancel) and supported formats (json, ndjson, csv). |
direct_streaming | object (available_when, backpressure, chunk_size_rows) | Yes | |
async_job | object (available_when, status_values, retention) | Yes | |
rate_limit | object (daily_cap_per_user, per_address_hourly_cap) | Yes |
LargePosition
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Composite prefixed ID pos_<wallet>:<condition_id>:<outcome_index>. |
platform | polymarket | Yes | Provider discriminator. Always polymarket. |
total_size_usd | number | No | Provider currentValue in USD for the outcome named by outcome_label / token_id, and for that outcome only. An absent key means the provider supplied no value for this leg, not a zero position. combined_value_usd carries the wallet’s whole-market total. |
position_unrealized_pnl | number | No | Provider unrealized mark-to-market P&L (Polymarket cashPnl) for that same one outcome. An absent key means unavailable, not break-even. |
combined_value_usd | number | No | The wallet’s currentValue across every outcome it holds in this market. Equals total_size_usd unless is_two_sided is true, and is the value the feed ranked this row by. |
combined_unrealized_pnl | number | No | The wallet’s unrealized P&L across every outcome it holds in this market. Equals position_unrealized_pnl unless is_two_sided is true. |
is_two_sided | boolean | Yes | Whether the wallet holds shares on both outcomes of this market. |
holdings | array of object (outcome_index, outcome_label, token_id, share_count, avg_entry_price, current_price, value_usd, unrealized_pnl) | Yes | Every outcome the wallet holds, primary first. holdings[0] restates the top-level per-outcome fields; a further entry is a leg those fields do not describe. No amount here is a share-proportional slice of a both-sides total. |
share_count | number | Yes | Live share count for this position. |
avg_entry_price | number | No | Volume-weighted entry price. |
current_price | number | No | Latest provider mark price for the position’s token. |
outcome_label | string | No | Backend-resolved outcome label (provider outcome, else Yes/No from the binary index). |
token_id | string | null | Yes | The Polymarket CLOB token id (ERC1155 asset id, decimal string) for this outcome; null when unavailable (e.g. unsynced markets). |
event_leg_count | integer | Yes | Legs collapsed into this representative row for one (wallet, event, outcome side) group. 1 means standalone. |
event_total_value_usd | number | No | Sum of the collapsed sibling legs’ own holding values for this (wallet, event) group; equals total_size_usd when event_leg_count = 1, and omitted when any member’s value is unknown. |
first_seen_at | string | Yes | |
last_updated_at | string | Yes | |
trader | object (id, address, username, grade, win_rate, pnl, in_scope_realized_pnl, markets_traded) | Yes | |
market | object (id, condition_id, title, slug, event_slug, category, protocol_version) | Yes |
LargePositionsUpdatedData
large_positions_updated data: one large-positions refresh finished.
| Field | Type | Required | Description |
|---|---|---|---|
count | integer | Yes | Positions the refresh published. |
LargeTrade
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Prefixed ID (wt_…). |
traded_at | string | Yes | |
size_usd | number | Yes | |
side | BUY | SELL | Yes | |
outcome | string | null | Yes | Traded outcome label (e.g. “Yes”/“No”/team name), resolved provider-first from the trade’s outcome_index against market_canonical (index 0 -> yes, 1 -> no). Distinct axis from side (BUY/SELL): side is the trade direction, outcome is which leg was traded. null for multi-outcome (outcome_index >= 2) or unsynced markets, and for a Polymarket trade recorded before 2026-04-02T00:00:00Z unless its stored outcome_index was verified against the fill’s own trade records (before that date the stored index was wrong for a large share of trades; an unverified side is unknown, not defaulted). |
token_id | string | null | Yes | The Polymarket CLOB token id (ERC1155 asset id, decimal string) for the traded outcome; null when unavailable (e.g. unsynced markets) and for a Polymarket trade recorded before 2026-04-02T00:00:00Z whose traded side is not verified (the same rule as outcome). |
price | number | Yes | |
review_score | number | Yes | Current trade review score on a 0..1 scale; higher values indicate a stronger review signal. This is the current response value and can differ from the recorded score. Missing measurements remain unavailable. |
signal_score | number | Yes | Deprecated alias of review_score with the same current value and 0..1 scale. Sunset 2027-02-01 (#29352): removed from V1 on that date; read review_score. |
recorded_review_score | number | null | Yes | 0.0–1.0 review score written once when the trade row is inserted, from the trader’s statistics at that moment. Populated from 2026-08-03T11:59Z; older rows return null and are never backfilled, because a backfill could only read today’s statistics. If a trade is added later, its time-sensitive recorded score reflects that delay. Canonical since #16311; recorded_signal_score carries the same value. |
recorded_signal_score | number | null | Yes | 0.0–1.0 review score written once when the trade row is inserted; null before 2026-08-03T11:59Z. Deprecated (#16311): recorded_review_score is the canonical spelling and carries the same value; this key stays on the wire until its sunset on 2027-02-01 (#29352), when it is removed. |
suspicion_score | integer | null | Yes | Persisted live suspicion score from the scorer. Null when the row has no persisted score. |
suspicion_track | whale | fresh_conviction | sliced_position | null | Yes | Persisted scorer track. Null when a legacy row has no stored track label. |
market_volume_share | number | No | This fill’s size relative to its market: its share count (size_usd / price) divided by the shares the market has traded, Polymarket’s recorded volume, which counts shares rather than dollars, as observed at or after the trade, so the value always falls between 0 and 1 inclusive. A 20,000-share fill is 0.00005 of a market that has traded 400M shares and 0.125 of one that has traded 160,000, which size_usd alone cannot distinguish. Absent when no volume figure recorded at or after the trade is available, or when that figure is smaller than the fill; never 0 as a stand-in and never capped at 1, because a denominator we cannot trust publishes nothing rather than a trimmed number. A market’s volume keeps growing, so the same trade reports a smaller share as the market trades on. |
trader | object (id, address, username, grade, grade_at_trade, grade_at_trade_status, first_trade_at, is_new_wallet) | Yes | |
market | object (id, condition_id, title, slug, category, protocol_version) | Yes | |
clv | object (basis_version, close_anchor_at, close_price, clv_cents, pre_kickoff, status, unavailable_reason, clv_after_fees_cents, taker_fee_cents) | Yes | Closing line value against the market’s stored close (GET /api/v1/market/{condition_id}/close). Always present; status says whether it is measured. |
LargeTradeDetail
No documented fields.LargeTradeHistoryMeta
| Field | Type | Required | Description |
|---|---|---|---|
request_id | string | Yes | Unique request ID (req_ prefix). The same value as the X-Request-Id response header, the request’s usage accounting row and its log lines. |
cached | boolean | Yes | |
cache_age_s | integer | No | Cache age in seconds; the key is absent when the response was not cached. |
source | object (kind, table, provider_fetch_at_request_time) | Yes | |
completeness | object (status, reason) | Yes |
LargeTradeInsertedV2Data
large_trade_inserted_v2 data (Pro and Max): one large trade, with the trade itself. The three amounts are decimal strings that keep the stored precision: parse them with a decimal library when the exact value matters. The endpoint’s trade_filters decide which trades it receives.
| Field | Type | Required | Description |
|---|---|---|---|
event_id | string | Yes | Stable identity of this trade’s event. It equals the envelope id, and the id of the same event on GET /api/v1/events/feed/since. |
whale_alert_id | integer | Yes | Numeric id of the trade. GET /api/v1/large-trades/{id} accepts it. |
condition_id | string | Yes | Polymarket condition id of the market. |
trader_id | integer | Yes | 0xinsider’s numeric id for the wallet. |
wallet | string | Yes | Address of the wallet that made the trade. |
grade | S | A | B | C | D | F | null | Yes | The wallet’s grade when the event was published; null when it has none. A backfilled trade publishes hours after it filled, so this can differ from grade_at_trade. min_grade filters on this field; min_grade_at_trade filters on grade_at_trade. |
size_usd | string | Yes | USD notional of the trade; decimal string. |
shares | string | Yes | Shares traded; decimal string. |
price | string | Yes | Price paid per share; decimal string. |
side | BUY | SELL | Yes | |
outcome_index | integer | Yes | Polymarket’s index of the outcome traded. |
traded_at | string | Yes | When the trade filled on Polymarket. The envelope’s created_at is this instant. |
platform | string | Yes | |
grade_at_trade | object | No | The grade the wallet held when the trade filled, the same fact as trader.grade_at_trade on GET /api/v1/large-trades; null unless grade_at_trade_status is graded. min_grade_at_trade filters on it. |
grade_at_trade_status | graded | ungraded | unknown | No | graded when grade_at_trade holds the grade at the fill; ungraded when the wallet had no grade then; unknown when it cannot be known, for a trade before 2026-09-19 23:00 UTC or while a grade change is unconfirmed. Only graded trades match min_grade_at_trade. An event published before these fields shipped (November 2026), or a redelivery of one, carries neither. |
LargeTradeSubscriptionFilters
All present fields narrow large_trade_inserted_v2 delivery. min_grade reads the payload’s grade, observed at publication; min_grade_at_trade reads its grade_at_trade, the grade when the trade filled. Send one of the two, not both (400). An empty object matches every large trade.| Field | Type | Required | Description |
|---|---|---|---|
condition_id | string | No | Raw provider condition ID or mkt_-prefixed market ID. |
wallet | string | No | Polymarket wallet address; matching is case-insensitive. |
min_grade | S | A | B | C | D | F | No | S is best; ungraded trades do not match. Reads the wallet’s grade when the trade was published, which for a backfilled trade can be hours after the fill. |
min_grade_at_trade | S | A | B | C | D | F | No | S is best. Reads grade_at_trade, the grade the trader held when the trade filled; only a trade whose grade_at_trade_status is graded matches. The same basis as min_grade_at_trade on GET /api/v1/large-trades and GET /api/v1/stream. |
min_size_usd | string | No | Positive USD notional as an exact decimal string. |
LargeTradesInsertedData
large_trades_inserted data (Pro and Max): new large trades were ingested. It carries a count and no trade; subscribe to large_trade_inserted_v2 for the trade itself. The deprecated spelling whale_trades_inserted delivers the same object until its sunset on 2027-02-01 (#29352).
| Field | Type | Required | Description |
|---|---|---|---|
count | integer | Yes | Large trades the producing batch admitted. |
LeaderboardEntry
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | |
address | string | Yes | |
username | string | No | |
grade | S | A | B | C | D | F | No | |
streak_tier | hot | rising | neutral | cooling | cold | No | Hot-streak tier (trailing-7d cross-sectional percentile); a separate axis from the all-time grade. Omitted when there is no recent activity. |
score | number | No | |
pnl | number | No | Deprecated since 2026-10-27 and never sent. It was Polymarket’s all-time leaderboard P&L, which covered every Polymarket market of the wallet, and wallet figures cover sports and esports markets only (#29971). Read in_scope.realized_pnl. |
realized_pnl | number | No | Deprecated since 2026-10-27 and never sent. It was native Polymarket realized P&L over every Polymarket market of the wallet, and wallet figures cover sports and esports markets only (#29971). Read in_scope.realized_pnl. |
pnl_correction | PnlCorrection | No | Deprecated since 2026-10-27 and never sent. It was the neg-risk conversion correction to the wallet-wide realized_pnl (#29971). Its sports and esports part is inside in_scope.realized_pnl. |
volume | number | No | Deprecated since 2026-10-27 and never sent. It was full-history USD cash volume over every Polymarket market of the wallet, and wallet figures cover sports and esports markets only (#29971). |
markets_traded | integer | No | Sports and esports markets on the wallet’s record, the same count as in_scope.markets. Since 2026-10-27 (#29971); before, it counted every Polymarket market. Sent exactly when in_scope is. |
win_rate | number | No | The wallet’s sports and esports win rate, in_scope.win_rate rounded to four places. Since 2026-10-27 (#29971); before, it covered every Polymarket market. ?category= decides WHICH wallets are listed (the wallet must be ranked in that category); it does not rescope this field. For a per-category record use GET /api/v1/trader/{address}/categories. Omitted when in_scope is omitted or has no win rate. |
in_scope | TraderPnlInScope | No | Additive (#27859): the wallet’s sports and esports record, the same object as GET /api/v1/trader/{address} pnl.in_scope, as of the leaderboard’s last refresh. The 0xinsider leaderboard page shows and sorts by in_scope.realized_pnl and in_scope.win_rate. Omitted until 0xinsider has computed the wallet’s record; absent means not computed yet, never zero. |
price_edge | LeaderboardPriceEdge | No | Additive (#32270): the wallet’s edge over the price paid on its sports and esports markets, the figures the 0xinsider leaderboard page’s Edge column states for the row. sort=edge orders by price_edge.edge. Omitted when the wallet has no settled sports or esports market of $20 or more at a known entry price. |
strategy_type | string | No | Observed trading style identifier. New rows use two_sided, category_focused, high_activity, diversified, mixed, or unclassified, counted over the wallet’s sports and esports markets only. Historical identifiers remain readable during normal reclassification; style does not predict skill or intent. |
platform | polymarket | Yes | Provider platform. Always polymarket. |
last_active | string | No | When the wallet last traded: its most recent recorded trade, as of the leaderboard row’s last refresh, which re-reads it hourly, so a new trade can take about an hour to show. It agrees with the activity filter: every wallet listed under activity=inactive last traded more than 30 days ago. Since 2026-11-02 (#32322); before, it carried the time 0xinsider last synced the wallet, usually within the past week whether or not the wallet traded. Omitted when the wallet has no recorded trade. |
win_rate_status | measured | not_enough_data | No | Additive (since 2026-11-11, #34333): in_scope.win_rate_status, lifted to the row beside win_rate. measured from 5 decided markets (in_scope.markets_decided), not_enough_data below, the floor the 0xinsider leaderboard page applies before it shows a win rate. Below it win_rate is still sent; quote in_scope.markets_decided instead of win_rate as a rate. Omitted exactly when in_scope.win_rate_status is. |
LeaderboardLeagues
Every league with a skill leaderboard, by sport: the league values GET /api/v1/leaderboard/sports/{sport} accepts.| Field | Type | Required | Description |
|---|---|---|---|
leagues | array of object (category, name, ranked_traders, slug, sport, total_traders) | Yes | Grouped by sport, then most ranked wallets first. |
min_ranked | integer | Yes | Wallets a league board’s edge sort must rank, with no hold, for the league to be listed. |
min_resolved | integer | Yes | Settled markets of $20 or more a wallet needs in a league to be on its board. |
refreshed_at | string | Yes | When the league ranking last ran. It runs about once a day. |
LeaderboardPriceEdge
Edge over the price paid (#32270): how often the side a wallet bought won, minus the average price it paid, over its settled sports and esports markets of $20 or more at a known entry price. Probabilities throughout: edge 0.12 is 12 percentage points. A wallet buying at 99 cents that wins every market has an edge of about 0.01. A market bought on both sides counts by its shares: the winning side’s share of the shares bought is its hit, the cost over those shares its price.| Field | Type | Required | Description |
|---|---|---|---|
markets | integer | Yes | Settled sports and esports markets of $20 or more at a known entry price that the edge is measured over. |
hit_rate | number | Yes | Share of those markets whose bought side won, 0-1. |
avg_price | number | Yes | Mean entry price paid, 0-1. |
edge | number | Yes | hit_rate minus avg_price, full precision. The value sort=edge orders by. |
status | ranked | too_few_markets | sample_mismatch | Yes | Whether the edge ranks. ranked: at least 30 such markets, and the share of the decided ones that made money at settlement within 10 points of the win rate over the same markets. too_few_markets: fewer than 30. sample_mismatch: that share is more than 10 points away, so these markets do not describe the wallet’s record. Only a ranked edge with no hold orders on sort=edge. |
hold | record_incomplete | No | Why the leaderboard does not rank a ranked edge. record_incomplete: the wallet’s stored sports and esports record shows more profit than Polymarket reports for it, so some losing markets are likely missing. Omitted when nothing holds the edge, and always omitted unless status is ranked. |
LeaderboardSummary
The whole board’s totals, the counts the 0xinsider leaderboard page shows (#32737), read with the ranking snapshot the page is served at. Sent on every page of a request with no category and no strategy, whatever its sort, dir and activity, which order or split the same wallets. Omitted on a category or strategy page, which lists a subset these totals do not describe, and while the ranking has no totals for the served generation.| Field | Type | Required | Description |
|---|---|---|---|
ranked_total | integer | Yes | Ranked wallets on the board: the wallets the unfiltered list pages through. |
by_grade | object (S, A, B) | Yes | Ranked wallets by grade. Every ranked wallet is graded S, A or B, so the three sum to ranked_total. |
active_30d | integer | Yes | Ranked wallets whose last trade was 30 days or less before as_of: the wallets activity=active lists. ranked_total minus active_30d is the activity=inactive count. |
as_of | string | Yes | When the totals were counted, UTC. They are recounted about once a minute while the ranking is current. |
LiveSportsScoreEntry
One side’s score line inside alive_sports_updated pulse.
| Field | Type | Required | Description |
|---|---|---|---|
team | string | Yes | Team name, ordered for the league (away first where the league reads that way). |
score | string | Yes | This side’s score as the provider sends it. |
map_score | string | No | Esports series only: this side’s current-map score. Absent on other sports. |
LiveSportsUpdatedData
live_sports_updated data: one bounded pulse for one live game. A pulse fires when a material field moved since this game’s previous delivered pulse (scores, status, period, live, ended), at most once per game per 20 seconds. A live or ended transition is exempt from that interval, and the game clock alone never fires a pulse. Suppressed frames are folded into the next pulse’s changed, and its body carries the current state.
| Field | Type | Required | Description |
|---|---|---|---|
event_slug | string | Yes | The Polymarket event slug this game trades under. |
game_id | string | null | Yes | Provider game id, or null when the frame carried none. |
league | string | null | Yes | League abbreviation, or null. |
version | integer | Yes | Durable per-game pulse ordinal, increasing by one per delivered pulse. Deliveries are not ordered, so drop a pulse whose version you already saw. |
changed | array of scores | status | period | live | ended | Yes | Material fields that moved since this game’s previous delivered pulse. |
observed_at | string | null | Yes | Provider frame time, or null when the frame carried none. Never replaced with a local clock. |
published_at | string | Yes | When the pulse was admitted. |
status | string | null | Yes | Provider status text, or null. |
period | string | null | Yes | Provider period text (“Q3”, “Map 2/3”), or null. |
clock | string | null | Yes | Game clock, or null. Not a material field: it never fires a pulse on its own. |
live | boolean | null | Yes | Provider live flag, or null when the frame carried none. |
ended | boolean | Yes | Whether the provider has marked this game final. |
scores | array of LiveSportsScoreEntry | Yes | Per-side scores, one line per team. |
series_format | string | null | Yes | Esports BoN series token, or null on every other sport. |
snapshot_url | string | Yes | Public game page. Re-read it after a gap instead of replaying pulses. |
MarketCandles
Provider-first bucketed OHLC price candles for a market’s outcome tokens (open and resolved markets): 5m and 1h from Polymarket’s /v2/prices-history buckets, 1d and 1w from our stored copy of its price history.| Field | Type | Required | Description |
|---|---|---|---|
condition_id | string | Yes | Market condition id the candles were read for. |
resolution | 5m | 1h | 1d | 1w | Yes | Bucketing granularity that produced these candles. |
window_start | integer | No | 5m and 1h only: the first bucket start the read covers, unix seconds. Every candle has t at or after it. |
window_end | integer | No | 5m and 1h only: the end of the covered window, unix seconds, exclusive. Every candle has t before it. A bucket inside the window with no candle had no Polymarket price; nothing is filled in. |
observed_at | string | No | 5m and 1h only: when Polymarket’s series was read. A window that reaches the present, or holds a provisional_minutes candle, is re-read after at most 60 seconds. |
outcomes | array of OutcomeCandles | Yes | One entry per present provider token (YES first, then NO); empty when no tokens have been fetched yet. |
protocol_version | v1 | v2 | Yes | The Polymarket protocol the market trades on, Gamma’s market version: v1 (CTF, ConditionalTokens) or v2 (Protocol V2). Read from the condition id, the same value GET /api/v1/markets/settled serves. On a v2 market an outcome’s token_id is its V2 position id: sign its orders for ExchangeV3 and read its balance as CONDITIONAL-V2. |
MarketClose
A market’s stored closing line (#32517): Polymarket’s price-history value for the last minute bucket ending at or before kickoff, read once after settlement and never recomputed.| Field | Type | Required | Description |
|---|---|---|---|
anchor_stale | boolean | null | Yes | true when game_start_time has moved more than lookback_seconds from close_anchor_at since capture; large trades on the market then carry no CLV. null without a stored row. |
basis_version | string | null | Yes | Provider response contract version the value was read under. |
captured_at | string | null | Yes | When the close was stored. Bookkeeping only. |
close_anchor_at | string | null | Yes | The instant the close was measured at: the kickoff when it was captured. Write-once; null when no close row is stored. |
close_anchor_source | string | null | Yes | The field that supplied close_anchor_at, markets.game_start_time. |
condition_id | string | Yes | Polymarket condition id. |
game_start_time | string | null | Yes | The market’s kickoff as stored now. |
lookback_seconds | integer | null | Yes | How far before the anchor the admitted bucket may start: 21600 (6 hours). |
observation_window_seconds | integer | null | Yes | Bucket width: 60 (minute grain) or 3600 (hour grain, for a market read more than about six days after kickoff). |
observed_at | string | null | Yes | Start of the provider bucket the close is. The bucket ends at observed_at + observation_window_seconds, at or before close_anchor_at. |
outcomes | array of object (close_price, derived_from_yes, outcome, outcome_index, token_id) | Yes | YES then NO when status is measured; empty otherwise. |
price_source | string | null | Yes | Provider endpoint and grain, e.g. polymarket_data_v2_prices_history@minute-window-v1. |
status | measured | pending | unavailable | Yes | measured: outcomes carries the close. pending: no close is stored yet and the capture will still read the market. unavailable: no close will be served; see unavailable_reason. |
unavailable_reason | object | Yes | Set exactly when status is unavailable. no_observation_in_lookback, provider_empty_window, provider_invalid_contract and capture_window_closed are the capture’s own stored refusals; no_game_start_time: the market has no kickoff time; not_one_sided_resolution: it resolved to neither side; not_captured: the capture does not read it (kickoff over 30 days ago; a market that is not a moneyline and had no tracked buy before resolution; or a moneyline whose game started before the capture began reading every moneyline); close_token_mismatch: the close was read on a different YES token than the market carries now. |
protocol_version | v1 | v2 | Yes | The Polymarket protocol the market trades on, Gamma’s market version: v1 (CTF, ConditionalTokens) or v2 (Protocol V2). Read from the condition id, the same value GET /api/v1/markets/settled serves. On a v2 market an outcome’s token_id is its V2 position id: sign its orders for ExchangeV3 and read its balance as CONDITIONAL-V2. |
MarketFlow
| Field | Type | Required | Description |
|---|---|---|---|
market | object (id, condition_id, title, slug, category, platform, protocol_version) | Yes | |
sharp_money | MarketFlowSharpMoney | Yes | Outcome-aware flow from all tracked whale trades in the window, without a grade filter. BUY YES and SELL NO add net exposure; BUY NO and SELL YES subtract it. Gross buy/sell volumes count both outcomes. Top positions are separately graded. Direction uses unrounded net: negative is NO, otherwise YES; the zero tie-break is not conviction. Canonical; smart_money is a deprecated byte-identical alias. |
smart_money | MarketFlowSharpMoney | Yes | Deprecated alias of sharp_money; byte-identical. Sunset 2027-02-01 (#29352): removed from V1 on that date; read sharp_money. |
timeframe | string | Yes |
MarketFlowSharpMoney
One market’s outcome-aware large-trade flow in the window and its top graded positions: the shape of MarketFlow’s sharp_money and of its deprecated alias smart_money.| Field | Type | Required | Description |
|---|---|---|---|
net_flow_usd | number | Yes | |
direction | YES | NO | Yes | |
token_id | string | null | Yes | The Polymarket CLOB token id (ERC1155 asset id, decimal string) for the net-flow direction outcome; null when unavailable (e.g. unsynced markets). |
large_trade_count | integer | Yes | Canonical key since #16304 (Polymarket’s noun is large trade); whale_trade_count is its deprecated spelling, emitted beside it with the same value until its sunset on 2027-02-01 (#29352). |
whale_trade_count | integer | Yes | Deprecated spelling of large_trade_count, emitted beside it with the same value. Sunset 2027-02-01 (#29352): removed from V1 on that date; read large_trade_count. |
buy_volume_usd | number | Yes | |
sell_volume_usd | number | Yes | |
top_positions | array of object (id, address, username, grade, side, token_id, size_usd) | Yes | |
oldest_snapshot_as_of | string | null | Yes | Age of the oldest stored position snapshot behind top_positions: the minimum wallet sync clock over the positions this body publishes. The roster is a stored read rather than a live one, and graded wallets sit on different sync tiers, so this names how current the whole roster is; the response is no fresher than this timestamp. Null when the roster is empty or no published position carries a sync clock. It does not date net_flow_usd, the volumes or the trade counts, which come from large-trade event times. |
MarketHolder
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Composite pos_<wallet>:<condition_id>:<outcome_index>, the same id GET /api/v1/positions gives this leg. |
trader_id | string | Yes | trd_-prefixed trader id, accepted by GET /api/v1/trader/{address}. |
address | string | Yes | Lowercased proxy wallet. |
name | string | null | Yes | Polymarket’s public display name from the same holder snapshot; null for a private wallet, which the provider redacts at the source. |
side | YES | NO | Yes | The outcome this wallet nets to. A wallet holding both outcomes is listed once, on its net side; see other_outcome_shares. |
token_id | string | null | Yes | Polymarket CLOB token id (ERC1155 asset id, decimal string) for side; null when the market has no stored token id. |
grade | S | A | B | null | Yes | All-time trader grade. This route lists the S/A/B cohort only, the same cohort a Pick of the Day roster lists. |
shares | number | Yes | Net shares on side, from the complete provider scan. For a wallet holding both outcomes, its shares on side minus other_outcome_shares. |
current_value_usd | number | null | Yes | What shares is worth, in USD: Polymarket’s own currentValue for this leg. For a wallet holding both outcomes it is scaled to the net shares, at Polymarket’s per-share value for the same position, so it never exceeds shares. Null when the snapshot predates the value map. |
other_outcome_shares | number | No | Shares on the other outcome when the wallet holds both. Absent when the wallet is one-sided. |
last_traded_at | string | null | Yes | The wallet’s last recorded trade anywhere, null when unknown. |
category_win_rate | number | No | This wallet’s win rate in the market’s canonical category (market.category): the share of its settled markets in that category (it closed its position by selling out, or the market resolved) whose realized P&L closed positive, as a 0..1 fraction. Present only with category_win_rate_status = measured. The same read GET /api/v1/trader/{address}/categories serves per wallet. |
category_win_record | object (wins, decided) | No | The two counts category_win_rate is the ratio of, from the same row: wins / decided equals the rate. Every settled Polymarket market the wallet traded (it closed its position by selling out, or the market resolved) in the market’s canonical category, at any position size, rebuilt daily. Present only with category_win_rate_status = measured. |
category_avg_price | number | No | The wallet’s average entry price in the market’s canonical category, as a 0..1 fraction of $1 (0.98 is 98 cents). Its sample is the wallet's markets in that category that resolved to a winning side, of $20 or more where it bought one side at a known price, so it can differ from the category_win_record sample. A wallet that buys near-certain outcomes wins almost every time, so read the win rate beside this price. Present only with category_win_rate_status = measured, and only when that sample has at least 5 markets. When category_win_rate_game is present the price is still the whole category bucket’s: this field has no per-game or per-league price. Absent otherwise and on payloads predating the field. |
category_win_rate_game | string | No | Where category_win_rate and category_win_record were measured: for an esports market the game (LoL, CS2, Dota 2, Valorant, Call of Duty, Honor of Kings, Mobile Legends: Bang Bang, Overwatch, Rainbow Six Siege, Rocket League or StarCraft II), and for a market in a registered league that league, by the name Pick of the Day uses for it (NBA, NFL, NHL, MLB, UFC, ATP, WTA, LaLiga, Premier League, Serie A, UEFA Champions League, MLS and the other registered leagues). Present only when the wallet’s record there clears the 5-settled-market floor, in which case the rate and record are the game’s or league’s rather than the whole category bucket’s. Absent when the rate is the bucket’s (the wallet’s history there is under the floor, or the competition is not a registered league), on every other market, and beside every non-measured status. Label the rate with this when present and with the market’s category otherwise. |
category_win_rate_status | measured | not_enough_data | unavailable | untracked | Yes | Why category_win_rate is present or absent: measured (rate present), not_enough_data (under the floor of 5 decided markets in the category), or unavailable (the market has no canonical category, or the read failed; retry later). Never untracked: this route lists S, A and B wallets only, all on file. Always present on this route. |
category_price_edge | PickHolderPriceEdge | No | The wallet’s edge over the price it paid in the market’s canonical category (market.category), the figure the event page’s Top holders row and GET /api/v1/market/{condition_id}/top-holders print for this wallet, from the same read and rule: how often the side it bought won, minus the average price it paid, over its settled markets there at a known entry price (every_size). Probabilities, not percentages: edge 0.022 is +2.2 pp. The page’s 95% range is 1.96 * sqrt(avg_price * (1 - avg_price) / markets) either side of edge, and the page names an edge only when that range is all on one side of zero. Not category_win_rate minus category_avg_price: the edge counts its own sample. As of the row’s category_records_as_of, or the payload’s when the row has none. Present only with category_win_rate_status = measured when the page shows the edge; otherwise, beside a measured rate, category_price_edge_hold says why. |
category_scope_price_edge | PickHolderPriceEdge | No | The same edge over the markets of the game or league category_win_rate_game names alone. Present only beside category_win_rate_game; otherwise, beside a game or league rate, category_scope_price_edge_hold says why. Never the whole category’s edge in its place. |
category_price_edge_hold | PickHolderPriceEdgeHold | No | Why there is no category_price_edge for a wallet with a measured rate, with the rule’s figures when it has them: the reason the page prints in place of the edge. Present only with category_win_rate_status = measured, and never beside category_price_edge. |
category_scope_price_edge_hold | PickHolderPriceEdgeHold | No | Why there is no category_scope_price_edge beside a game or league rate, with the rule’s figures when it has them. Present only beside category_win_rate_game, and never beside category_scope_price_edge. |
category_records_as_of | string | No | When this wallet’s category record was recounted, sent only when that is later than the payload’s category_records_as_of: a wallet’s record is also recounted about an hour after its markets settle, between daily rebuilds. This row’s category win record, average price and price edges are as of this time. Absent on every other row. |
category_evidence | HolderCategoryEvidence | No | |
wallet_age_days | integer | null | No | Whole UTC calendar days since this wallet’s first trade, as an integer (271, not 271.0): the number of UTC dates from the first trade’s date to today, so a first trade at 23:00 UTC reads 1 an hour later. Every wallet’s age changes at 00:00 UTC, once a day, not on every request. The five badge fields are present together, only for a wallet that draws at least one badge. |
is_new_wallet | boolean | No | True when the wallet’s first trade was under 30 days ago. |
markets_traded | integer | null | No | Distinct markets the wallet has traded. |
is_bot | boolean | No | True when the wallet is flagged as automated. |
x_username | string | null | No | The wallet’s X handle without the @, when linked. |
MarketHoldersMarket
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | mkt_-prefixed market id. |
condition_id | string | Yes | |
title | string | null | Yes | |
slug | string | No | |
event_slug | string | No | |
category | string | null | Yes | The canonical category bucket category_win_rate is measured in. |
outcome_yes | string | null | Yes | |
outcome_no | string | null | Yes | |
token_id_yes | string | null | Yes | |
token_id_no | string | null | Yes | |
end_date | string | No | |
status | open | closed | resolved | Yes | A settled market’s roster is whatever the provider still lists as open; it empties as holders redeem. |
protocol_version | v1 | v2 | Yes | The Polymarket protocol the market trades on, Gamma’s market version: v1 (CTF, ConditionalTokens) or v2 (Protocol V2). Read from the condition id, the same value GET /api/v1/markets/settled serves. On a v2 market every token_id this object names is a V2 position id: sign its orders for ExchangeV3 and read its balance as CONDITIONAL-V2. |
MarketHoldersScan
| Field | Type | Required | Description |
|---|---|---|---|
source | cached | live | Yes | cached: the shared holder snapshot, at most 180 s old at compute time. live: the provider answered a fresh complete walk for this compute. |
complete | boolean | Yes | Always true on a served roster. An incomplete or unstable scan is a 503, never a partial list. |
fetched_at | string | null | Yes | When the provider walk that produced the holder population finished. |
wallet_count | integer | Yes | Every distinct wallet the complete walk saw with open shares, graded or not. The roster lists the graded S/A/B subset. |
MarketHoldersSideGradeUsd
The rows’ current_value_usd per grade on one side, over the same wallets and values as that side’s usd total. Each value is rounded to the cent after summing, so s + a + b can differ from the side total by up to 2 cents.| Field | Type | Required | Description |
|---|---|---|---|
s | number | Yes | USD held by S-grade wallets netting this side. |
a | number | Yes | USD held by A-grade wallets netting this side. |
b | number | Yes | USD held by B-grade wallets netting this side. |
MarketHoldersSideGrades
| Field | Type | Required | Description |
|---|---|---|---|
s | integer | Yes | |
a | integer | Yes | |
b | integer | Yes |
MarketHoldersTotals
Roster totals BEFORE anyoutcome or min_grade filter, so a page always knows the whole market it was cut from.
| Field | Type | Required | Description |
|---|---|---|---|
graded_count | integer | Yes | Distinct graded wallets with net exposure; a two-sided wallet counts once. |
yes_count | integer | Yes | |
no_count | integer | Yes | |
yes_shares | number | Yes | |
no_shares | number | Yes | |
yes_usd | number | Yes | The rows’ current_value_usd summed over the graded wallets netting YES: a wallet holding both outcomes counts at its net shares’ value. |
no_usd | number | Yes | The rows’ current_value_usd summed over the graded wallets netting NO: a wallet holding both outcomes counts at its net shares’ value. |
yes_grades | MarketHoldersSideGrades | Yes | |
no_grades | MarketHoldersSideGrades | Yes | |
yes_grade_usd | MarketHoldersSideGradeUsd | Yes | yes_usd split by grade: where the S, A and B money on YES sits. |
no_grade_usd | MarketHoldersSideGradeUsd | Yes | no_usd split by grade: where the S, A and B money on NO sits. |
MarketPriceMovedData
market_price_moved data, also the MarketPriceMoved frame on GET /api/v1/stream: a sports or esports market’s outcome-0 midpoint moved a whole-cent level over one window. Prices are decimal strings at full precision. A missing value is null with its *_unavailable_reason.
| Field | Type | Required | Description |
|---|---|---|---|
best_ask | string | Yes | |
best_bid | string | Yes | |
concurrent_sharp_flow | object | Yes | |
concurrent_sharp_flow_unavailable_reason | object | Yes | |
condition_id | string | Yes | |
detected_at | string | Yes | |
direction | up | down | Yes | |
event_slug | string | null | Yes | |
from_price | string | Yes | |
game_state | object | Yes | |
game_state_unavailable_reason | object | Yes | |
gap_before | boolean | Yes | |
label | string | null | Yes | |
league | string | null | Yes | |
level_cents | integer | Yes | |
market_slug | string | null | Yes | |
move_cents | string | Yes | |
observed_at | string | null | Yes | |
outcome_index | integer | Yes | |
phase | pre_game | in_play | unknown | Yes | Where the game stood at detected_at. in_play: its live state reports it live. pre_game: its live state is neither live nor ended, or it has no live state yet and the market’s scheduled start (the games endpoints’ scheduled_at) is after detected_at. unknown: neither holds or the live state could not be read; game_state_unavailable_reason says why. |
previous_level_cents | integer | Yes | |
source | string | Yes | |
spread_cents | string | Yes | |
to_price | string | Yes | |
window_seconds | integer | Yes | |
window_start | string | Yes | |
book_depth_unavailable_reason | object | Yes | Why book_depth_within_2c is null, and null when it is present. no_book: no full order book has arrived for the market since tracking began, only quotes. book_changed: the best bid or ask moved after the latest full book, so its depth belongs to another top. band_not_covered: the latest full book shows no level beyond 2 cents from the midpoint on at least one side, so that side’s sum could be cut short. |
book_depth_within_2c | object | Yes | USD resting within 2 cents of outcome 0’s midpoint on each side at detected_at, or null with book_depth_unavailable_reason. |
MarketSearchResult
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | |
condition_id | string | Yes | |
title | string | Yes | |
slug | string | null | Yes | |
category | string | null | Yes | |
platform | polymarket | null | Yes | Provider platform. Always polymarket, or null when the row carries no stored value. |
status | active | closed | Yes | closed once Polymarket has closed trading or the market has resolved; active otherwise. The same rule labels a market on markets/search, markets/explore and market/{condition_id}/snapshot. |
event_slug | string | No |
MarketSettledData
market_settled data, also the MarketSettled frame on GET /api/v1/stream: a sports or esports game market settled, sent once per settled state the first time 0xinsider records it. A market can settle in more than one state: a resolved UMA question row with no winner yet, the same row with the winner ConditionalTokens paid on chain, and the condition row with the provider’s payouts; each is its own event with its own settlement_id, except a state naming the winner an earlier event named, which is not sent.
| Field | Type | Required | Description |
|---|---|---|---|
condition_id | string | Yes | Polymarket condition ID of the market, lowercase. |
settlement_id | integer | Yes | The recorded state: one per market per settled state, never reused. Deduplicate on it, or on the event id. |
event_slug | string | null | Yes | Polymarket event (game) slug, or null when the market stores none. |
game_id | string | null | Yes | Polymarket game ID for the event as a string, the game_id of GET /api/v1/games, or null when the market stores none. |
league | string | null | Yes | The event slug league prefix (nba in nba-lal-gsw-2026-11-01), lowercase, read after a polyv2 copy prefix. A PGA Tour golf slug starts with the year, so its markets are pga, from their series. null when neither names a league. |
sports_market_type | string | null | Yes | Polymarket sportsMarketType of the market (moneyline, spreads, totals, a prop type) verbatim, or null when the market stores none. |
outcomes | array of string | Yes | Outcome names, each at its outcome index: settlement.payouts and settlement.winning_outcome_index index into it. Empty when the market stores none; an outcome Polymarket labels blank is an empty string. |
copy_of_event_slug | string | null | Yes | Set on a Polymarket polyv2 copy of a game whose original event has a moneyline market: the original event slug, which GET /api/v1/games serves. Such a copy reaches a webhook only when its settlement_filters name its condition ID or its own event slug. |
settlement | object (expected_settlement_time, observed_at, oracle_status, payouts, proposed_answer, resolved_at, result, settled, settlement_time_basis, status, was_disputed, winning_outcome_index, oracle_updated_at) | Yes | The settled state, the block GET /api/v1/games/{event_slug}/markets serves as settlement: status observed, oracle_status resolved, settled true. payouts is null on a resolved UMA question row, whose result and winning_outcome_index come from the payout ConditionalTokens reported on chain (null in an event sent before it paid), and set on the condition row that follows, sent as its own event unless it names a winner already sent. observed_at is when 0xinsider first saw this state. |
protocol_version | v1 | v2 | Yes | The Polymarket protocol the market settles and redeems on, Gamma’s market version: v1 (ConditionalTokens) or v2 (the Protocol V2 modules: every market whose Gamma version reads v2, the polyv2 copies included). Read from the condition id, the same value on the webhook, the MarketSettled stream frame and GET /api/v1/markets/settled. A redelivery resends its event as first delivered, so one first delivered before the field shipped lacks it. |
MarketSnapshot
| Field | Type | Required | Description |
|---|---|---|---|
market | object (id, condition_id, provider, title, slug, page_slug, event_slug, category, status, description, image, series_slug, market_type, market_result, created_at, end_date, resolved_at, protocol_version) | Yes | |
outcomes | array of object (side, label, token_id, current_price, top_of_book) | Yes | |
liquidity | object (source, volume_usd, liquidity_usd, volume_24h_usd, volume_24h_as_of, last_price) | Yes | |
sports | object (status, source, live_match_key, live_league_key, live_score, reason) | Yes | |
freshness | object (market_data, top_of_book, live_sports) | Yes | |
trust | MarketSnapshotTrust | No | Price and spread trust metadata. Present only when expand=trust or expand[]=trust is requested. |
settlement | object (expected_settlement_time, observed_at, oracle_status, payouts, proposed_answer, resolved_at, result, settled, settlement_time_basis, status, was_disputed, winning_outcome_index, oracle_updated_at) | Yes | How Polymarket’s oracle settled or is settling this market, the block GET /api/v1/games/{event_slug}/markets serves, read from the store of the market’s event (a child event’s market: its game’s). It never waits for Polymarket: with nothing stored a settled market reads its recorded settlement, and any other reads status unavailable while the read starts. market.market_result stays null; read settlement.result. |
MarketSnapshotFreshness
| Field | Type | Required | Description |
|---|---|---|---|
status | fresh | stale | available | not_live | unavailable | Yes | |
source | string | Yes | |
as_of | string | No | |
stale_after_s | integer | No | Age-relative freshness bound when known. Omitted for live_sports: its as_of records compute start, while its two-second freshness marker starts at publication. |
reason | string | No |
MarketSnapshotTopOfBook
| Field | Type | Required | Description |
|---|---|---|---|
status | available | unavailable | Yes | |
source | string | Yes | |
best_bid | number | No | |
best_ask | number | No | |
spread_bps | integer | No | |
bid_depth_usdc | number | No | USD (price times size) on bids at or above the midpoint minus 0.02, from the whole book, rounded to the cent. The props filter min_book_usd_within_2c compares the unrounded sums, which expand=quotes serves as book_depth_within_2c. Absent when we hold no depth for the book. |
ask_depth_usdc | number | No | USD (price times size) on asks at or below the midpoint plus 0.02, from the whole book, rounded to the cent. The props filter min_book_usd_within_2c compares the unrounded sums, which expand=quotes serves as book_depth_within_2c. Absent when we hold no depth for the book. |
reason | string | No | Set when status is unavailable. cache_miss: we hold no book for the outcome yet. On an open market this read starts its live book, and a read 1 second later usually has it; on a closed market no book is started. cache_unavailable: we could not read the book from the cache; read again. stream_capacity: API reads already hold every live book they may open; reading again does not help until fewer markets are read. one_sided_book: the book holds bids or asks, not both, and the side it holds is served. empty_book: the book holds no orders. missing_provider_token_id: the outcome has no provider token id. |
MarketSnapshotTrust
Price and spread trust metadata returned only when GET /api/v1/market/{condition_id}/snapshot includes expand=trust.| Field | Type | Required | Description |
|---|---|---|---|
current_price | TrustMetadata | Yes | |
spread_bps | TrustMetadata | Yes |
MarketTopHolder
| Field | Type | Required | Description |
|---|---|---|---|
rank | integer | Yes | 1-based position on this outcome, by shares. |
trader_id | string | Yes | trd_-prefixed trader id, accepted by GET /api/v1/trader/{address}. |
address | string | Yes | Lowercased proxy wallet. |
name | string | null | Yes | The wallet’s display name; null when it shows none. |
grade | S | A | B | C | D | F | null | Yes | All-time trader grade, S to F. Null for a wallet 0xinsider has not graded: this route lists every holder whatever its grade. |
shares | number | Yes | Shares held on this outcome. |
current_value_usd | number | null | Yes | Polymarket’s current value of this position, in USD. Null when the provider served none. |
avg_entry_price | number | null | Yes | Average price paid for the shares still held, as a 0..1 fraction of $1. Null when the provider served none. |
other_outcome_shares | number | No | Shares on the other outcome when the wallet holds both; the wallet is then listed on both sides. Absent when it is one-sided. |
position_realized_pnl | number | null | Yes | Polymarket’s realized P&L of this position (sells and redemptions), in USD. Null when the provider served no economics for the row. |
position_unrealized_pnl | number | null | Yes | Polymarket’s mark-to-market P&L of the shares still held, in USD. On a resolved market the mark is the settlement price. |
position_total_pnl | number | null | Yes | position_realized_pnl plus position_unrealized_pnl, in USD. |
in_scope_realized_pnl | number | null | Yes | The wallet’s realized P&L on sports and esports markets, in USD, the figure on its 0xinsider profile. Null until 0xinsider has computed the record, never 0 in its place, and null for every row when profiles_status is unavailable. |
in_scope_volume | number | null | Yes | The wallet’s volume traded on sports and esports markets, in USD. Null under the same rule as in_scope_realized_pnl. |
strategy_type | string | null | Yes | The wallet’s stored trading-style label (see Wallet trading styles); null when it has none. |
last_traded_at | string | null | Yes | The wallet’s last recorded trade anywhere, null when unknown. |
category_win_rate | number | No | This wallet’s win rate in the market’s canonical category (market.category): the share of its settled markets in that category (it closed its position by selling out, or the market resolved) whose realized P&L closed positive, as a 0..1 fraction. Present only with category_win_rate_status = measured. The same read GET /api/v1/trader/{address}/categories serves per wallet. |
category_win_record | object (wins, decided) | No | The two counts category_win_rate is the ratio of, from the same row: wins / decided equals the rate. Every settled Polymarket market the wallet traded (it closed its position by selling out, or the market resolved) in the market’s canonical category, at any position size, rebuilt daily. Present only with category_win_rate_status = measured. |
category_avg_price | number | No | The wallet’s average entry price in the market’s canonical category, as a 0..1 fraction of $1 (0.98 is 98 cents). Its sample is the wallet's markets in that category that resolved to a winning side, of $20 or more where it bought one side at a known price, so it can differ from the category_win_record sample. A wallet that buys near-certain outcomes wins almost every time, so read the win rate beside this price. Present only with category_win_rate_status = measured, and only when that sample has at least 5 markets. When category_win_rate_game is present the price is still the whole category bucket’s: this field has no per-game or per-league price. Absent otherwise and on payloads predating the field. |
category_win_rate_game | string | No | Where category_win_rate and category_win_record were measured: for an esports market the game (LoL, CS2, Dota 2, Valorant, Call of Duty, Honor of Kings, Mobile Legends: Bang Bang, Overwatch, Rainbow Six Siege, Rocket League or StarCraft II), and for a market in a registered league that league, by the name Pick of the Day uses for it (NBA, NFL, NHL, MLB, UFC, ATP, WTA, LaLiga, Premier League, Serie A, UEFA Champions League, MLS and the other registered leagues). Present only when the wallet’s record there clears the 5-settled-market floor, in which case the rate and record are the game’s or league’s rather than the whole category bucket’s. Absent when the rate is the bucket’s (the wallet’s history there is under the floor, or the competition is not a registered league), on every other market, and beside every non-measured status. Label the rate with this when present and with the market’s category otherwise. |
category_win_rate_status | measured | not_enough_data | unavailable | untracked | No | Why category_win_rate is present or absent: measured (rate present), not_enough_data (the wallet is on file and under the floor of 5 decided markets in the category), untracked (0xinsider has no record of the wallet, so nothing was measured; grade, in_scope_realized_pnl and in_scope_volume are null too), or unavailable (a read failed; retry later). Absent when the market has no canonical category. |
category_price_edge | PickHolderPriceEdge | No | The wallet’s edge over the price it paid in the market’s canonical category (market.category), the figure the event page’s Top holders row prints for this wallet, from the same computation: how often the side it bought won, minus the average price it paid, over its settled markets there at a known entry price (every_size). Probabilities, not percentages: edge 0.022 is the page’s +2.2 pp, and hit_rate 0.515 over markets 98 is its won 51.5% of 98 markets. The page’s 95% range is 1.96 * sqrt(avg_price * (1 - avg_price) / markets) either side of edge (0.099, the page’s ± 9.9 pp, at 0.5 over 98 markets), and the page names an edge only when that range is all on one side of zero, printing no clear edge otherwise. Not category_win_rate minus category_avg_price: the edge counts its own sample. As of the row’s category_records_as_of, or the payload’s when the row has none. Present only with category_win_rate_status = measured when the page shows the edge; otherwise, beside a measured rate, category_price_edge_hold says why. Absent on every other row. |
category_scope_price_edge | PickHolderPriceEdge | No | The same edge over the markets of the game or league category_win_rate_game names alone: the edge the page prints beside a game or league win rate (for example +1.7 pp in CS2). Present only beside category_win_rate_game; otherwise, beside a game or league rate, category_scope_price_edge_hold says why. Never the whole category’s edge in its place. Absent on every other row. |
category_price_edge_hold | PickHolderPriceEdgeHold | No | Why there is no category_price_edge for a wallet with a measured rate, with the rule’s figures when it has them: the reason the page prints in place of the edge (for example too few markets). Present only with category_win_rate_status = measured, and never beside category_price_edge. |
category_scope_price_edge_hold | PickHolderPriceEdgeHold | No | Why there is no category_scope_price_edge beside a game or league rate, with the rule’s figures when it has them. Present only beside category_win_rate_game, and never beside category_scope_price_edge. |
wallet_age_days | integer | null | No | Whole UTC calendar days since this wallet’s first trade, as an integer (271, not 271.0): the number of UTC dates from the first trade’s date to today, so a first trade at 23:00 UTC reads 1 an hour later. Every wallet’s age changes at 00:00 UTC, once a day, not on every request. The five badge fields are present together, only for a wallet that draws at least one badge. |
is_new_wallet | boolean | No | True when the wallet’s first trade was under 30 days ago. |
markets_traded | integer | null | No | Distinct markets the wallet has traded. |
is_bot | boolean | No | True when the wallet is flagged as automated. |
x_username | string | null | No | The wallet’s X handle without the @, when linked. |
category_records_as_of | string | No | When this wallet’s category record was recounted, sent only when that is later than the category_records_as_of beside the rows: a wallet’s record is also recounted about an hour after its markets settle, between daily rebuilds. This row’s category_win_rate, category_win_record, category_avg_price and price edges (category_price_edge, category_scope_price_edge and their holds) are as of this time. Absent on every other row, which is as of the payload’s category_records_as_of. |
MarketTopHolders
| Field | Type | Required | Description |
|---|---|---|---|
market | MarketHoldersMarket | Yes | |
yes | array of MarketTopHolder | Yes | The largest YES holders, by shares, up to limit. |
no | array of MarketTopHolder | Yes | The largest NO holders, by shares, up to limit. |
totals | MarketTopHoldersTotals | Yes | |
profiles_status | available | unavailable | Yes | unavailable when the wallet record read failed: in_scope_realized_pnl, in_scope_volume and strategy_type are then null for every row because they were not read, not because they are unknown. |
category_records_as_of | string | No | When the daily pass behind the rows’ category win records and price edges began: the oldest any row’s record or edge can be. A row whose wallet was recounted since carries its own, later category_records_as_of; every other row is as of this time. Absent when the market has no category or the read answered no row. |
computed_at | string | No | When this holder sample was built. |
positions_as_of | string | No | When Polymarket’s holder board behind this sample was fetched: up to 120 s before computed_at on an open market. Absent on a resolved market, whose sample reads no live board, and when the fetch stamp could not be read. |
source_stale | boolean | Yes | true when this is the market’s last sample, served after its 30 s window while a refresh runs; positions_as_of is then at most 300 s old. Read again in a few seconds for the refreshed sample. Always false on a resolved market. |
MarketTopHoldersTotals
| Field | Type | Required | Description |
|---|---|---|---|
yes_count | integer | Yes | Holders in the YES sample, before limit. Equal to sample_cap means that many or more. |
no_count | integer | Yes | Holders in the NO sample, before limit. |
yes_shares | number | Yes | Shares summed over the YES sample. |
no_shares | number | Yes | Shares summed over the NO sample. |
sample_cap | integer | Yes | The most holders the sample keeps per outcome (100). |
MarketTrade
One taker fill of 100 USD or more on a market, from the exchange’s on-chain fill events.| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | {transaction_hash}:{log_index}: one fill event, listed once. Deduplicate on it across reads. |
traded_at | string | Yes | The fill’s block time, to the second. |
side | BUY | SELL | Yes | The taker’s side: BUY took outcome shares, SELL gave them. |
outcome | string | null | Yes | The traded outcome’s label; null when the market names none. |
outcome_index | integer | Yes | 0 for the first (Yes) outcome token, 1 for the second (No). |
token_id | string | null | Yes | The traded outcome token’s id (decimal string); null when the market holds none for that outcome. |
price | number | Yes | Fill price per share, 0 to 1. |
shares | number | Yes | Outcome shares filled. |
size_usd | number | Yes | USDC notional of the fill. |
taker | string | Yes | The taker’s wallet, lowercase. |
transaction_hash | string | Yes | The fill’s transaction, lowercase 0x hex. |
log_index | integer | Yes | The fill event’s log index in its transaction. |
MarketWalletsInOut
One market’s net buyers and net sellers over a 24h or 7d window, as the market page’s wallets in/out panel shows a Pro viewer.| Field | Type | Required | Description |
|---|---|---|---|
condition_id | string | Yes | The market’s raw provider condition id. |
window | string | Yes | The window the nets are summed over: 24h or 7d. |
window_start | string | null | Yes | The window’s inclusive start; null only when the bounds are unknown. |
window_end | string | null | Yes | The window’s inclusive end, the read’s clock; null only when the bounds are unknown. |
summary | object (wallets_in, wallets_out, net_usd) | Yes | Totals over every wallet that traded the market in the window, not only the listed 50. |
net_buyers | array of object (address, display_name, grade, net_usd, trades, last_traded_at) | Yes | Wallets whose net is positive, largest first, at most 25. |
net_sellers | array of object (address, display_name, grade, net_usd, trades, last_traded_at) | Yes | Wallets whose net is negative, most negative first, at most 25. |
McpJsonRpcError
| Field | Type | Required | Description |
|---|---|---|---|
jsonrpc | string | Yes | |
id | string or number or null | No | The request’s id, or null when the request could not be parsed. Omitted on the answer to an unsolicited response message. |
error | object (code, message, data) | Yes |
OutcomeCandles
One outcome token’s bucketed candle series.| Field | Type | Required | Description |
|---|---|---|---|
token_id | string | Yes | Provider CLOB token id the candles were read for. |
outcome | YES | NO | Yes | Canonical side label. |
candles | array of Candle | Yes | OHLC candles for this outcome token, ascending by bucket start. |
PickHolder
| Field | Type | Required | Description |
|---|---|---|---|
address | string | Yes | |
name | string | null | Yes | |
grade | string | null | Yes | All-time trader grade (S, A, B, C, D, F). |
last_traded_at | string | null | Yes | The UTC day of the wallet’s most recent recorded trade, served as that day’s 00:00:00Z, stamped at serve time from its current trader record rather than frozen with the pick. It changes at most once a day per wallet, so the pick’s ETag holds between polls. Always sent; null when no trade time is recorded. |
profile_segment | string | No | 0xinsider profile path segment this wallet links to: @<username> when that username resolves to this wallet alone, otherwise the lowercase wallet. Percent-encode the part after @ and append to https://0xinsider.com/profile/. Stamped at serve time; absent on a body cached before the field shipped. |
shares | number | Yes | |
entry_value_usd | number | No | USD entry value of this wallet’s position: shares times the pick’s frozen backed_price. An entry valuation, never a live balance or the provider’s current value. Omitted when the holder snapshot has no valid price. |
category_win_rate | number | No | This wallet’s win rate in the pick’s canonical category bucket (the pick’s category field, e.g. Basketball — label the rate with it, never with the narrower display_category league, except when category_win_rate_game is present, in which case the rate is that game’s or league’s and is labelled with it): the share of the wallet’s settled markets in that category (it closed its position by selling out, or the market resolved) whose realized P&L closed positive, as a 0..1 fraction. Present only with category_win_rate_status = measured, on display_holders entries, and only when the wallet clears the settled-market floor; frozen when the pick is published on picks from mid-November 2026 on, and recomputed at serve time from the current category read model on earlier picks (category_win_rate_status says which). Absent on holders entries, legacy rows, and payloads predating the field. |
category_win_record | object (wins, decided) | No | The two counts category_win_rate is the ratio of, read from the same row: wins / decided equals the rate. Counts every settled Polymarket market the wallet traded (it closed its position by selling out, or the market resolved) in the pick’s canonical category (or in its game or league, when category_win_rate_game is present), at any position size; the counts are rebuilt daily. Present only with category_win_rate_status = measured; absent otherwise and on payloads predating the field. |
category_avg_price | number | No | The wallet’s average entry price in the pick’s canonical category, as a 0..1 fraction of $1 (0.98 is 98 cents). Its sample is the wallet's markets in that category that resolved to a winning side, of $20 or more where it bought one side at a known price, so it can differ from the category_win_record sample. A wallet that buys near-certain outcomes wins almost every time, so read the win rate beside this price. Present only with category_win_rate_status = measured, and only when that sample has at least 5 markets. When category_win_rate_game is present the price is still the whole category bucket’s; the game’s or league’s own price is category_scope_avg_price. Absent otherwise and on payloads predating the field. |
category_scope_avg_price | number | No | The wallet’s average entry price in the game or league category_win_rate_game names, as a 0..1 fraction of $1: category_avg_price over that game’s or league’s markets only, under the same sample rules and the same 5-market floor. Read category_win_rate against this price when both are present; the difference is the wallet’s edge there. Present only beside category_win_rate_game, and only when that sample clears the floor; frozen or recomputed as category_win_rate is. Absent otherwise and on payloads predating the field. |
category_win_rate_game | string | No | Where category_win_rate and category_win_record were measured, by the same name the pick’s display_category uses for it: for an esports pick the game (LoL, CS2, Dota 2, Valorant, Call of Duty, Honor of Kings, Mobile Legends: Bang Bang, Overwatch, Rainbow Six Siege, Rocket League or StarCraft II), and for a pick in a registered league that league (NBA, NFL, NHL, MLB, UFC, ATP, WTA, LaLiga, Premier League, Serie A, UEFA Champions League, MLS and the other registered leagues). Present only when the wallet’s record there clears the 5-settled-market floor, in which case the rate and record are the game’s or league’s rather than the whole category bucket’s. Absent when the rate is the bucket’s (the wallet’s history there is under the floor, or the competition is not a registered league), on every other pick, beside every non-measured status, and on payloads predating the field. Label the rate with this when present and with category otherwise. |
category_win_rate_status | measured | not_enough_data | unavailable | untracked | No | Why category_win_rate is present or absent on a display_holders entry: measured (rate present), not_enough_data (the wallet is below the settled-market floor of 5 in the category), or unavailable (the annotation read failed; retry later). Never untracked: every recorded holder is a graded wallet 0xinsider has on file. Absent entirely on holders entries, legacy rows, and payloads predating the field — absence means the roster was never annotated, not a small sample. On picks published from mid-November 2026 on, this status and every record field beside it (the rates, records, average prices, category_win_rate_game, the edges and their holds) are frozen when the pick is published and never change; on earlier picks they are recomputed at serve time. |
wallet_age_days | integer | null | No | Whole UTC calendar days since this wallet’s first trade, as an integer (271, not 271.0): the number of UTC dates from the first trade’s date to today, so a first trade at 23:00 UTC reads 1 an hour later. Every wallet’s age changes at 00:00 UTC, once a day, not on every request, and the pick’s ETag holds between requests. Stamped at serve time from the wallet’s current trader record, never frozen with the pick. The five badge fields are present together, and only for a wallet that carries at least one badge; all absent means no badge, or a body cached before the fields shipped. |
is_new_wallet | boolean | No | True when the wallet’s first trade was under 30 days ago. Stamped at serve time from the wallet’s current trader record, never frozen with the pick. The five badge fields are present together, and only for a wallet that carries at least one badge; all absent means no badge, or a body cached before the fields shipped. |
markets_traded | integer | null | No | Distinct markets this wallet has traded. Stamped at serve time from the wallet’s current trader record, never frozen with the pick. The five badge fields are present together, and only for a wallet that carries at least one badge; all absent means no badge, or a body cached before the fields shipped. |
is_bot | boolean | No | True when the wallet has traded 10,000 or more distinct markets, the breadth floor 0xinsider uses to mark automated wallets. It is a breadth rule, not proof of automation. Stamped at serve time from the wallet’s current trader record, never frozen with the pick. The five badge fields are present together, and only for a wallet that carries at least one badge; all absent means no badge, or a body cached before the fields shipped. |
x_username | string | null | No | The wallet’s X handle from its Polymarket profile, normalized to 1-15 characters of [A-Za-z0-9_] with no @. Link it as https://x.com/<handle>. Stamped at serve time from the wallet’s current trader record, never frozen with the pick. The five badge fields are present together, and only for a wallet that carries at least one badge; all absent means no badge, or a body cached before the fields shipped. |
category_price_edge | PickHolderPriceEdge | No | The wallet’s edge over the price it paid in the pick’s canonical category (category): how often the side it bought won, minus the average price it paid, over its settled markets there at a known entry price (every_size). The rule the site’s sport leaderboards use for their Edge column, over every size, and the figure the pick card prints on the sport’s line. Not category_win_rate minus category_avg_price: the edge counts its own sample. Present only with category_win_rate_status = measured, when the edge ranks (30 or more such markets, and the share of the decided ones that made money at settlement within 10 points of the win rate) and the wallet’s realized P&L over them is above zero; otherwise category_price_edge_hold says why. Beside category_win_rate_game it is still the whole category’s edge; the game’s or league’s is category_scope_price_edge. Frozen when the pick is published on picks from mid-November 2026 on, and recomputed at serve time from the daily record rebuild on earlier picks. Absent otherwise and on payloads predating the field. |
category_scope_price_edge | PickHolderPriceEdge | No | The same edge over the markets of the game or league category_win_rate_game names alone: the edge the pick card prints beside a game or league win rate (for example -17.1 pp in the Premier League). Present only beside category_win_rate_game, under the same rule over that game’s or league’s markets and the wallet’s realized P&L there; otherwise, beside a game or league rate, category_scope_price_edge_hold says why. Never the whole category’s edge in its place. Frozen or recomputed as category_price_edge is. Absent otherwise and on payloads predating the field. |
category_price_edge_hold | PickHolderPriceEdgeHold | No | Why there is no category_price_edge for a wallet with a measured rate, with the rule’s figures when it has them. Present only with category_win_rate_status = measured, and never beside category_price_edge. Absent otherwise and on payloads predating the field. |
category_scope_price_edge_hold | PickHolderPriceEdgeHold | No | Why there is no category_scope_price_edge beside a game or league rate, with the rule’s figures when it has them. Present only beside category_win_rate_game, and never beside category_scope_price_edge. Absent otherwise and on payloads predating the field. |
after_release | object (changes_through, frozen, last_change_at, observed_at, other_shares_change, redeemed_at, redeemed_shares, redemptions_through, shares_after, shares_change, state, unavailable_reason, other_shares_after) | No | What this wallet did on the pick’s market after the pick was released, read from the fills, merges, splits and redemptions 0xinsider stores. Sits beside the release shares, which never change. state is held, added, reduced, exited, hedged or switched for the time between release and the game’s start, then redeemed once the wallet redeemed backed shares after settlement, unless it switched. The state reads both outcomes: compare the release backed_outcome_shares and other_outcome_shares with shares_after and other_shares_after. Read unavailable as unknown, never as held. Present on display_holders items of a full pick; absent on teasers and on payloads predating the field. |
backed_outcome_shares | number | No | Gross shares of the backed outcome this wallet held when the pick was released, from the same observation as other_outcome_shares; shares is the figure the pick lists. Present on display_holders items only, always with other_outcome_shares; absent on rosters recorded before the pair was. |
other_outcome_shares | number | No | Shares of the other outcome this wallet held when the pick was released, from the same observation as backed_outcome_shares: 0 means it held none then. Beside after_release.other_shares_change, it says whether the wallet bought the other side before or after release. Present on display_holders items only, always with backed_outcome_shares; absent on rosters recorded before the pair was. |
PickHolderPriceEdge
Edge over the price paid in one category, game or league: how often the side a wallet bought won, minus the average price it paid, over its settled markets there at a known entry price (every_size). Probabilities throughout: edge -0.171 is -17.1 percentage points. A market bought on both sides counts by its shares: the winning side’s share of the shares bought is its hit, the cost over those shares its price. Figures from the daily record rebuild.
| Field | Type | Required | Description |
|---|---|---|---|
markets | integer | Yes | Settled markets at a known entry price that the edge is measured over (every_size). |
hit_rate | number | Yes | Share of those markets whose bought side won, 0-1. |
avg_price | number | Yes | Mean entry price paid over the same markets, 0-1. Its sample is these markets, so it can differ from category_avg_price and category_scope_avg_price. |
edge | number | Yes | hit_rate minus avg_price, full precision. |
every_size | boolean | Yes | True when the figures count every settled market of every size; false or absent when they count markets of $20 or more (older or not yet recounted). |
PickHolderPriceEdgeHold
An edge the holder row does not show, and why.| Field | Type | Required | Description |
|---|---|---|---|
hold | category_loss | too_few_markets | sample_mismatch | no_markets | Yes | category_loss: the edge ranks, and the wallet’s realized P&L over the same markets is zero or below. too_few_markets: fewer than 30 counted markets. sample_mismatch: the share of the decided markets that made money at settlement is more than 10 points from the win rate over the same markets, so these markets do not describe the wallet’s record. no_markets: no settled market at a known entry price. |
record | PickHolderPriceEdge | No | The rule’s figures, as a shown edge carries them. Omitted for no_markets, and for too_few_markets when the wallet has fewer than 5 such markets. |
PickLeadBacker
Recorded lead wallet facts on a full response when available. Position and category history are frozen at publication; they are not live balances or pick win probabilities.| Field | Type | Required | Description |
|---|---|---|---|
address | string | Yes | Lead trader wallet address. |
name | string | null | Yes | Recorded provider display name. |
grade | string | Yes | Trader grade recorded at publication. |
category | string | Yes | Canonical sport of the recorded directional history. |
position_usd | number | Yes | Provider-reported position value on the backed outcome at publication, in USD. It is the gross value on that outcome and does not subtract shares the wallet held on the other outcome; see net_position_usd. It is not the entry cost or a live balance. |
net_position_usd | number | No | Net value of the lead’s position toward the backed outcome at publication, in USD: shares held on the backed outcome minus shares held on the other outcome of the same market, valued at the backed outcome’s provider price at publication. Present only when the wallet also held the other outcome; absent for a one-sided position, whose net equals position_usd. It is not a live balance. |
position_observed_at | string | Yes | Start time of the provider position fetch used at publication. This conservative observation clock precedes completion; the position is not a live balance. |
directional_event_count | integer | Yes | Distinct directional events in the recorded category history. |
profitable_event_count | integer | Yes | Events with strictly positive native terminal P&L in the same frozen category sample as directional_event_count, realized_pnl_usd and roi. Multiple market positions in one event contribute one combined event result. Zero-profit events remain in directional_event_count but do not increase this count. This is a recorded wallet result, not a market win rate or the pick’s win probability. |
realized_pnl_usd | number | Yes | Realized P&L over the recorded directional category sample, in USD. Excludes open positions and later changes. |
entry_basis_usd | number | Yes | Recorded entry basis of that directional sample, in USD; not a claim of complete trading costs or fees. |
roi | number | Yes | Realized P&L divided by recorded entry basis, as a fraction: 0.10 means 10%. This is a wallet statistic, not a pick win probability. |
max_realized_drawdown_usd | number | Yes | Peak-to-trough realized P&L drawdown after each event result in the recorded sample, in USD. Excludes intragame, unrealized, and account equity drawdown. |
recorded_at | string | Yes | Timestamp when the directional history evidence was recorded, separate from the provider position snapshot clock. |
PickOfTheDay
| Field | Type | Required | Description |
|---|---|---|---|
state | full | Yes | Full success containing entitled proof-readable picks. |
pick_date | string | No | The pick’s local publication date (YYYY-MM-DD). |
pick_rank | integer | No | Deprecated compatibility daily release slot; use pick_id for identity and publication_order for scheduling. |
picks | array of PickOfTheDay | No | Published picks for this product day in the returned display order. Use pick_id for identity. |
pick_count | integer | No | Number of items in picks: the proof-readable picks. Picks held in proof_pending_picks are not counted. |
scheduled_picks | array of ScheduledPickSlot | No | Rank-ordered entitled selections that have not released. Every row retains release_at and kickoff; unauthorized scheduled ranks appear only in identity-free locked_picks. |
matchup | string | No | Human-readable matchup (e.g. “Portugal vs. Uzbekistan”). |
category | string | No | Recorded canonical sport category. Prefer display_category for the public competition label. |
display_category | string | No | Frozen public presentation category. Tennis uses the provider-verified ATP or WTA tour, including Wimbledon and doubles; unknown tours retain Tennis. Every men’s and women’s cricket competition uses Cricket. Other sports use the curated league, esports title or soccer competition label, then the provider series name without its season year, then category when no competition is known. The canonical category and measured cohort are unchanged: an esports title still uses the pooled Esports category. Optional for mixed-version client compatibility. |
platform | polymarket | No | Provider platform. Always polymarket. |
release_at | string | No | The pick’s stored release instant. Use the returned timestamp; published_at records when publication occurred. |
is_locked | boolean | No | True only before the pick’s stored release instant (a pre-release embargo flag); effectively always false on a served, already-published pick. To detect that the backed game has kicked off, use game_started. |
game_started | boolean | No | True once the backed game has started (kickoff <= now). When true the snapshotted pre-game price is no longer actionable. It compares the start recorded with the pick, which can briefly trail a provider reschedule that kickoff already shows. Absent for a legacy pick with no recorded start (treat as not-started). |
game_ended | boolean | No | Whether the backed game is over, from the game’s scoreboard. Once the game is recorded as finished it stays true, on later reads and on past days. A pick settled win or loss reads true unless the live scoreboard shows the game still in play. Tells a finished game from one still in play before outcome settles. Omitted when the game’s state is unknown; absence is unknown, never false. |
outcome | pending | win | loss | void | No | Settlement outcome of the backed side; ‘pending’ until the market resolves. |
outcome_display | string | No | Pre-formatted SETTLEMENT STATUS for display: “Win” / “Loss” / “Void” / “Pending” — the outcome enum above as a label. Convenience only; outcome is the source value. NOTE: this is the win/loss STATUS, not the backed side. The backed side is pick_outcome_label (“Belgium (-2.5)”) — a different field answering a different question. |
pick_outcome_label | string | No | The backed side as a short label: a team for a moneyline (e.g. “Bengals”), the team and handicap for a spread (e.g. “Seahawks (-14.5)”), the line and side for a total (e.g. “O/U 38.5 (Under)”), or “{team} to advance” for a knockout advancement market (e.g. “Spain to advance”). |
token_id | string | No | The Polymarket CLOB token id (ERC1155 asset id, decimal string) for the backed outcome; omitted when unavailable (e.g. unsynced markets). |
position | string | No | The backed side as the pick’s headline reads it (e.g. “Bengals to win”, “Seahawks (-14.5)”, “O/U 38.5 (Under)”). |
side_summary | string | No | One-line summary of which side sharp money is backing. On a pick dated 2026-08-12 or later it counts the S and A grade wallets the pick lists on the backed side, the sharp_wallet_count value, and names those grades: “26 S and A grade wallets on Alexander Shevchenko”, or “1 S or A grade wallet on …”. The list can leave out wallets that hold the side. The site’s “profitable wallets” counts the S, A and B grade wallets the pick lists, so its number can be larger for the same pick. A pick whose only recorded backing is its lead wallet reads “Recorded lead wallet on …”. Earlier picks, and a pick recorded without graded holders, keep the sentence recorded with them. Required on every item in picks: a current-day published pick whose required holder proof is not safely readable is listed in proof_pending_picks instead of being served with a partial success shape or a synthetic zero, and the route returns 503 read_model_warming only when no published pick has readable proof. |
sharp_wallet_count | integer | No | S/A wallet count of the wallets the pick lists on the backed side, in the public V1 compatibility projection. |
smart_wallet_count | integer | No | Deprecated spelling of sharp_wallet_count with the same value. |
top_grade | string | No | Best recorded S/A grade in the public V1 compatibility projection. Absent when the pick lists no S or A grade wallet, for example a pick that lists only B grade wallets; display_holders lists every grade. |
sharp_usd | number | No | Recorded graded-flow magnitude in USD on the backed side. Absent when the recorded value is zero, and on every pick that carries lead_backer. |
smart_usd | number | No | Deprecated spelling of sharp_usd with the same value. |
backed_price | number | No | Frozen pre-game probability (0..1) for the backed side, written once at publication. It is the Polymarket CLOB order book midpoint at release, not an executed fill: a buyer lifts the ask, so a subscriber’s own entry is usually a little worse than this price. |
entry_price_note | string | No | Full-only disclosure when backed_price was recovered from provider history within 30 seconds before publication. Render beside the price. Absent for ordinary publication captures and teasers; this is a historical reference, not an executed fill. |
odds_display | string | No | Pre-formatted backed_price as cents-on-the-dollar odds, to ONE decimal: “62.0c” / “99.9c”. Never rounded to a whole cent — a 99.9c favorite is not a 100c certainty. Convenience only; backed_price is the source value. Omitted when backed_price is. |
stake_usd | number | No | The flat stake the published record puts on every pick, in USD: 1000 since 2026-09-22 (it was 100 before). Present exactly when return_usd is, so a reader never has to know the stake from anywhere else. |
return_usd | number | No | Gross return of stake_usd at the frozen midpoint price (stake_usd / backed_price). A real fill pays the ask, so an executed stake usually returns a little less. Omitted with backed_price. |
return_per_100 | number | No | The same return on a literal $100 (100 / backed_price), kept for compatibility: the field predates stake_usd and its name promises the $100 basis, so a client that scales it to its own stake stays right. Present exactly when return_usd is. |
payout_display | string | No | Pre-formatted return_usd as USD with cents and thousands separators: “$1,612.90" / "$12,500.00”. The GROSS return (the stake included), so it carries no sign. Convenience only; return_usd is the source value. Omitted when return_usd is. |
profit_display | string | No | Pre-formatted PROFIT on the stake — return_usd minus stake_usd, i.e. the payout net of what you put in — as a signed USD string: ”+$612.90”. Distinct from payout_display, which is gross. Omitted when return_usd is. |
clv_status | string | No | Backend-owned CLV capture disposition. “pending” means no capture decision exists yet; terminal provider or quality statuses remain distinguishable. The raw close price and timestamp are never serialized. |
clv_basis | string | No | Backend-owned CLV evidence basis. frozen_displayed_entry uses the persisted displayed entry. historical_provider_entry uses a known-CLOB point at or before publication. historical_provider_price_match requires the latest point in the prior hour to match. historical_provider_nearby_price_match requires a matching point within five minutes before publication. Source-null bases preserve unknown original provenance. |
clv_pct | number | No | Closing-line value toward the backed side, computed as (close / entry - 1) * 100. The basis-specific provider p entry must match the stored display; historical_provider_price_match also requires source provenance to remain null and its latest entry to be within the one-hour window at or before publication. Every basis requires a later quality-checked p close from the same series in the bounded post-entry, pre-kickoff window. Omitted when not measured. |
clv_display | string | No | Backend-formatted signed CLV percentage, present exactly when clv_pct is present. |
clv_explanation | string | No | Backend-owned CLV formula text with the entry probability, close probability, and rounded result. Provider timestamps remain private. |
unit_score | number | No | Net return for the pick in stake units (return_usd / stake_usd - 1); one unit is one stake_usd stake, and the figure is the same under any stake size. Omitted when the outcome is not valued. |
unit_score_display | string | No | Backend-formatted signed unit score, present exactly when unit_score is present. |
sharp_pct | number | No | Recorded sharp-money share as a 0..1 fraction. This is not a winning probability. Absent on every pick dated 2026-08-12 or later: from that date the recorded share includes B grade wallets, which this S and A projection does not count. Earlier picks carry it when it was recorded. backed_side_share carries the recorded share on every pick, on the pick’s own grade basis. |
market_pct | number | No | Recorded market-implied probability as a 0..1 fraction when available. |
qualifying_expert | object (address, name, grade, canonical_category, win_rate, n_resolved, position_usd, opposite_position_usd, stats_computed_at) | No | Optional recorded specialist facts on a full response. These describe the trader, not the pick’s win probability. Omitted when no recorded specialist is available. |
traders | integer | No | Public V1 S/A wallet count on the backed side, equal to sharp_wallet_count. |
backed_sharp_usd | number | No | Recorded aggregate backed-side position value in USD, not a live balance or entry cost. Absent on every pick dated 2026-08-12 or later: from that date the recorded value includes B grade wallets, which this S and A projection does not count. Earlier picks carry it when it was recorded. sharp_positioned_usd carries the recorded value on every pick, on the pick’s own grade basis. The display_holders roster can include additional wallets; use the returned aggregate rather than summing that roster. |
holders | array of PickHolder | No | Bounded S/A holder display projection from the recorded snapshot. Historical rows retain their recorded display shape. |
display_holders | array of PickHolder | No | Optional recorded holder roster in display order, with lead_backer first when present. Preserve the returned order. The roster can include wallets outside the recorded count and aggregate fields; do not derive holder_count, wallet counts or backed_sharp_usd from its length or a sum. Position values are gross holdings on the backed outcome and can coexist with holdings on the other outcome. Historical rows retain their recorded display shape. |
holder_count | integer | No | S/A holder count for the public V1 compatibility projection. display_holders can include additional grades. sharp_positioned_usd and backed_side_share count every grade the pick lists, so a pick that lists only B grade wallets reads 0 here beside a positive sharp_positioned_usd. |
thesis | string | No | Display-ready explanation of the recorded pick. Render the returned text rather than reconstructing it from holder counts or grades. |
market_url | string | No | Canonical web market URL. |
polymarket_url | string | No | The pick’s event on Polymarket, carrying the 0xinsider tags: https://polymarket.com/event/<event_slug>?via=0xinsider&r=0xinsidercom. Present whenever event_slug is. |
event_slug | string | No | The canonical /event game-page slug (one neutral page per game); omitted when the game has no neutral event page. |
event_link_slug | string | null | No | Backend-resolved /event destination slug for the source market. Omitted outside full responses; null is an authoritative no-link decision. |
sports_context | PickSportsContext | No | Provider-first sports context for the pick’s market (team logos, league branding, live score). Full-state only; omitted when the pick is not a team-sports market. |
disclaimer | string | No | Risk disclaimer shown with every pick. |
proof_pending_picks | array of ProofPendingPickSlot | No | Entitled published picks whose holder proof is unreadable, ordered by rank. Unauthorized ranks appear only in locked_picks and cannot trigger proof warming. Read retry_at for the next read. |
entry_authorization | PotdEntryAuthorization | No | Optional full-response entry authorization. The pick’s release issues it once, only when a fresh check then finds the pick meets the selection standard in force at release and its current price still allows an entry. A pick released without one never gains one later, so read its absence as no automated entry for this pick, not as pending. Missing or expired authorization cannot authorize an automated entry. |
locked_picks | array of object (pick_rank, required_tier) | No | Unauthorized unresolved published or scheduled ranks. Contains no game, provider identity, price, or identifying clock. Pro may upgrade to Max to open these ranks. |
message | string | No | Actionable status, including Upgrade to Max when only locked ranks are published. |
pick_id | string | No | Stable pick row identity as decimal text. Never use a quality rank as identity. |
publication_order | integer | No | Compatibility release slot. No quality claim; historic scheduling order is retained. |
is_free_selection | boolean | No | Viewer-independent free selection designation. New rows store it explicitly; historic null storage uses the original free slot. |
supersedes_pick_id | string | null | Yes | Deprecated (#24157): always null. No replacement lineage was ever recorded in this field; the key stays so existing V1 clients keep parsing. Identify a pick by pick_id. |
lead_backer | PickLeadBacker | No | Optional full-only lead wallet publication facts: the profitable wallet whose position and record certified the pick when it was released. Many picks have no certified lead, and a pick released without one never gains one later. Also omitted on legacy picks or when the recorded evidence is unavailable in this response. |
more_picks_until | string | No | On the top level of today’s set read. The instant until which today’s list of published picks can still grow: present while another pick can still be added to the day, absent once the day is final. Absent for a past date, on picks items and on a pick_id read. A later pick is possible, not promised; schedule one read before this instant instead of polling. |
public_sports_identity | object (event_matchup, league_logo, league_name, no_team, side_order, yes_team) | No | Display identity for the pick’s game: the league and the two sides, with names, crests and records, and for a tennis player the headshot, tour and ranking. Sent on a pick whose sports identity resolved; absent otherwise. It carries no market, event or provider identifier. An image value that starts with / is a path relative to https://0xinsider.com. |
published_at | string | No | When the pick was published: the recorded instant, the same one the archive returns for it. release_at is the scheduled release. Sent on every pick; absent with the other pick fields on a state=none body. |
resolved_at | string | No | When outcome was LAST written to a settled value (RFC3339 UTC), the same instant the archive and the commitment ledger return for the pick. It moves with a corrected market re-mapping an already-settled pick. Omitted (not null) for a pending pick and for a pick that settled before the instant was recorded, so absence means the instant is unknown, never that the pick is unsettled — outcome answers that. Additive and optional for mixed-version client compatibility. |
kickoff | string | No | When the backed game starts (RFC3339 UTC): the same instant the 0xinsider site shows for the pick, read from the provider’s current schedule, so a rescheduled game shows its new start, else the start recorded with the pick. scheduled_picks and proof_pending_picks use the same name for a pick’s start. Omitted (not null) only when neither is on record, on a legacy pick; never estimated. Additive and optional for mixed-version client compatibility. |
backed_side_share | number | No | The Sharp side share the pick’s page shows, from the same recorded value: of all the dollars graded wallets held in the market, on both sides, the part on the backed side, as a fraction from 0 to 1 (pick 2153 reads 0.887, which the page prints as 88.7%). It counts the grades of the pick’s own wallet policy: S, A and B wallets on picks dated 2026-08-12 or later, where sharp_pct is absent, and S and A wallets before that date, where it equals sharp_pct. Frozen when the pick was selected, or at its first complete pre-game publication read for a pick stored without a selection snapshot, and not updated after. A measure of positioning, not a winning probability. Absent when the pick recorded no share. Additive and optional. |
sharp_positioned_usd | number | No | The Sharp positioned value the pick’s page shows, from the same recorded value: the dollars, in USD, that the wallets the pick counts held on the backed side, on the same grade basis as backed_side_share. When the pick’s frozen wallet list states each counted wallet’s shares, it is those shares at the pick’s recorded price; otherwise it is the figure stored when the pick was selected, which covers every graded wallet on the backed side then. On picks dated before 2026-08-12 it equals backed_sharp_usd. Recorded for the pick and not updated after: not a live balance or entry cost. The display_holders roster can include additional wallets; use this value rather than summing that roster. Absent when the pick recorded no value. Additive and optional. |
side_graded_wallet_count | integer | No | Every graded wallet (S, A or B) holding the backed side when the pick was selected, listed or not: the wallets whose money backed_side_share is the share of. display_holders lists some of them, so this can exceed holder_count and the roster’s length (pick 2178 lists 6 of 11). Sent on picks recorded under the current S, A and B wallet policy that stored the count; absent otherwise, on a teaser, and on payloads predating the field. Additive and optional. |
side_graded_usd | number | No | Those wallets’ gross USD on the backed side when the pick was selected, sent only beside side_graded_wallet_count and only when above zero. It values every share at selection, so it can differ from sharp_positioned_usd. Not a live balance or entry cost. Additive and optional. |
commitment_hash | string | No | The pick’s sealed pre-game commitment as 64 lowercase hex characters: the commitment_hash its entry in GET /api/v1/pick-of-the-day/ledger/{pick_id} and the public repository github.com/0xinsider/picks carry. Sent with sealed_at, ledger_url and committed_kickoff, all four or none; absent on a pick that was never sealed. Additive and optional. |
committed_kickoff | string | No | The game start the sealed commitment bound (RFC3339 UTC): the start the pick was released against, the kickoff its opened ledger payload carries. kickoff follows the provider’s current schedule, so the two differ when the game moved after release; measure how far ahead of the game a pick went out from this one. Sent with commitment_hash. Additive and optional. |
game_start_time | string | No | The same instant as kickoff, under the name the 0xinsider site’s own pick body uses. Sent whenever kickoff is. Additive and optional. |
holders_observed_at | string | No | When the pick’s release read of its listed wallets was taken (RFC3339 UTC): the first accepted read of the backed side’s holders, stored once at release and never read again, keeping only the wallets display_holders lists. Absent when no release read is stored for the pick yet, when the stored read was not taken at release (picks released before the release read began on November 10, 2026, or whose first read came late), and on picks without display_holders. Additive and optional. |
ledger_url | string | No | The page of the public ledger file in github.com/0xinsider/picks that records this pick’s product day; its history shows the commit that recorded the hash. Sent with commitment_hash. Additive and optional. |
records_as_of | string | No | When the daily wallet-record pass behind the listed wallets’ records began (RFC3339 UTC), from the same stored release read as holders_observed_at and under the same conditions: the oldest a listed wallet’s records can be, since a wallet is also recounted about an hour after its markets settle. Absent when that read recorded no pass. Additive and optional. |
sealed_at | string | No | When the commitment was sealed (RFC3339 UTC), the sealed_at its ledger entry carries; always before committed_kickoff. Sent with commitment_hash. Additive and optional. |
sports_market_type | string | No | The backed market’s Polymarket sports market type as recorded with the pick: moneyline, spreads, totals, map_handicap and others, the value the archive row returns for the pick. Omitted when the market states none. Additive and optional. |
protocol_version | v1 | v2 | No | The Polymarket protocol the market trades on, Gamma’s market version: v1 (CTF, ConditionalTokens) or v2 (Protocol V2). Read from the condition id, the same value GET /api/v1/markets/settled serves. On a v2 market every token_id this object names is a V2 position id: sign its orders for ExchangeV3 and read its balance as CONDITIONAL-V2. |
PickOfTheDayArchive
| Field | Type | Required | Description |
|---|---|---|---|
picks | array of PickOfTheDayArchiveEntry | Yes | Published Pick of the Day selections that have not been withdrawn, newest first by pick_date and then pick_rank within each product day. Withdrawn rows stay excluded after settlement. |
days | array of PickOfTheDayArchiveDay | Yes | One entry per product day that has a published pick included in the archive, newest first, in the same order as picks. Each carries that day’s net units, accumulated in the same backend pass and behind the same visibility gate as hit_rate.unit_score, so both cover the same population of picks. Re-adding the day totals reproduces hit_rate.unit_score to display precision rather than bit-for-bit, since that re-associates the floating-point sum. |
hit_rate | PickOfTheDayHitRate | Yes | |
page | object (has_more, limit, next_cursor, returned, total) | No |
PickOfTheDayArchiveDay
| Field | Type | Required | Description |
|---|---|---|---|
date | string | Yes | The product day (YYYY-MM-DD). |
picks | integer | Yes | Published picks on the day: wins + losses + void + pending. |
wins | integer | Yes | Picks on the day that resolved as a win, counted by the same pass as hit_rate.wins, so the day entries sum to the headline record. |
losses | integer | Yes | Picks on the day that resolved as a loss, counted by the same pass as hit_rate.losses. |
void | integer | Yes | Picks on the day that resolved void: the market settled with no winner, or the game was suspended or postponed and not completed within 72 hours of kickoff. A void is neither a win nor a loss and is not staked, so it enters no money figure. |
pending | integer | Yes | Picks on the day not yet resolved. A day whose picks are all pending is a real 0-0 day with pending > 0, not a missing record. |
unit_score | number | No | Net units over the day’s visible, valued, staked (win or loss) picks: the same population staked_usd runs over. Omitted when the day has not scored — every pick still pending or void, or a price-gated current row — which is not the same as a real 0.0 day. |
unit_score_display | string | No | unit_score pre-formatted as signed units to two decimals (for example +1.24u or -2.00u), by the same formatter the per-pick unit_score_display and hit_rate.unit_score_display use. Present exactly when unit_score is; unit_score is the source value. |
sweep | win | loss | No | win when every decided pick on the day won, loss when every one lost, over at least three decided (win or loss) picks with nothing pending. Omitted for every other day. A void is not a result: it neither lifts a day over the floor nor spoils a sweep. |
PickOfTheDayArchiveEntry
| Field | Type | Required | Description |
|---|---|---|---|
pick_date | string | Yes | The pick’s local publication date (YYYY-MM-DD). |
pick_rank | integer | Yes | Deprecated compatibility daily release slot; use pick_id for identity and publication_order for scheduling. |
published_at | string | No | When this selection was published, as RFC3339 UTC. Use this instant for publication feeds and timelines; pick_date is the America/New_York product day, not a publication timestamp. Absent only for historical rows whose publication instant is unknown. |
matchup | string | No | Human-readable matchup (e.g. “Portugal vs. Uzbekistan”). |
category | string | No | Frozen canonical sport bucket (e.g. “Basketball”, “MMA”, or “Soccer”). Existing semantics are unchanged; presentation consumers should prefer display_category when present. |
display_category | string | No | Frozen public presentation category. Tennis uses the provider-verified ATP or WTA tour, including Wimbledon and doubles; unknown tours retain Tennis. Every men’s and women’s cricket competition uses Cricket. Other sports use the curated league, esports title or soccer competition label, then the provider series name without its season year, then category when no competition is known. The canonical category and measured cohort are unchanged: an esports title still uses the pooled Esports category. Optional for mixed-version client compatibility. |
image_url | string | No | Provider (Polymarket Gamma) market thumbnail URL (markets.image); omitted (not null) when the market has no image. Public regardless of the backed-side gate, so present for pending rows too. |
pick_outcome_label | string | No | The backed side’s outcome label. Omitted for a still-pending pick when the request is not from an authenticated Pro key. |
top_grade | string | No | Recorded best S or A grade on the backed side in the public V1 compatibility projection. Omitted when unavailable, including on a pick that lists no S or A grade wallet. Historical values remain recorded snapshots. |
outcome | pending | win | loss | void | Yes | Settlement outcome of the backed side; ‘pending’ until the market resolves. |
outcome_display | string | No | Pre-formatted settlement status for display: “Win” / “Loss” / “Void” / “Pending” — the outcome enum above as a label, from the same formatter the pick payload’s outcome_display uses. Convenience only; outcome is the source value. |
resolved_at | string | No | When outcome was LAST written to a settled value (RFC3339 UTC), the same instant the commitment ledger publishes. It moves with a corrected market re-mapping an already-settled pick. Omitted (not null) for a pending pick and for a pick that settled before the instant was recorded, so absence means the instant is unknown, never that the pick is unsettled — outcome answers that. Additive and optional for mixed-version client compatibility. |
stake_usd | number | No | The flat stake this row was valued at, in USD: 1000 since 2026-09-22 (100 before). Every row of the record is valued at the current stake, including picks published before the change. Present exactly when return_usd is. |
return_usd | number | No | Gross return of stake_usd on this resolved pick: a win returns stake_usd / backed_price and a loss returns 0. A loss always returns 0 (the whole stake is lost regardless of price). The operand is published beside it as backed_price on every row that carries a return, so the entry never has to be recovered by inverting this number. Omitted (not null) for a still-pending pick, for a void (the market settled with no winner, or the game was suspended or postponed and not completed within 72 hours of kickoff, so the pick is not staked) and for a resolved WIN with no frozen price (a win’s payout needs the price); mirrors the backend skip-when-absent behavior and the route-client optional (non-nullable) schema. |
return_per_100 | number | No | The same return on a literal $100 (a win returns 100 / backed_price, a loss 0), kept for compatibility: the field predates stake_usd and its name promises the $100 basis. Present exactly when return_usd is. |
payout_display | string | No | Pre-formatted return_usd as USD with cents: “$2,000.00”. Present exactly when return_usd is — it is formatted from that already-gated value — so it is omitted for a still-pending pick, a void, an unpriced win, and any pick whose backed side is withheld. Convenience only; return_usd is the source value. |
backed_price | number | No | Frozen price of the backed side (0..1) that return_usd and return_per_100 were computed from: on a win, stake_usd / backed_price equals return_usd. It is the Polymarket CLOB order book midpoint at release, frozen write-once at publication, not an executed fill: a buyer lifts the ask, so a subscriber’s own entry is usually a little worse than this price. Present when return_usd is, on a void, which carries no return, and on a still-pending pick whose CLV is measured (clv_pct present), where it equals clv_entry_price. Omitted for any other still-pending pick, an unpriced win, and any pick whose backed side is withheld. |
clv_pct | number | No | Closing-line value toward the backed side, computed as (close / entry - 1) * 100. Omitted when the row is gated, ineligible, or not measured. |
clv_display | string | No | Backend-formatted signed CLV percentage, present exactly when clv_pct is present. |
clv_entry_price | number | No | Entry operand of clv_pct: the frozen pick probability the close is compared against. It equals backed_price, which CLV eligibility requires. Present exactly when clv_pct is. |
clv_close_price | number | No | Close operand of clv_pct: the last valid Polymarket probability before the close bound (kickoff, or the first instant the live feed reported the game in progress when that came earlier). Present exactly when clv_pct is; the close timestamp stays private. |
clv_applicability | applicable | not_applicable | No | Whether CLV applies. A visible resolved pick published after kickoff is not_applicable. |
clv_explanation | string | No | Backend-owned CLV text. A measured row names the entry, then the close, then the formula (close / entry - 1) x 100 and its rounded result; otherwise it gives the reason CLV does not apply or is unavailable. |
clv_status | string | No | Exact backend CLV capture disposition for this visible row. Pending and terminal provider or quality statuses are distinguishable; capture timestamps are never serialized, while a measured row’s entry and close prices are published as clv_entry_price and clv_close_price. |
clv_basis | string | No | Backend-owned CLV evidence basis. Source-null price-match bases preserve unknown original provenance. historical_provider_nearby_price_match requires a matching Polymarket point within five minutes before publication. |
unit_score | number | No | Net return for this pick in stake units (return_usd / stake_usd - 1), where one unit is one stake_usd stake; the same figure under any stake size. Omitted when the backed side is withheld or the pick is not valued. |
unit_score_display | string | No | Backend-formatted signed unit score, present exactly when unit_score is present. |
required_tier | account | insider | max | No | The account or paid tier needed to open this unresolved rank. |
backed_side_locked | boolean | No | True for an unauthorized unresolved row. Game identity, category, image, publication clock and all backed facts are omitted. |
pick_id | string | Yes | Stable pick row identity as decimal text. Never use a quality rank as identity. |
publication_order | integer | Yes | Compatibility release slot. No quality claim; historic scheduling order is retained. |
is_free_selection | boolean | Yes | Viewer-independent free selection designation. New rows store it explicitly; historic null storage uses the original free slot. |
supersedes_pick_id | string | null | Yes | Deprecated (#24157): always null. No replacement lineage was ever recorded in this field; the key stays so existing V1 clients keep parsing. Identify a pick by pick_id. |
backed_side_share | number | No | The single-pick read’s backed_side_share for the same pick: the Sharp side share the pick’s page shows, the part of the graded wallets’ dollars in the market that sat on the backed side when the pick was selected, as a fraction from 0 to 1 (0.887 is the page’s 88.7%). Absent where the single-pick read omits it and on a row with backed_side_locked. Additive and optional. |
condition_id | string | No | The backed market’s Polymarket condition_id, the one the single-pick read serves as entry_authorization.condition_id. Present on every row whose backed side this key opens. Additive and optional. |
kickoff | string | No | When the backed game starts (RFC3339 UTC): the start recorded with the pick. The single-pick read (GET /api/v1/pick-of-the-day?pick_id=) serves the same instant unless the provider moved the game after publication, where that read states the new start. Present on every row whose backed side this key opens; omitted on a row with backed_side_locked. Additive and optional. |
sharp_positioned_usd | number | No | The single-pick read’s sharp_positioned_usd for the same pick: the Sharp positioned value the pick’s page shows, the dollars the pick’s counted graded wallets held on the backed side, in USD, recorded for the pick and not updated after. Absent where the single-pick read omits it and on a row with backed_side_locked. Additive and optional. |
sharp_wallet_count | integer | No | The single-pick read’s sharp_wallet_count for the same pick: S/A wallet count of the wallets the pick lists on the backed side, in the public V1 compatibility projection. Absent where the single-pick read omits it and on a row with backed_side_locked. Additive and optional. |
side_graded_usd | number | No | The single-pick read’s side_graded_usd for the same pick: those wallets’ gross USD on the backed side when the pick was selected, sent only beside side_graded_wallet_count and only when above zero. Not a live balance or entry cost. Additive and optional. |
side_graded_wallet_count | integer | No | The single-pick read’s side_graded_wallet_count for the same pick: every graded wallet (S, A or B) holding the backed side when the pick was selected, listed or not. Sent on picks recorded under the current S, A and B wallet policy that stored the count; absent otherwise and on a row with backed_side_locked. Additive and optional. |
sports_market_type | string | No | The backed market’s Polymarket sports market type as recorded with the pick: moneyline, spreads, totals, map_handicap, both_teams_to_score and others. Present when the row’s backed side is open and the market states a type. Additive and optional. |
PickOfTheDayArchiveSummary
The archive withview=summary: hit_rate without its daily series, one short row per pick, and page. Page with limit and cursor; view=full returns every field of a row.
| Field | Type | Required | Description |
|---|---|---|---|
hit_rate | object (clv_applicable, clv_avg_display, clv_avg_pct, clv_avg_pp, clv_avg_pp_display, clv_beats_close, clv_coverage_display, clv_coverage_explanation, clv_coverage_pct, clv_eligible, clv_measured, clv_not_applicable, clv_pending, clv_state, clv_ties, clv_total, clv_unavailable, decided, losses, net_profit_display, net_profit_usd, pct, pending, roi_display, roi_pct, stake_usd, staked_usd, unit_score, unit_score_display, void, win_rate_display, wins, edge_display, edge_pp, priced_decided, priced_in_display, priced_in_pct) | Yes | |
page | object (has_more, limit, next_cursor, returned, total) | Yes | |
picks | array of object (backed_price, backed_side_locked, clv_pct, display_category, is_free_selection, matchup, outcome, pick_date, pick_id, pick_outcome_label, publication_order, required_tier, top_grade, unit_score) | Yes | |
view | string | Yes |
PickOfTheDayAskComparison
| Field | Type | Required | Description |
|---|---|---|---|
ask | object (roi_display, roi_pct, units, units_display) | Yes | |
from_date | string | null | Yes | |
from_date_display | string | null | Yes | |
midpoint | object (roi_display, roi_pct, units, units_display) | Yes | |
valued_decided | integer | Yes |
PickOfTheDayCommitmentPayload
Select using the entry commitment_version, never implicit payload shape. All historic v1 hashes remain unchanged. One of:PickOfTheDayCommitmentPayloadV1, PickOfTheDayCommitmentPayloadV2.
PickOfTheDayCommitmentPayloadV1
The frozen identity of the pick, exactly as the hash was taken over it. Served byte for byte as it was hashed — keys sorted by UTF-8 byte value, no insignificant whitespace — so a verifier concatenates and hashes with nothing to reconstruct. Property order below is the wire order. The outcome is deliberately NOT part of it: surviving a corrected outcome unchanged is the case the commitment exists for. Worked example: {“backed_price”:“0.545000”,“condition_id”:“0xabc”,“kickoff”:“2026-09-20T23:05:00Z”,“pick_date”:“2026-09-20”,“pick_outcome_index”:1,“pick_outcome_label”:“Lakers”,“pick_rank”:1,“platform”:“polymarket”} with the nonce 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f hashes to 44d18fa5e2aa3a2bf3c971dcc9317c8ccbdfd5480a4773b6d8ffd5fbeeea84dc.| Field | Type | Required | Description |
|---|---|---|---|
backed_price | string | Yes | Frozen pre-game price of the backed side, 0..1, as the plain decimal text of the stored NUMERIC at full stored precision, trailing zeros included. A string, never a number: a float round-trip would change the bytes and break the hash. Deliberately not normalized — 0.545000 stays “0.545000”. |
condition_id | string | Yes | Provider condition id of the backed market. |
kickoff | string | Yes | Frozen provider kickoff, whole seconds, UTC, literal Z. Fixed precision, never a shortest-lossless rendering. |
pick_date | string | Yes | ET product day (YYYY-MM-DD). |
pick_outcome_index | 0 | 1 | Yes | Index of the backed outcome within the market. |
pick_outcome_label | string | Yes | Frozen display label of the backed outcome. |
pick_rank | integer | Yes | 1-based daily slot. |
platform | polymarket | Yes | Provider platform. Always polymarket. |
PickOfTheDayCommitmentPayloadV2
Version 2 rank-free canonical payload: sorted nine keys, unchanged string escaping, exact decimal text and whole-second UTC kickoff. pick_id is decimal text; version is JSON integer 2.| Field | Type | Required | Description |
|---|---|---|---|
backed_price | string | Yes | Frozen pre-game price of the backed side, 0..1, as the plain decimal text of the stored NUMERIC at full stored precision, trailing zeros included. A string, never a number: a float round-trip would change the bytes and break the hash. Deliberately not normalized — 0.545000 stays “0.545000”. |
condition_id | string | Yes | Provider condition id of the backed market. |
kickoff | string | Yes | Frozen provider kickoff, whole seconds, UTC, literal Z. Fixed precision, never a shortest-lossless rendering. |
pick_date | string | Yes | ET product day (YYYY-MM-DD). |
pick_outcome_index | 0 | 1 | Yes | Index of the backed outcome within the market. |
pick_outcome_label | string | Yes | Frozen display label of the backed outcome. |
platform | polymarket | Yes | Provider platform. Always polymarket. |
pick_id | string | Yes | Stable pick row identity as decimal text. Never use a quality rank as identity. |
version | integer | Yes |
PickOfTheDayHitRate
| Field | Type | Required | Description |
|---|---|---|---|
wins | integer | Yes | Number of decided picks that won. |
losses | integer | Yes | Number of decided picks that lost. |
decided | integer | Yes | Number of decided picks (wins + losses); excludes void and pending. |
pct | number | Yes | Rolling hit rate as a percentage (wins / decided * 100, to 1 decimal); 0 when none are decided. |
void | integer | Yes | Number of picks that resolved void (excluded from the hit rate). |
pending | integer | Yes | Number of picks still pending resolution (excluded from the hit rate). |
stake_usd | number | Yes | The flat stake every money figure here assumes, in USD: 1000 since 2026-09-22 (100 before). Always present. |
net_profit_usd | number | Yes | Cumulative profit (USD) of a stake_usd-per-pick strategy over visible valued settled picks: a priced win pays stake_usd/backed_price - stake_usd, every visible loss pays -stake_usd independent of price. A void is not staked and adds nothing. An unpriced visible win and a current non-Insider row whose price is gated remain in wins/losses but are excluded from price-derived totals. |
staked_usd | number | Yes | Total staked (USD) = stake_usd * count of visible valued settled picks: every visible loss and every priced win. Voids, unpriced wins and current non-Insider rows whose price is gated are excluded. |
roi_pct | number | Yes | Return on the staked amount as a percentage (net_profit_usd / staked_usd * 100, to 1 decimal); 0 when nothing is staked. |
net_profit_display | string | Yes | Pre-formatted net profit for display, e.g. “+$100" / "-$40”. Whole dollars, signed, round-then-signed so a rounds-to-zero record reads “+$0" (never "-$0”). Convenience only; net_profit_usd is the source value. |
roi_display | string | Yes | Pre-formatted ROI for display, e.g. “+8.3%” / “-20.0%”. One decimal, signed, round-then-signed so a rounds-to-zero record reads “+0.0%” (never “-0.0%”). Convenience only; roi_pct is the source value. |
win_rate_display | string | Yes | Pre-formatted win rate for display, e.g. “92.3%”. One decimal, unsigned. Convenience only; pct is the source value. |
unit_score | number | No | Cumulative net return in stake units over the same valued win/loss population as net_profit_usd. |
unit_score_display | string | No | Backend-formatted signed cumulative unit score, for example “+1.25u”. Omitted when no valued settled pick contributes to the aggregate. |
clv_pending | integer | Yes | Visible resolved archive rows with no CLV capture disposition yet. |
clv_unavailable | integer | Yes | Visible resolved archive rows with a terminal non-measured CLV disposition. |
clv_state | measured | pending | unavailable | not_applicable | none | Yes | Aggregate CLV state. Counts remain available for mixed measured/pending/unavailable populations. |
clv_eligible | integer | Yes | Visible resolved archive rows with valid basis-specific CLV entry evidence. Known-source bases require CLOB provenance; historical_provider_price_match instead requires source provenance to remain null and the latest provider p entry in the one-hour window at or before publication to match the stored display. |
clv_total | integer | Yes | Every visible resolved archive row, including post-kickoff picks. A price-gated current row is excluded until its backed side becomes visible. |
clv_measured | integer | Yes | Eligible resolved public rows with a measured Polymarket CLOB close. |
clv_applicable | integer | Yes | Visible resolved rows published before kickoff. This is the CLV coverage denominator. |
clv_not_applicable | integer | Yes | Visible resolved rows published after kickoff. These rows remain public but do not enter coverage. |
clv_coverage_pct | number | No | Measured divided by clv_applicable as a percentage. Omitted when clv_applicable is zero. |
clv_coverage_display | string | No | Backend-formatted measured/clv_applicable coverage percentage. |
clv_coverage_explanation | string | No | Backend-owned coverage count text, including the excluded post-kickoff count. |
clv_avg_pct | number | No | Arithmetic mean of per-pick ratio CLV, (close / entry - 1) * 100. A cheap entry weighs more here than a favorite, so the headline average is clv_avg_pp; this field is kept for continuity. Suppressed until at least five measured rows exist. |
clv_avg_display | string | No | Backend-formatted signed average CLV percentage, present when clv_avg_pct is present. |
clv_avg_pp | number | No | Arithmetic mean of the measured closing-line move in percentage points, (close - entry) * 100, so every pick counts on the same scale. The headline CLV average. Covers the same measured rows as clv_avg_pct and is suppressed under the same five-row floor. |
clv_avg_pp_display | string | No | Backend-formatted signed average in percentage points, for example “+0.4 pp”; a value that rounds to zero reads “0.0 pp”. Present when clv_avg_pp is present. |
clv_beats_close | integer | Yes | Measured public rows where close is strictly greater than entry. |
clv_ties | integer | Yes | Measured public rows where close exactly equals entry. |
series | array of object (date, net_profit_usd, hit_rate_pct) | Yes | Cumulative track-record series, one point per decided (win/loss) pick in ascending pick_date order (pending and void picks add no point). A non-valued decided row carries cumulative profit forward while advancing hit rate. The last point’s net_profit_usd and hit_rate_pct equal the headline net_profit_usd and pct by construction. Empty when nothing is decided. |
edge_display | string | No | |
edge_pp | number | No | |
priced_decided | integer | Yes | |
priced_in_display | string | No | |
priced_in_pct | number | No |
PickOfTheDayLedger
The commitment ledger: every published pick, ascending, in the state its commitment is actually in. The counts are derived from entries in the same pass that builds it.| Field | Type | Required | Description |
|---|---|---|---|
entries | array of PickOfTheDayLedgerEntry | Yes | One entry per published (pick_date, pick_rank), ascending by pick_date then pick_rank. |
entry_count | integer | Yes | Number of entries, all states included. |
sealed_count | integer | Yes | Entries committed to and not yet settled. |
opened_count | integer | Yes | Entries committed to and verifiable now. |
uncommitted_count | integer | Yes | Entries carrying no commitment, so provable by nothing: the honest size of the unprovable part of the record. It only stops growing; no pick is ever retro-sealed. |
PickOfTheDayLedgerEntry
One ledger entry. Readstate to know which shape you have; the three are disjoint.
One of: PickOfTheDayLedgerSealedEntry, PickOfTheDayLedgerOpenedEntry, PickOfTheDayLedgerUncommittedEntry. Discriminated by state.
PickOfTheDayLedgerOpenedEntry
A settled pick whose commitment is open: the nonce plus the exact payload the hash was taken over. Concatenate the payload bytes as received with the decoded nonce and sha256 them to reproduce commitment_hash.| Field | Type | Required | Description |
|---|---|---|---|
state | string | Yes | |
pick_date | string | Yes | ET product day the pick belongs to (YYYY-MM-DD). |
pick_rank | integer | Yes | Deprecated compatibility daily release slot; use pick_id for identity and publication_order for scheduling. |
commitment_hash | string | Yes | sha256(canonical_json(payload) || nonce), lowercase hex, no 0x prefix. Publishable the moment the pick releases: without the nonce it is not invertible. |
commitment_nonce | string | Yes | The 32-byte nonce the hash was taken over, lowercase hex, no 0x prefix. Secret while the pick is live: a pick payload is low entropy, so a published nonce on a live pick would hand out the backed side. |
commitment_algo | string | Yes | The construction the hash was taken with, stated in the response so a verifier never has to guess the serialization. |
sealed_at | string | Yes | When the hash was frozen. Always strictly before kickoff: a pick that reaches kickoff unsealed stays unsealed forever, because a seal written after the game started would be a backdated proof. |
resolved_at | string | null | Yes | When outcome was LAST written to a settled value, or null when that instant is unknown. It moves with a corrected market re-mapping an already-settled pick, while commitment_hash stays untouched — which is how a mirror that keeps history sees a correction. |
kickoff | string | Yes | The frozen provider kickoff in the canonical payload form: whole seconds, UTC, literal Z. This exact string reappears inside payload.kickoff when the pick opens. |
payload | PickOfTheDayCommitmentPayload | Yes | |
outcome | win | loss | void | Yes | How the pick settled. Never pending: a pending pick is a sealed entry. |
withdrawal_reason | provider_game_cancelled | published_after_kickoff | null | Yes | Why the site withdrew this pick from its track record, or null when the pick counts. provider_game_cancelled: Polymarket marked the game Cancelled while the pick was pending. published_after_kickoff: the pick was published at or after its game started, including a suspended match that resumed later, so it was never a pre-game pick; this can be set after the pick settled. A withdrawn pick keeps its commitment and its real outcome here, but the site’s record leaves it out of every count and money figure. Not part of the hashed payload, so it never moves commitment_hash. |
withdrawn_at | string | null | Yes | When the site withdrew this pick from its track record, or null when the pick counts. Set beside withdrawal_reason by the same write and never without it, so a reader can tell a correction made after the pick settled (withdrawn_at later than resolved_at) from a withdrawal made while it was pending. null beside a reason only if that instant was not stored. Not part of the hashed payload, so it never moves commitment_hash. |
matchup | string | Yes | Frozen matchup, for a reader. |
category | string | Yes | Frozen canonical sport bucket (for example Basketball or MMA), not the exact public league identity; the archive owns that. |
permalink | string | Yes | The pick’s stable public page, https://0xinsider.com/pick-of-the-day/picks/{pick_id}. |
pick_id | string | Yes | Stable pick row identity as decimal text. Never use a quality rank as identity. |
publication_order | integer | Yes | Compatibility release slot. No quality claim; historic scheduling order is retained. |
is_free_selection | boolean | Yes | Viewer-independent free selection designation. New rows store it explicitly; historic null storage uses the original free slot. |
supersedes_pick_id | string | null | Yes | Deprecated (#24157): always null. No replacement lineage was ever recorded in this field; the key stays so existing V1 clients keep parsing. Identify a pick by pick_id. |
commitment_version | 1 | 2 | Yes | Explicit proof provenance: 1 retains historic eight-field canonical JSON; 2 binds stable pick_id and version without pick_rank. |
PickOfTheDayLedgerSealedEntry
An unresolved published pick. Carries only date, rank, hash, algorithm, seal instant and permalink. Kickoff and game identity are withheld; seal time remains public commitment provenance.| Field | Type | Required | Description |
|---|---|---|---|
state | string | Yes | |
pick_date | string | Yes | ET product day the pick belongs to (YYYY-MM-DD). |
pick_rank | integer | Yes | Deprecated compatibility daily release slot; use pick_id for identity and publication_order for scheduling. |
commitment_hash | string | Yes | sha256(canonical_json(payload) || nonce), lowercase hex, no 0x prefix. Publishable the moment the pick releases: without the nonce it is not invertible. |
commitment_algo | string | Yes | The construction the hash was taken with, stated in the response so a verifier never has to guess the serialization. |
sealed_at | string | Yes | When the hash was frozen. Always strictly before kickoff: a pick that reaches kickoff unsealed stays unsealed forever, because a seal written after the game started would be a backdated proof. |
permalink | string | Yes | The pick’s stable public page, https://0xinsider.com/pick-of-the-day/picks/{pick_id}. |
pick_id | string | Yes | Stable pick row identity as decimal text. Never use a quality rank as identity. |
publication_order | integer | Yes | Compatibility release slot. No quality claim; historic scheduling order is retained. |
is_free_selection | boolean | Yes | Viewer-independent free selection designation. New rows store it explicitly; historic null storage uses the original free slot. |
supersedes_pick_id | string | null | Yes | Deprecated (#24157): always null. No replacement lineage was ever recorded in this field; the key stays so existing V1 clients keep parsing. Identify a pick by pick_id. |
commitment_version | 1 | 2 | Yes | Explicit proof provenance: 1 retains historic eight-field canonical JSON; 2 binds stable pick_id and version without pick_rank. |
PickOfTheDayLedgerUncommittedEntry
A pick without a commitment, retained so the record cannot omit unprovable entries. Unresolved entries omit game identity; once resolved, matchup, category and payload become public. Existing opened canonical payload bytes and hashes are unchanged.| Field | Type | Required | Description |
|---|---|---|---|
state | string | Yes | |
pick_date | string | Yes | ET product day the pick belongs to (YYYY-MM-DD). |
pick_rank | integer | Yes | Deprecated compatibility daily release slot; use pick_id for identity and publication_order for scheduling. |
pre_commitment | boolean | Yes | Always true: this pick has no commitment and never will. |
outcome | pending | win | loss | void | Yes | How the pick settled, or pending. |
withdrawal_reason | provider_game_cancelled | published_after_kickoff | null | No | Omitted while the pick is pending; once it settles, why the site withdrew it from its track record, or null when the pick counts. provider_game_cancelled: Polymarket marked the game Cancelled while the pick was pending. published_after_kickoff: the pick was published at or after its game started, including a suspended match that resumed later, so it was never a pre-game pick; this can be set after the pick settled. A withdrawn pick stays here with its real outcome, but the site’s record leaves it out of every count and money figure. |
withdrawn_at | string | null | No | Omitted while the pick is pending; once it settles, when the site withdrew it from its track record, or null when the pick counts. Set beside withdrawal_reason by the same write and never without it, so a reader can tell a correction made after the pick settled (withdrawn_at later than resolved_at) from a withdrawal made while it was pending. null beside a reason only if that instant was not stored. |
matchup | string | No | Frozen matchup, for a reader. |
category | string | No | Frozen canonical sport bucket (for example Basketball or MMA), not the exact public league identity; the archive owns that. |
resolved_at | string | null | Yes | When outcome was LAST written to a settled value, or null when that instant is unknown. It moves with a corrected market re-mapping an already-settled pick, while commitment_hash stays untouched — which is how a mirror that keeps history sees a correction. |
payload | PickOfTheDayUncommittedPayload or null | Yes | The pick’s market, side and price once it has settled; null while it is pending, and null for a settled pick whose stored row lacks one of these columns. Not hashed: nothing was committed over these values, which is what pre_commitment: true says. |
permalink | string | Yes | The pick’s stable public page, https://0xinsider.com/pick-of-the-day/picks/{pick_id}. |
pick_id | string | Yes | Stable pick row identity as decimal text. Never use a quality rank as identity. |
publication_order | integer | Yes | Compatibility release slot. No quality claim; historic scheduling order is retained. |
is_free_selection | boolean | Yes | Viewer-independent free selection designation. New rows store it explicitly; historic null storage uses the original free slot. |
supersedes_pick_id | string | null | Yes | Deprecated (#24157): always null. No replacement lineage was ever recorded in this field; the key stays so existing V1 clients keep parsing. Identify a pick by pick_id. |
PickOfTheDayMarketExpectations
| Field | Type | Required | Description |
|---|---|---|---|
as_of_date | string | Yes | |
price_basis | string | Yes | |
timezone | string | Yes | |
windows | array of object (clv_avg_display, clv_avg_pct, clv_avg_pp, clv_avg_pp_display, clv_measured, clv_missing, expected_wins, expected_wins_display, from_date, key, label, numeric_unavailable, priced_decided, through_date, units, units_display, units_z, units_z_display, unpriced_decided, wins, wins_z, wins_z_display) | Yes |
PickOfTheDayNoEntitledPicks
A successful current-day entitlement response when only unauthorized ranks have published. It carries an empty pick set, identity-free locked ranks and an upgrade message. Selection IDs, game identity, prices and unauthorized clocks are absent. Any scheduled or proof-pending rows are entitled rows.| Field | Type | Required | Description |
|---|---|---|---|
state | none | Yes | Only locked ranks are published for this account. |
pick_date | string | Yes | Current product date in America/New_York (YYYY-MM-DD). |
picks | array of PickOfTheDay | Yes | Empty: no entitled proof-readable picks are returned. |
pick_count | integer | Yes | Zero entitled proof-readable picks. |
locked_picks | array of object (pick_rank, required_tier) | Yes | Unauthorized unresolved published or scheduled ranks. Contains no game, provider identity, price, or identifying clock. Pro may upgrade to Max to open these ranks. |
message | string | Yes | Actionable status, including Upgrade to Max when only locked ranks are published. |
scheduled_picks | array of ScheduledPickSlot | No | Rank-ordered entitled selections that have not released. Every row retains release_at and kickoff; unauthorized scheduled ranks appear only in identity-free locked_picks. |
supersedes_pick_id | string | null | Yes | Deprecated (#24157): always null. No replacement lineage was ever recorded in this field; the key stays so existing V1 clients keep parsing. Identify a pick by pick_id. |
more_picks_until | string | No | The instant until which today’s list of published picks can still grow: present while another pick can still be added to the day, absent once the day is final. A later pick is possible, not promised. |
PickOfTheDayOutcomeStats
| Field | Type | Required | Description |
|---|---|---|---|
concentration | object (positive_wins, remaining_valued_decided, removed_wins, roi_without_top_wins_display, roi_without_top_wins_pct, target_wins, top_wins_share_display, top_wins_share_pct, valued_decided) | Yes | |
drawdown | object (completed_days, current_days_below_peak, current_drawdown_display, current_drawdown_units, days_below_peak, excluded_days, from_date, longest_days_below_peak, longest_recovery_days, max_drawdown_display, max_drawdown_units, peak_date, peak_net_profit_usd, through_date) | Yes | |
profit_factor | object (display, gross_loss_usd, gross_profit_usd, state, value, valued_decided) | Yes | |
rolling | array of object (from_date, losses, roi_display, roi_pct, through_date, units, units_display, valued_decided, win_rate_display, win_rate_pct, window_size, wins) | Yes |
PickOfTheDayStats
| Field | Type | Required | Description |
|---|---|---|---|
categories | array of PickOfTheDayStatsBucket | Yes | |
days | array of PickOfTheDayStatsDay | Yes | |
hit_rate | PickOfTheDayHitRate | Yes | |
market_expectations | PickOfTheDayMarketExpectations | Yes | |
market_types | array of PickOfTheDayStatsBucket | Yes | |
months | array of PickOfTheDayStatsBucket | Yes | |
outcome_stats | PickOfTheDayOutcomeStats | Yes | |
price_bands | array of PickOfTheDayStatsBucket | Yes | |
records | PickOfTheDayStatsRecords | Yes | |
sports | array of PickOfTheDayStatsBucket | Yes | |
streaks | PickOfTheDayStatsStreaks | Yes | |
tiers | array of PickOfTheDayStatsBucket | Yes | |
total_sides | array of PickOfTheDayStatsBucket | Yes | |
voids | array of PickOfTheDayStatsVoid | Yes | |
ask_comparison | PickOfTheDayAskComparison | Yes |
PickOfTheDayStatsBucket
| Field | Type | Required | Description |
|---|---|---|---|
canonical_category | string | No | |
clv_avg_display | string | No | |
clv_avg_pct | number | No | |
clv_avg_pp | number | No | |
clv_avg_pp_display | string | No | |
clv_measured | integer | Yes | |
edge_display | string | No | |
edge_pp | number | No | |
key | string | Yes | |
label | string | Yes | |
losses | integer | Yes | |
net_profit_display | string | No | |
net_profit_usd | number | No | |
pending | integer | Yes | |
picks | integer | Yes | |
priced_decided | integer | Yes | |
priced_in_display | string | No | |
priced_in_pct | number | No | |
roi_display | string | No | |
roi_pct | number | No | |
settled | integer | Yes | |
small_sample | boolean | Yes | |
staked_usd | number | Yes | |
unit_score | number | No | |
unit_score_display | string | No | |
void | integer | Yes | |
win_rate_display | string | No | |
win_rate_pct | number | No | |
wins | integer | Yes |
PickOfTheDayStatsDay
| Field | Type | Required | Description |
|---|---|---|---|
date | string | Yes | |
losses | integer | Yes | |
net_profit_display | string | No | |
net_profit_usd | number | No | |
pending | integer | Yes | |
picks | integer | Yes | |
sweep | win | loss | No | |
unit_score | number | No | |
unit_score_display | string | No | |
void | integer | Yes | |
wins | integer | Yes |
PickOfTheDayStatsRecords
| Field | Type | Required | Description |
|---|---|---|---|
best_day | object (date, date_display, losses, net_profit_display, net_profit_usd, picks, wins) | No | |
biggest_win | object (category, date, date_display, matchup, net_profit_display, net_profit_usd) | No | |
longest_losing_day_streak | object (days, end_date, net_profit_display, net_profit_usd, range_display, start_date) | No | |
longest_winning_day_streak | object (days, end_date, net_profit_display, net_profit_usd, range_display, start_date) | No | |
sweeps | object (clean_sweeps, latest_clean_sweep, latest_wipeout, min_decided, wipeouts) | Yes | |
winning_days | object (flat, losing, settled, winning, winning_pct, winning_pct_display) | No | |
worst_day | object (date, date_display, losses, net_profit_display, net_profit_usd, picks, wins) | No |
PickOfTheDayStatsSections
The stats withview=summary or sections: only the named sections, listed in sections. view=summary names every section except series, days, categories, months and voids.
| Field | Type | Required | Description |
|---|---|---|---|
categories | array of PickOfTheDayStatsBucket | No | |
days | array of PickOfTheDayStatsDay | No | |
hit_rate | object (clv_applicable, clv_avg_display, clv_avg_pct, clv_avg_pp, clv_avg_pp_display, clv_beats_close, clv_coverage_display, clv_coverage_explanation, clv_coverage_pct, clv_eligible, clv_measured, clv_not_applicable, clv_pending, clv_state, clv_ties, clv_total, clv_unavailable, decided, losses, net_profit_display, net_profit_usd, pct, pending, roi_display, roi_pct, stake_usd, staked_usd, unit_score, unit_score_display, void, win_rate_display, wins, edge_display, edge_pp, priced_decided, priced_in_display, priced_in_pct) | No | |
market_expectations | PickOfTheDayMarketExpectations | No | |
market_types | array of PickOfTheDayStatsBucket | No | |
months | array of PickOfTheDayStatsBucket | No | |
outcome_stats | PickOfTheDayOutcomeStats | No | |
price_bands | array of PickOfTheDayStatsBucket | No | |
records | PickOfTheDayStatsRecords | No | |
sections | array of string | Yes | |
series | array of object (date, hit_rate_pct, net_profit_usd) | No | |
sports | array of PickOfTheDayStatsBucket | No | |
streaks | PickOfTheDayStatsStreaks | No | |
tiers | array of PickOfTheDayStatsBucket | No | |
total_sides | array of PickOfTheDayStatsBucket | No | |
view | string | Yes | |
voids | array of PickOfTheDayStatsVoid | No | |
ask_comparison | PickOfTheDayAskComparison | No |
PickOfTheDayStatsStreaks
| Field | Type | Required | Description |
|---|---|---|---|
current | integer | No | |
current_day | integer | No | |
current_day_display | string | No | |
current_display | string | No | |
longest_loss | integer | Yes | |
longest_win | integer | Yes |
PickOfTheDayStatsVoid
| Field | Type | Required | Description |
|---|---|---|---|
backed_price | number | No | |
backed_side | string | No | |
category | string | No | |
matchup | string | No | |
pick_date | string | Yes | |
pick_id | string | Yes | |
pick_rank | integer | Yes |
PickOfTheDayUncommittedPayload
A settled uncommitted pick’s market, side and price. The same eight fields as PickOfTheDayCommitmentPayload, in the same key order, so a settled pick’s side and price sit under payload whatever the entry’s state. It is NOT a commitment: no hash was taken over it before the game, and it proves nothing about when the pick was made.| Field | Type | Required | Description |
|---|---|---|---|
backed_price | string | Yes | Frozen pre-game price of the backed side, 0..1, as the plain decimal text of the stored NUMERIC at full stored precision, trailing zeros included — rendered exactly as the commitment payload renders it. |
condition_id | string | Yes | Provider condition id of the backed market. |
kickoff | string | null | Yes | Frozen provider kickoff, UTC, literal Z; null when no kickoff was frozen. Whole seconds render exactly as the commitment payload does; a sub-second instant keeps its fraction rather than being truncated, since nothing here is hashed. |
pick_date | string | Yes | ET product day (YYYY-MM-DD). |
pick_outcome_index | 0 | 1 | Yes | Index of the backed outcome within the market. |
pick_outcome_label | string | Yes | Frozen display label of the backed outcome. |
pick_rank | integer | Yes | 1-based daily slot. |
platform | polymarket | Yes | Provider platform. Always polymarket. |
PickSportsContext
Provider-first sports context for a Pick of the Day market: team crests, league branding, and live score. Each teamlogo is a registered club crest or national flag as a same-origin path where one exists, and provider artwork otherwise.
| Field | Type | Required | Description |
|---|---|---|---|
league_name | string | null | Yes | League or competition display name (e.g. “Premier League”). |
competition_label | string | No | Provider-owned event taxonomy from Gamma eventMetadata, joined in league · serie · tournament order with blanks and case-insensitive duplicates removed. A tennis qualifying match ends in ”, Qualification”, including an ATP Challenger qualifying match, which Gamma marks only in eventMetadata.tennisFixtureSource. Separate from league_name; omitted when the provider does not supply the metadata. |
league_logo | string | null | Yes | League logo URL (provider-owned). |
yes_team | PickSportsTeam or null | Yes | The team mapped to the market’s YES outcome, or the game’s first team when event_matchup is true. To lay the two teams out in the game’s order, read side_order. |
no_team | PickSportsTeam or null | Yes | The team mapped to the market’s NO outcome, or the game’s second team when event_matchup is true. |
game_id | integer | No | Provider game identifier (Polymarket Gamma gameId); omitted when the provider supplies none. |
event_matchup | boolean | Yes | Always present. True when the two teams are the parent-event match identity for a teamless binary leg (e.g. a draw, totals, or prop market), not the market’s own outcomes. |
event_subject_team | PickSportsTeam | No | Present only alongside event_matchup: the event team the binary leg is about (provider group_item_title matched to a matchup team, e.g. Belgium for “Will Belgium win?”), i.e. the winner on a Yes resolution. Omitted for teamless legs (draw, totals, prop). |
side_order | yes_first | no_first | No | Which of yes_team and no_team the game lists first, in Polymarket’s order for the event (the order of its title: the away team first in US leagues, the home team first in soccer). yes_first when yes_team is the first team, no_first when no_team is. A spread’s Yes side is the favorite, so it is often the game’s second team. Lay the teams out in this order to show every pick on one game the same way; yes_team and no_team keep their Yes and No meaning. Omitted when the order is unknown: lay out yes_team first. |
matchup_title | string | No | The two teams as a single whole-game label, joined “<first> – <second>” (en-dash) in the game’s order, the order side_order names (e.g. “LA Clippers – Phoenix Suns”), so every pick on one game carries the same title. Composed server-side from the provider team names (no title/slug parsing). Present when both teams resolve a name; omitted for single-subject, teamless, or non-two-team contexts. |
PickSportsTeam
A single sports team or competitor in a Pick of the Day market’s sports context. Identity and score fields are provider-owned and nullable. The structured score fields (sets, format, sets_won) and the tennis fields (headshot, headshot_revision, tour) are backend-owned and are OMITTED rather than null when they do not apply, so a consumer must treat an absent key and a null the same way.
| Field | Type | Required | Description |
|---|---|---|---|
label | string | null | Yes | Team display label as it appears on the market outcome (e.g. “Portugal”). |
short_label | string | null | Yes | The team’s abbreviation in upper case (e.g. “POR”), the same on every market of the game. A competitor Polymarket gives no abbreviation can carry its name here instead. |
full_name | string | null | Yes | The name to show for this team or competitor, the same on every surface (e.g. “UCF Knights”, “Oklahoma City Thunder”, “Portugal”). label keeps the market outcome’s own spelling. |
provider_id | integer | null | Yes | Provider team identifier (Polymarket /teams id). |
logo | string | null | Yes | Team crest or flag URL. Official NFL (32), WNBA (15), NBA (30), NHL (32), and MLB (30) club crests use same-origin relative paths (/api/sports/team-logos/{league}/{abbr}.svg?v=<content hash>); resolve relative URLs against the API origin. Vendored soccer club crests use the same path with .png. National teams in the registered national-team competitions use the same path with .svg: the official national flag, drawn whole at its own aspect. Other teams use provider artwork, including country flags for tennis players. Novelty rows, and national-team rows that are not exactly one country, retain provider artwork. |
logo_mark_dark | boolean | Yes | True when artwork measurements show that the team mark needs a light plate on a dark background. Vendored crest verdicts are tied to the exact asset bytes; provider artwork is measured by the teams sync. Always sent; false when no current measurement marks the logo dark. |
color | string | null | Yes | Team brand color as a hex string (provider-owned). |
record | string | null | Yes | Win-loss record as a display string (e.g. “12-4”). |
score | string | null | Yes | Live or final score as a display string when the game is in play or settled. |
headshot | string | No | Tennis player headshot URL, served same-origin. Present only for a tennis competitor the headshot resolver matched; absent for team sports and for unmatched players, where logo stays the fallback. |
tour | atp | wta | itf | No | Tennis tour this competitor belongs to. Present for every tennis entry whether or not headshot resolved, so a consumer can tell a tennis player with no photo from a non-tennis team. Absent for every other sport. Only atp and wta name a gender; the ITF World Tennis Tour runs men’s and women’s events and the provider does not say which, so itf means tennis with gender unknown. |
sets | array of ScoreCell | No | Per-set score cells for this side, in set order. Backend-owned: render these rather than parsing score. Omitted entirely when the provider score is not a structured multi-set match or could not be parsed, so an absent array and an empty one carry the same meaning. |
format | ScoreFormat | No | |
sets_won | integer | No | Completed sets won by this side. Present only when both sides expose the same set columns, so a partially parsed scoreline reports no tally rather than a misleading one. |
headshot_revision | integer | No | Optional monotonic photo revision for this tennis player, independent of the sports score revision. Legacy stored photos start at zero. Successful new or changed image bytes advance it; source checks and attribution changes do not. Compare only for the same tour and provider_id: a higher revision replaces the portrait, an equal revision may fill a missing portrait, and a lower revision must not replace a newer one. Absent when no photo resolved. |
ranking | TennisRanking | No | Optional latest retrieved ATP/WTA singles rank for this player. Absent for unranked, ambiguous, doubles, expired, or unavailable identities. This is not rank at match time. |
logo_mark_light | boolean | Yes | True when artwork measurements show that the team mark disappears on a white background and needs a dark plate there: the light-background twin of logo_mark_dark. Vendored crest verdicts are tied to the exact asset bytes; provider artwork is measured on white by the teams sync. Always sent; false when no current measurement marks the logo light. |
logo_mark_measured | boolean | Yes | True when logo_mark_dark and logo_mark_light are both measurements of this exact logo URL, so their false means the mark is legible on that background. Every vendored crest is measured; a provider logo is measured once the teams sync has scored it, usually within a few hourly cycles of first appearing. Always sent; false while the logo is not measured yet. |
PlatformCapabilities
| Field | Type | Required | Description |
|---|---|---|---|
grade | PlatformCapabilityStatus | Yes | |
pnl | PlatformCapabilityStatus | Yes | |
strategy | PlatformCapabilityStatus | Yes | |
timeline | PlatformCapabilityStatus | Yes | |
large_trades | PlatformCapabilityStatus | Yes | The large-trade feed. Canonical key since #16304; whale_signal is its deprecated spelling, emitted beside it with the same value until its sunset on 2027-02-01 (#29352). |
whale_signal | PlatformCapabilityStatus | Yes | Deprecated spelling of large_trades, emitted beside it with the same value. Sunset 2027-02-01 (#29352): removed from V1 on that date; read large_trades. |
suspicious_trades | PlatformCapabilityStatus | Yes | |
insider_radar | PlatformCapabilityStatus | Yes | Deprecated spelling of suspicious_trades, emitted beside it with the same value. Sunset 2027-02-01 (#29352): removed from V1 on that date; read suspicious_trades. |
market_snapshot | PlatformCapabilityStatus | Yes |
PlatformCapabilityStatus
Every capability the API serves reports supported. The field names a per-capability status so a client can branch on coverage; no other value is emitted. String enum:supported.
Platforms
| Field | Type | Required | Description |
|---|---|---|---|
platforms | object (polymarket) | Yes |
PnlCorrection
A derived 0xinsider correction to Polymarket’s P&L, never a Polymarket value. Polymarket misbooks neg-risk conversions, in both directions: it puts cost on placeholder YES outcomes minted by a conversion and never books it as a loss (negative amount), and its position records leave out shares the wallet really got, such as YES minted by a conversion, so it books no P&L on them (positive amount). Per neg-risk market the wallet converted in, 0xinsider measures Polymarket’s own activity cash against the sum of its position P&L, and sums the difference over every measured market whose shares did not move by direct transfer: transferred shares have no activity row, so such a market keeps Polymarket’s figure and is counted in markets_excluded. It is published once every neg-risk market with a sports or esports event that the wallet converted in is measured and checked for transfers, and stays as last published until then; a market with no sports or esports event is not measured, and counts only when it was measured before (on the trader body, pnl.correction_pending says so); a sum under $1 either way publishes nothing. The body’s own P&L fields keep Polymarket’s figures; this object adds the amount and the corrected figures. Money is truncated toward zero to cents.| Field | Type | Required | Description |
|---|---|---|---|
basis | neg_risk_conversion_v1 | Yes | The correction method. |
amount | number | Yes | The correction in USD. Negative when Polymarket overstates the wallet. |
realized | number | No | Polymarket’s net realized P&L plus amount. Since 2026-10-22 the grade reads this figure’s sports and esports share. Omitted when Polymarket’s figure is. |
net_total | number | No | Polymarket’s net total P&L over every Polymarket market of the wallet, plus amount. Omitted when Polymarket’s figure is, and on leaderboard entries. |
as_of | string | Yes | The newest measurement among the measured markets. |
markets_measured | integer | Yes | Neg-risk markets whose measurement amount sums. |
markets_excluded | integer | No | Measured neg-risk markets left out because shares moved in or out of the wallet by direct transfer; they keep Polymarket’s figure. Omitted when none. |
Position
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Composite prefixed ID pos_<wallet>:<condition_id>:<outcome_index>. |
platform | polymarket | Yes | Provider discriminator. Polymarket only. |
wallet | string | Yes | Lowercased proxy wallet address. |
side | YES | NO | Yes | Binary outcome side. Non-binary positions are not surfaced on V1. |
token_id | string | null | Yes | The Polymarket CLOB token id (ERC1155 asset id, decimal string) for this outcome; null when unavailable (e.g. unsynced markets). |
shares | number | Yes | Live share count from the wallet_positions mirror. |
avg_price | number | No | Volume-weighted entry price for this leg. |
current_value_usd | number | Yes | Current mark-to-market value in USD (always non-null on V1 — pre-reconcile rows are excluded). |
initial_value_usd | number | No | |
cash_pnl | number | No | Unrealized P&L for the open position (Polymarket cashPnl). |
realized_pnl | number | No | Closed-leg P&L rolled up (Polymarket realizedPnl). |
exact | PositionExact | No | Additive lossless source atoms for the display-safe position fields. Parse every value with decimal-safe arithmetic; never recover exact values from the numeric twins. |
last_reconciled_at | string | No | Max updated_at across mirror legs for this pair. |
freshness | fresh | refreshing | stale | unknown | Yes | Backend-computed staleness bucket derived from last_reconciled_at. |
trader | object (id, address, username, grade, win_rate, pnl, in_scope_realized_pnl, markets, first_trade_at, wallet_age_days, is_new_wallet, markets_decided, win_rate_status) | Yes | |
market | object (id, condition_id, title, slug, event_slug, category, outcome_label, end_date, protocol_version) | Yes |
PositionExact
Lossless position atoms fromwallet_positions. shares and current_value_usd are required when this object is present; other source values are omitted when the mirror has no verified value.
| Field | Type | Required | Description |
|---|---|---|---|
shares | ExactDecimal | Yes | |
cost_basis_usd | ExactDecimal | No | |
avg_price | ExactDecimal | No | Exact derived price: wallet_positions.cost_basis_usd / wallet_positions.shares. |
current_value_usd | ExactDecimal | Yes | |
initial_value_usd | ExactDecimal | No | |
cash_pnl | ExactDecimal | No | |
realized_pnl | ExactDecimal | No |
PositionTimelineEvent
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Opaque fill id (fill_…). Responses before #33245 carried pe_… ids, which no longer match. |
event_timestamp | string | Yes | ISO 8601 timestamp of the on-chain fill. |
action | buy | sell | Yes | The wallet’s own side of this fill: buy or sell. |
outcome_side | yes | no | Yes | |
token_id | string | null | Yes | The Polymarket CLOB token id (ERC1155 asset id, decimal string) for this outcome; null when unavailable (e.g. unsynced markets). |
amount_delta | number | Yes | Signed share delta (+ on buy, − on sell). |
price | number | Yes | Fill price in USDC per share, in [0,1]. |
usdc_notional | number | Yes | Positive USDC notional of the fill. |
tx_hash | string | null | Yes | Polygon transaction hash of the fill, from the large-trade alert recorded for it. null for a fill with no such alert: the fill ledger stores no transaction hash (#33245). |
running_amount | number | Yes | Cumulative signed stored-fill amount for this outcome after this fill, including older pages. Stable across limits/cursors for unchanged source history. Excludes split, merge, redemption and neg-risk activity; not complete holdings. Incomplete fill history can also leave a negative amount. |
running_avg_price | number | Yes | Cumulative buy-weighted average of stored fills for this outcome, including older pages; not provider current-position avgPrice. Sells do not change this value. 0 when no stored buys have occurred yet. |
protocol_version | v1 | v2 | Yes | The Polymarket protocol the market trades on, Gamma’s market version: v1 (CTF, ConditionalTokens) or v2 (Protocol V2). Read from the condition id, the same value GET /api/v1/markets/settled serves. On a v2 market an outcome’s token_id is its V2 position id: sign its orders for ExchangeV3 and read its balance as CONDITIONAL-V2. |
PotdEntryAuthorization
Returned entry permission bound to the named market, token and outcome. Honor the immutable max_entry_price and expires_at, and quote a current executable book for the actual stake. The submitted order price must remain within the returned limit; fills may be lower. Fees are separate, and this grant does not guarantee liquidity, execution or positive expected value.| Field | Type | Required | Description |
|---|---|---|---|
version | 1 | Yes | |
authorization_id | string | Yes | |
policy_version | 7 | 8 | Yes | Identifier for the policy recorded with this authorization. It does not replace the returned max_entry_price or expires_at. Existing grants retain their recorded values. |
condition_id | string | Yes | |
token_id | string | Yes | |
outcome_index | 0 | 1 | Yes | |
category | string | Yes | Canonical sport bucket, not display_category. |
canonical_event_id | string | Yes | Exact provider parent event ID, or provider event ID when no parent exists. |
max_entry_price | string | Yes | Maximum authorized order price as an exact decimal string, excluding fees. Quote a current executable book for the actual stake and keep the submitted order price at or below this bound. Actual fills may be lower; this limit does not guarantee a fill or define fair probability. |
reference_best_ask | string | Yes | Selected-token best ask from the recorded reference book at issuance. This is a reference quote, not the authorized order-price limit; use max_entry_price for that limit. |
reference_book_hash | string | Yes | |
reference_book_at | string | Yes | |
issued_at | string | Yes | |
expires_at | string | Yes | Authorization expiry timestamp. Existing grants do not extend; an expired authorization cannot authorize a new automated entry. |
PriceMoveOutcomeAfter
What outcome 0’s midpoint did after the move, read from the live order book: two-sided with a spread of 10 cents or less. Each checkpoint is measured (mid and its read time), unavailable (unavailable_reason), or pending. Null never means 0.| Field | Type | Required | Description |
|---|---|---|---|
status | pending | final | Yes | pending: a checkpoint is not due yet, or due and not read yet. final: every checkpoint is measured or unavailable, and nothing here changes again. |
mid_15m | string | null | Yes | Outcome 0’s midpoint at the first read at or after detected_at + 15 minutes, as a decimal string; null until measured or when unavailable. |
mid_15m_at | string | null | Yes | When the 15-minute midpoint was read. |
held_15m | boolean | null | Yes | Whether the 15-minute midpoint kept at least half of the move; null when not measured. |
mid_15m_unavailable_reason | no_quote | missed | null | Yes | no_quote: no two-sided quote with a spread of 10 cents or less at the checkpoint (an empty or one-sided book, a settled market). missed: no read landed within 5 minutes of the checkpoint. |
mid_60m | string | null | Yes | As mid_15m, at detected_at + 60 minutes. |
mid_60m_at | string | null | Yes | When the 60-minute midpoint was read. |
held_60m | boolean | null | Yes | Whether the 60-minute midpoint kept at least half of the move; null when not measured. |
mid_60m_unavailable_reason | no_quote | missed | null | Yes | As mid_15m_unavailable_reason. |
mid_kickoff | string | null | Yes | As mid_15m, at the market’s scheduled kickoff, for a pre-game move only. |
mid_kickoff_at | string | null | Yes | When the kickoff midpoint was read. |
held_kickoff | boolean | null | Yes | Whether the kickoff midpoint kept at least half of the move; null when not measured and for every move that was not pre-game. |
mid_kickoff_unavailable_reason | no_quote | missed | not_pre_game | no_scheduled_start | null | Yes | no_quote and missed as for mid_15m_unavailable_reason. not_pre_game: the move was in play or its phase unknown, so it has no kickoff checkpoint. no_scheduled_start: the market had no scheduled kickoff after the move. |
PriceMoveSubscriptionFilters
Settings for market_price_moved: required when event_types includes it, refused (400) when it does not. A PATCH without it keeps the stored settings; removing the event clears them. A subscription receives at most one delivery per market per window: the one level step whose (previous_level_cents, level_cents] holds min_move_cents.| Field | Type | Required | Description |
|---|---|---|---|
min_move_cents | integer | Yes | Move threshold in whole cents of outcome 0’s midpoint. |
window_seconds | 60 | 120 | 300 | 900 | Yes | The window the move is measured over. |
condition_id | string | No | One market only. Raw or mkt_-prefixed. |
event_slug | string | No | One Polymarket event (game) only. |
league | array of string | No | Event slug league prefixes such as nba or epl, matched case-insensitively; any one matches. |
phase | any | pre_game | in_play | Yes | Game phase when the move was detected. any includes unknown. |
require_concurrent_sharp_flow | boolean | Yes | Deliver only moves with concurrent_sharp_flow.detected true. |
min_book_usd_within_2c | integer | No | Deliver only moves whose book_depth_within_2c is known and holds at least this many USD on each side. A move with book_depth_within_2c null does not match. |
ProofPendingPickSlot
One PUBLISHED same-day pick whose holder proof is not readable yet: its stable slot rank, the release and kickoff instants, and the instant before which a retry cannot succeed. Every item inpicks carries its full required shape, so a pick that cannot meet it is listed here instead of being served with missing fields or a synthetic zero.
| Field | Type | Required | Description |
|---|---|---|---|
pick_rank | integer | Yes | Deprecated compatibility daily release slot; use pick_id for identity and publication_order for scheduling. |
release_at | string | Yes | The pick’s stored release instant. |
kickoff | string | No | The backed game’s frozen kickoff instant; absent for a legacy row without one. |
retry_at | string | Yes | Recommended next read: 30 seconds ahead while pre-game proof is warming, one hour ahead for a post-kickoff pending legacy row that only settlement can make readable. Schedule against it instead of polling. |
pick_id | string | Yes | Stable pick row identity as decimal text. Never use a quality rank as identity. |
publication_order | integer | Yes | Compatibility release slot. No quality claim; historic scheduling order is retained. |
is_free_selection | boolean | Yes | Viewer-independent free selection designation. New rows store it explicitly; historic null storage uses the original free slot. |
supersedes_pick_id | string | null | Yes | Deprecated (#24157): always null. No replacement lineage was ever recorded in this field; the key stays so existing V1 clients keep parsing. Identify a pick by pick_id. |
ReportPayload
| Field | Type | Required | Description |
|---|---|---|---|
total_large_trades | integer | null | Yes | Canonical key since #16304; total_whale_trades is its deprecated spelling, emitted beside it with the same value until its sunset on 2027-02-01 (#29352). |
total_whale_trades | integer | null | Yes | |
total_large_trade_volume | number | null | Yes | Canonical key since #16304; total_whale_volume is its deprecated spelling, emitted beside it with the same value until its sunset on 2027-02-01 (#29352). |
total_whale_volume | number | null | Yes | |
biggest_trade_size | number | null | Yes | |
active_traders | integer | null | Yes | |
top_large_trades | array of object (outcome, side, title, size, price, token_id, id, trade_time, market_category, platform, name, pseudonym, trader_grade, condition_id, protocol_version) | null | Yes | Canonical key since #16304; top_whale_trades is its deprecated spelling, emitted beside it with the same value until its sunset on 2027-02-01 (#29352). |
top_whale_trades | array of object (outcome, side, title, size, price, token_id, id, trade_time, market_category, platform, name, pseudonym, trader_grade, condition_id, protocol_version) | null | Yes | |
categories | array of object (category, large_trade_count, whale_trade_count, category_volume) | null | Yes | |
grade_distribution | array of object (grade, count) | null | Yes | Counts of current grades for distinct Polymarket traders with at least one whale alert in the report’s source date range. The grade is the current projection at snapshot materialization time, not a historical grade at trade time. Traders without a current ranking projection are omitted; a null grade entry means the active trader’s current grade is unavailable. |
market_scope | all_markets | sports_and_esports | Yes | Which markets the report counts. sports_and_esports: totals, categories, top trades and the grade cohort cover sports and esports markets only. Every period that ends on or after 2026-10-21 and every custom from/to range says so, as does an earlier stored period first built after 2026-10-24. all_markets: an earlier stored period built before then, which keeps every Polymarket market it published. A custom range can therefore count fewer trades than the stored report of the same dates. |
ReportReconciliation
| Field | Type | Required | Description |
|---|---|---|---|
volume_kind | string | Yes | |
whale_volume_source | string | Yes | Where the whale volume in this report is read from: the column name whale_alerts.usdc_notional_num, followed in parentheses by the reconciliation note the server attaches to it. The server has always sent the note with the name, so this is not a bare constant; match on the prefix, not the whole string. |
notes | string | Yes |
ReportSnapshot
| Field | Type | Required | Description |
|---|---|---|---|
kind | daily | weekly | monthly | Yes | |
generated_at | string | Yes | |
source_range | ReportSourceRange | Yes | |
snapshot | SnapshotState | Yes | |
completeness | SnapshotCompleteness | Yes | |
reconciliation | ReportReconciliation | Yes | |
report | ReportPayload | Yes |
ReportSourceRange
| Field | Type | Required | Description |
|---|---|---|---|
start_date | string | Yes | |
end_date | string | Yes | |
timezone | string | Yes |
ResolutionReport
| Field | Type | Required | Description |
|---|---|---|---|
accuracy | number | null | Yes | |
all_wallets_accuracy | number | null | Yes | |
all_wallets_right | integer | null | Yes | |
all_wallets_wrong | integer | null | Yes | |
date | string | null | Yes | |
generated_at | string | null | Yes | |
grade_basis | object | Yes | |
market_scope | all_markets | sports_and_esports | Yes | |
markets | array of object (all_wallets_right, category, condition_id, confidence, event_slug, out_of_product_scope, outcome_no, outcome_yes, report_at, smart_consensus, smart_right, smart_trader_count, time_basis, title, total_smart_pnl, traders, weighted_no, weighted_yes, winning_outcome) | No | |
markets_without_smart_positions | integer | null | Yes | |
no_consensus | integer | null | Yes | |
positions_grade_unknown | integer | null | Yes | |
positions_without_side | integer | null | Yes | |
smart_money_right | integer | null | Yes | |
smart_money_wrong | integer | null | Yes | |
source_updates_pending | boolean | Yes | |
time_basis_counts | object | Yes | |
total_resolved | integer | null | Yes | |
total_smart_pnl | number | null | Yes | |
with_smart_positions | integer | null | Yes |
ResponseMeta
| Field | Type | Required | Description |
|---|---|---|---|
request_id | string | Yes | Unique request ID (req_ prefix). The same value as the X-Request-Id response header, the request’s usage accounting row and its log lines. |
cached | boolean | Yes | |
cache_age_s | integer | No | Cache age in seconds. Omitted when the response was not cached, and also when it was cached but its age cannot be established (an entry stored before its cache carried a computed instant). Never a placeholder: an unknown age is reported as no value rather than as the cache TTL. |
cost | integer | Yes | Advisory request weight (relative compute cost). 1 for simple reads; higher for heavier endpoints. Not a credit/price. |
ranking_generation | integer | No | Committed PostgreSQL-owned leaderboard generation for the returned rows and cursor. Present on GET /api/v1/leaderboard; omitted on endpoints that do not read this ranking. |
ranking_as_of | string | No | Authoritative RFC3339 timestamp from cache_generations.updated_at for ranking_generation. It is read in the same repeatable-read snapshot as the leaderboard rows and is not request time, cache write time, or row insertion order. |
continued_from_generation | integer | No | GET /api/v1/leaderboard only. The cursor’s ranking_generation, set when this page continued a cursor from an earlier ranking that moved under it: the rows follow the cursor’s boundary in the ranking named by ranking_generation, so a trader who crossed the boundary can repeat a row you already hold or be missing from the walk. De-duplicate by id, or restart from the first page for an exact walk. Omitted on a first page and on an exact continuation, including a newer generation in which nothing a page of that order reads moved. It can equal ranking_generation when the ranking moved within one generation: on the default order, sort=rank and sort=grade when the rank keys changed, and on every other sort whenever the projection republished (about once a minute; since 2026-11-07). |
directional_source | live | degraded | No | Directional evidence provenance for Edge Hunter signals collections. The default board carries this provenance in data.directional_source and omits this optional meta field. |
ranking_source | live | db_only | No | Ranking evidence provenance for Edge Hunter signals collections. The default board carries this clock/provenance in data.ranking_source and omits this optional meta field. |
category_skill_source | live | partial | degraded | unavailable | No | Whole filtered snapshot category-evidence status before pagination. Operational live always remains partial source coverage. |
category_skill_model_version | string | No | |
category_skill_taxonomy_version | string | No | |
category_skill_platform | string | No | |
category_skill_scope | string | No | |
category_skill_source_coverage | partial_whale_threshold_fills | graded_wallet_fills | No | |
category_skill_observation_started_at | string | No | |
category_skill_model_operationally_degraded | boolean | No | Whole-model operational readiness captured with the category model snapshot. Present on category-enriched responses even when the filtered signal list is empty. When true, category_skill_source is degraded and Edge Hunter signals uses the shorter degraded cache TTL. |
category_skill_status_counts | object (live, insufficient, stale, unknown, degraded) | No | |
category_skill_base_payload_hash | string | No | SHA-256 of the funded signal membership/order/rank/cursor vector immediately before category-skill enrichment. Edge Hunter signals view only. |
category_skill_enriched_base_payload_hash | string | No | Independent SHA-256 recomputation over the same base fields immediately after category-skill enrichment. Equality with category_skill_base_payload_hash proves category-skill enrichment did not change funded inputs. Edge Hunter signals view only. |
ScheduledPickSlot
An entitled same-day slot with a future scheduled release: stable identity and backend-owned release/kickoff instants. It leaves this list at its release instant; an unpublished slot is never a delayed recommendation. No matchup, category, platform, side, price, or holder fields appear before release. Unauthorized scheduled ranks appear only in locked_picks.| Field | Type | Required | Description |
|---|---|---|---|
pick_rank | integer | Yes | Deprecated compatibility daily release slot; use pick_id for identity and publication_order for scheduling. |
release_at | string | Yes | The slot’s future release instant. Remove this preview at that instant and read again for published picks; a scheduled slot does not guarantee publication. |
kickoff | string | Yes | The backed game’s current kickoff instant. |
pick_id | string | Yes | Stable pick row identity as decimal text. Never use a quality rank as identity. |
publication_order | integer | Yes | Compatibility release slot. No quality claim; historic scheduling order is retained. |
is_free_selection | boolean | Yes | Viewer-independent free selection designation. New rows store it explicitly; historic null storage uses the original free slot. |
supersedes_pick_id | string | null | Yes | Deprecated (#24157): always null. No replacement lineage was ever recorded in this field; the key stays so existing V1 clients keep parsing. Identify a pick by pick_id. |
ScoreCell
One side’s score in a single set. The verbatim provider text stays on the team’sscore string; this is the parsed form.
| Field | Type | Required | Description |
|---|---|---|---|
games | integer | Yes | Games won in this set. |
tiebreak | integer | No | Tiebreak points won in this set. Omitted when the set had no tiebreak; absence and zero are different. |
ScoreFormat
Shape the provider score string was parsed into.two_side is one aggregate per side (basketball 105-98), multi_set is per-set columns (tennis 6-7(5-7), 6-0, 1-0), esports_series is a maps/sets/format triplet (000-000\|2-0\|Bo3). Omitted when the score could not be parsed.
String enum: two_side, multi_set, esports_series.
SettledMarketData
One GET /api/v1/markets/settled row: the market_settled webhook’s data, MarketSettledData, protocol_version included. Kept as its own name for clients generated since SDK 0.45.0. No documented fields.SettlementSubscriptionFilters
Settings for market_settled; every set field must match. Optional: subscribing without it stores {“sports_market_types”: [“moneyline”]}, every market Polymarket labels moneyline, and sending it without the event is refused (400). That label is each head-to-head game’s winner market, but in golf and other field events Polymarket labels every player market moneyline (winner, make the cut, round leader), so one tournament can send hundreds of states. Narrow it with leagues, which no market outside the list matches, including one whose league is null (a golf event slug that starts with a year, such as 2026-world-wide-technology-championship), or with condition_ids. A PATCH without it keeps the stored settings while the event stays subscribed; removing the event clears them. Stored as the API normalized it: trimmed and deduplicated, leagues, market types and condition IDs lowercased, and sports_market_types filled in when omitted.| Field | Type | Required | Description |
|---|---|---|---|
leagues | array of string | No | Event slug league prefixes such as nba or epl, matched case-insensitively; any one matches. A polyv2 copy’s league is read after its polyv2 prefix. PGA Tour golf, whose event slugs start with the year, is pga. |
sports_market_types | array of string | No | Polymarket sportsMarketType values such as moneyline, spreads, totals or a prop type, matched case-insensitively; any one matches, and * matches every type. Omitted, it is [“moneyline”], or [”*”] when condition_ids names the markets. |
event_slugs | array of string | No | Polymarket event (game) slugs; any one matches. |
condition_ids | array of string | No | Market condition IDs, raw or mkt_-prefixed; any one matches. |
SharpMoneyFlowDetectedData
sharp_money_flow_detected data (Pro and Max): ranked-trader net flow on a market crossed the threshold. The deprecated spelling smart_money_flow_detected delivers the same object until its sunset on 2027-02-01 (#29352).
| Field | Type | Required | Description |
|---|---|---|---|
condition_id | string | Yes | Polymarket condition id of the market. |
net_flow_usd | number | Yes | Signed ranked-trader net flow in USD over window: positive is net into YES, negative net into NO. |
abs_net_flow_usd | number | Yes | Absolute value of net_flow_usd, the magnitude compared with the threshold. |
dominant_side | yes | no | Yes | yes when net_flow_usd is 0 or more, else no. |
grade_floor | S | A | B | C | D | F | Yes | Minimum trader grade included in the flow. |
whale_trade_count | integer | Yes | Ranked-trader large fills that make up the flow. |
window | string | Yes | Window the flow was aggregated over, for example 24h. |
SmartMoneyFlowMarket
| Field | Type | Required | Description |
|---|---|---|---|
market | object (id, condition_id, title, slug, category, platform, protocol_version) | Yes | |
sharp_money | object (net_flow_usd, direction, token_id, large_trade_count, whale_trade_count, buy_volume_usd, sell_volume_usd) | Yes | Sharp-money flow aggregate for the market (canonical; smart_money is a deprecated byte-identical alias). |
smart_money | object (net_flow_usd, direction, token_id, large_trade_count, whale_trade_count, buy_volume_usd, sell_volume_usd) | Yes | Deprecated alias of sharp_money; byte-identical. Sunset 2027-02-01 (#29352): removed from V1 on that date; read sharp_money. |
timeframe | string | Yes |
SnapshotCompleteness
| Field | Type | Required | Description |
|---|---|---|---|
status | complete | partial | empty | Yes | complete only on a final body (snapshot.status final). partial for a live range and for a closed range whose body was read before final_after; reason says which. empty when the range has no whale activity. |
reason | string | Yes | |
expected_days | integer | Yes | |
covered_days_with_large_trade_activity | integer | Yes | Canonical key since #16304; covered_days_with_whale_activity is its deprecated spelling, emitted beside it with the same value until its sunset on 2027-02-01 (#29352). |
covered_days_with_whale_activity | integer | Yes | Deprecated spelling of covered_days_with_large_trade_activity, emitted beside it with the same value. Sunset 2027-02-01 (#29352): removed from V1 on that date; read covered_days_with_large_trade_activity. |
SnapshotState
| Field | Type | Required | Description |
|---|---|---|---|
version | integer | Yes | Immutable content version for a durable report identity; 0 for an ephemeral explicit weekly from/to range. |
storage | durable | ephemeral | Yes | durable for canonical daily, ISO-week, and monthly snapshot identities; ephemeral for explicit weekly from/to ranges, which are recomputed within a bounded 31-day window and never persisted. |
status | final | rolling | Yes | final only for a body whose source read started at or after final_after (the UTC close of the range plus the whale-trade ingestion budget). rolling for a live range and for a closed range still inside that budget: such a body refreshes every five minutes, is rebuilt once after final_after, and is then frozen. Before 2026-09-22 a closed range read final from the calendar alone, even for a body built before the range ended (#16225). |
generated_at | string | Yes | |
mutable_until | string | null | Yes | For a rolling body, the UTC date on which a final body can first be built (the date of final_after); null once final. |
period_closed | boolean | Yes | Whether the source range has ended on the UTC calendar. Closing is not finality: a closed range is rolling until final_after. |
final_after | string | Yes | The instant a source read must start at or after to produce a final body: the range’s UTC close plus 7,530 s, the whale-trade ingestion budget (p95 block lag gate plus the projection retry budget). |
source_read_started_at | string | null | Yes | When this body’s source read started, the clock finality is judged on. null for a body stored before that clock was recorded. |
SportLeaderboard
One sport’s skill leaderboard, or one league’s. Every figure on a row is the wallet’s record in this sport or league, except grade, the wallet’s all-time grade, and volume (see volume_scope).| Field | Type | Required | Description |
|---|---|---|---|
as_of | string | null | Yes | The latest time any wallet’s record on this board was recomputed. The sport ranking reruns hourly, a league ranking about once a day. null when the board has no rows. |
category | string | null | Yes | The canonical sport the slug resolved to, for example Soccer or Basketball. null when no wallet has a record under it; rows is then empty. |
edge_average | number | null | Yes | The mean edge over every wallet in the field whose price_edge.status is ranked, held ones included: the value each row’s edge_skill is pulled toward. null when no wallet’s edge is ranked. |
league | object | Yes | The league this board ranks; null on a sport board. |
limit | integer | Yes | The requested limit after clamping to 1..100 (default 20). rows holds fewer when the board has fewer wallets. |
min_resolved | integer | Yes | Settled markets of $20 or more a wallet needs in the sport or league to be on the board. |
rows | array of object (address, cost, edge_hold, edge_skill, grade, id, last_category_trade_at, losses, n_resolved, platform, pnl, price_edge, rank, roi, username, volume, win_rate, win_rate_wilson_lb, wins, category_numbers) | Yes | The head of the board, in sort order. Every figure is the wallet’s record in this sport or league, except grade (all-time) and volume (see volume_scope). |
sort | edge | pnl | win_rate | Yes | The order rows are in. edge: by edge_skill, with every wallet whose edge is not ranked, or is held, after the ranked ones. pnl: by realized P&L in the sport or league. win_rate: by the Wilson lower bound of the win rate. |
sport | string | Yes | The board’s sport slug, for example soccer, basketball or esports. An alias in the path, such as nba or cs2, reads as its sport’s slug. |
total_traders | integer | Yes | Wallets with at least min_resolved settled markets in the sport or league and a trade, in any market, in the last 180 days: the field rows is the head of. |
volume_scope | sports_and_esports | Yes | What each row’s volume measures. sports_and_esports: the wallet’s volume across all its sports and esports markets, not this sport’s or league’s alone. |
StoredPriceMove
One stored price move: the market_price_moved payload of the episode’s largest step, unchanged, plus move_id, episode_started_at and outcome_after. No documented fields.SuspiciousTrade
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Prefixed ID (rf_…). |
suspicion_score | number | Yes | Stored score that met the live flag threshold. |
severity | flag | Yes | The live scorer persists one threshold class. |
trader | object (id, address, username) | Yes | |
market | object (id, condition_id, title, slug) | Yes | |
scores | object (timing, edge, size, fresh_wallet) | Yes | |
evidence | object | Yes | Stored whale_alerts.suspicion_signals JSON from the scorer. |
created_at | string | Yes | Stored trade timestamp. |
clv | object (basis_version, close_anchor_at, close_price, clv_cents, pre_kickoff, status, unavailable_reason, clv_after_fees_cents, taker_fee_cents) | Yes | Closing line value against the market’s stored close (GET /api/v1/market/{condition_id}/close), the same object large trades carry. Always present; status says whether it is measured. |
result | object (status, resolved_at, pnl_usdc) | Yes | How the market settled for the trade’s side. A flag is a lead, not a verdict; this is what followed it. |
hedge | object | Yes | What else the wallet holds that pays if the flagged outcome loses: the hedge the Suspicious trades page shows. Only outcomes that cannot win together with the flagged one count: the other outcome of the same market, and for a Yes buy on a negative-risk market, Yes on the event’s other negative-risk markets of the same type. Null when the trade is older than 90 days, the window the page measures. |
outcome | string | null | Yes | The traded outcome’s label (for example “Yes”, “No” or a team name), from the trade’s trusted outcome index against the market. Null when the index is not trusted or the market has no label for it. |
price | number | Yes | Fill price of the traded outcome, from 0 to 1. |
side | string | Yes | Trade direction: BUY or SELL, or UNKNOWN when the stored side is neither. |
size_usd | number | null | Yes | USD notional of the fill. Null when the trade stored none. |
traded_at | string | Yes | When the trade filled. The same instant as created_at; a flag scored after the fill still carries the fill time. |
SuspiciousTradeFlaggedData
suspicious_trade_flagged data (Pro and Max): a trade’s suspicion score crossed the flag threshold for the first time. The deprecated spelling insider_radar_flag_raised delivers the same object until its sunset on 2027-02-01 (#29352).
| Field | Type | Required | Description |
|---|---|---|---|
trade_id | integer | Yes | Numeric id of the flagged trade, a JSON number. It is the id that GET /api/v1/large-trades/{id} accepts. |
wallet | string | Yes | Address of the wallet that made the trade. |
trader_id | integer | Yes | 0xinsider’s numeric id for the wallet. |
condition_id | string | Yes | Polymarket condition id of the market. |
suspicion_score | number | Yes | The suspicion score, 0 to 100, that crossed the threshold. |
track | whale | fresh_conviction | sliced_position | Yes | The scoring track that raised the flag. |
side | yes | no | Yes | Outcome side the flagged fill took. |
size | number | Yes | Share count of the flagged fill. |
price | number | Yes | Fill price of the flagged trade. |
TennisPoints
Optional current-game tennis facts from API-Tennis, aligned with live_score.scores display order. These facts have their own revision and expiry; Polymarket remains the source of sets, match status, period, and the outer live-score revision, except on ITF singles, which Polymarket does not score: there API-Tennis supplies the whole live_score, bound on both players’ names, the tournament and the date. New observations require corroborated identity, current set/games, and live state. Where Polymarket publishes no score (tennis doubles, whose live_score reads one 0-0 set throughout), the group binds on both pairs’ names, the tour, the date and API-Tennis’s live flag, and carries set_games, the provider’s set score for the match. Cached responses and replayed frames may still carry expired facts, so clients must enforce expires_at.| Field | Type | Required | Description |
|---|---|---|---|
source | api_tennis | Yes | |
match_key | integer | Yes | API-Tennis match ID. This is not a Polymarket market or event ID. |
player_keys | array of integer | Yes | API-Tennis player IDs in the same first/second order as live_score.scores. These are not Polymarket team IDs. |
points | array of string | Yes | Current-game point values in first/second order. Read strings, including A for advantage and numeric tiebreak points. Missing points are not zero. |
serving_side | first | second | No | The serving player in live_score.scores display order. Omitted when API-Tennis does not identify the server. |
source_revision | integer | Yes | Orders only the tennis_points group for the same match. Never compare this with live_score.source_revision. |
observed_at | string | Yes | When 0xinsider observed these API-Tennis facts. This is not a timestamp from the court. |
expires_at | string | Yes | Stop displaying the point group at this instant, even if the enclosing score remains fresh. The group expires 30 seconds after observed_at. |
set_number | integer | Yes | Current set number. Display points only while this matches the enclosing scoreboard, unless set_games is present. |
games | array of integer | Yes | Current-set games in first/second order. Display points only while these match the enclosing scoreboard, unless set_games is present. |
set_games | array of array of integer | No | API-Tennis games in every listed set, first set first, each in first/second order. Present only when Polymarket publishes no score for the match (tennis doubles): display these as the set score, and discard the group once live_score carries a nonzero game. A deciding match tie-break is listed as games, for example 9-5. Omitted for every other match. |
TennisRanking
A provider-reported ATP/WTA singles rank with independent retrieval and expiry clocks. API-Tennis provides no ranking publication date. Retrieval time does not establish when the tour published the ranking.| Field | Type | Required | Description |
|---|---|---|---|
rank | integer | Yes | Provider-reported singles rank. |
tour | atp | wta | Yes | The player ranking tour. |
source | api_tennis | Yes | The standings provider. |
observed_at | string | Yes | Successful snapshot retrieval time in UTC, not ranking publication date. |
expires_at | string | Yes | UTC deadline after which clients must hide this rank, including when an older game or pick response remains cached. |
Trader
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Prefixed ID (trd_…). |
address | string | Yes | |
username | string | No | |
grade | S | A | B | C | D | F | No | |
streak_tier | hot | rising | neutral | cooling | cold | No | Hot-streak tier (trailing-7d cross-sectional percentile); a separate axis from the all-time grade. Omitted when there is no recent activity. |
score | number | No | |
forecast_score | number | No | Optional forecast score on the documented display scale. Null when unavailable. |
forecast_evidence | number | No | Optional 0-1 share of forecast_score that the trader’s own resolved-market record supports, to two decimal places. It rises toward 1 as more of the trader’s markets resolve and never reaches it. Missing values remain unavailable rather than being inferred. |
rank | integer | No | |
pnl | object (total, net_total, correction, correction_pending, realized, unrealized, exact, in_scope) | Yes | |
stats | object (markets_traded, win_rate, daily_win_rate, total_volume, exact, markets_decided, markets_won, win_rate_status) | Yes | Sports and esports markets only since 2026-10-27 (#29830): markets_traded and win_rate come from the wallet’s sports and esports record (pnl.in_scope), and total_volume from its stored trade days. A wallet that traded no sports or esports market never gets a record: markets_traded is 0 and win_rate is omitted (since 2026-10-29, #30589, #30657). A wallet that trades only combos has no record either: both are omitted (since 2026-10-29, #30637). |
strategy | object (strategy_type, description, confidence) | No | |
category_strengths | object | No | Per-category rank context when expand=categories is requested. Values include available rank, category totals, performance and record counts; scaled_total_pnl is a legacy alias of total_pnl. Its measurement basis and update timing differ from the plain record returned by GET /api/v1/trader/{address}/categories, so the two need not agree. Use this for rank context and that route for the plain record. Sports and esports only (#28761): keys are sports and esports categories, and a category outside them is omitted, as on that route. The inner key-set is intentionally unconstrained and may contain additional compatibility fields. |
quant_metrics | object (smart_score, copy_score, sharpe_30d, sharpe_7d, profit_factor, edge_consistency, sharpe_percentile, pf_percentile, consistency_percentile) | No | Deprecated since 2026-10-27 and never sent. These advanced risk and performance metrics covered every Polymarket market of the wallet, and wallet figures cover sports and esports markets only (#29589). expand=quant_metrics is still accepted and adds nothing. For the sports and esports record read pnl.in_scope here, and GET /api/v1/trader/{address}/pnl for its daily series. The member shape below is what the object held before; it is kept so existing type declarations still compile. |
last_active | string | No | When the wallet last traded: the later of its most recent recorded trade and its most recent trade seen on Polymarket’s live trade stream, which carries the taking side of each match and is written every 30 seconds for a wallet whose small fills are not recorded as they happen (since 2026-11-15, #35652). A trade later than synced_at marks the sports_record group stale. The leaderboard entry’s last_active reads the recorded trade alone and re-reads it hourly, so this can be later. A cached body (meta.cached true) can lag a new trade by up to 60 seconds. No data_quality group dates it: the value is itself a trade time. Since 2026-11-02 (#32324); before, it carried the time 0xinsider last synced the wallet, the same value as synced_at. Omitted when neither trade time is known. |
synced_at | string | No | When 0xinsider last completed a sync of the wallet (traders.last_synced), dated by the sync data_quality group. Not when the wallet traded: read last_active for that. |
sync_status | string | No | synced, unknown, or pending. |
data_quality | DataQuality | Yes | Data age and coverage for this trader body. Always present. Its six groups are sync (traders.last_synced, covering synced_at and sync_status; it covered last_active until 2026-11-02, #32324, and no group covers last_active now, since the value is itself a trade time), sports_record (trader_product_scope_records.computed_at, covering pnl.in_scope, stats.markets_traded and stats.win_rate: unavailable until the wallet’s sports and esports record is computed, partial while it has no decided sports or esports market; stale with owner traders.last_synced and as_of the last completed sync when the wallet traded after that sync (last_active later than synced_at), because the record’s figures come from the per-market values that sync read and leave out every trade and settlement since, since 2026-11-15, #35587; stale the same way, with no trade since, when a market the wallet held settled after that sync, because settling removes the wallet’s open row for it and the settled row waits for the next read of its Polymarket positions, so the figures may leave that market out, since 2026-11-15, #35613; for a wallet that traded no sports or esports market, which never gets a record, partial with owner traders.last_synced, as of the completed sync that found none, stats.markets_traded 0 and pnl.in_scope and stats.win_rate omitted, since 2026-10-29, #30589, #30657; for a wallet that trades only combos and holds no single sports or esports market, partial with owner traders.last_synced and all three omitted, since 2026-10-29, #30637), ranking (trader_rankings.computed_at, covering grade, score, streak_tier, forecast_score and forecast_evidence), leaderboard_rank (leaderboard_rank_refresh_state.completed_at, the completion time of the latest fully completed global rank refresh, covering rank), volume (traders.last_synced, covering stats.total_volume, the sum of the trade days the sync stores: unavailable before the first completed sync and while a stored day’s sports and esports volume is not computed) and positions (trader_position_snapshots.last_refreshed_at with traders.last_synced as fallback, covering pnl.unrealized, the open-position aggregate; stale with as_of that clock when the wallet traded after it, last_active later than as_of, because a stored fill moves no open position, since 2026-11-15, #35613). Since 2026-10-27 (#29830) there is no leaderboard_pnl group, and volume is dated by the sync clock instead of trader_usd_volume.observed_at. The positions clock is the latest successful /positions snapshot when one exists, otherwise the last completed trader sync. A rank or position value remains unknown or unavailable when its clock or value is absent. For an unknown wallet every group is unavailable. If the open-position read itself fails, positions is unavailable with a reason that says so, pnl.unrealized is absent, and the body is answered fresh (meta.cached false) and is not kept for later callers. |
trust | TraderTrust | No | Field-level trust metadata. Present only when expand=trust or expand[]=trust is requested. |
category_records | array of CategorySkillV2 | No | Current evidence for observed and known categories (expand=categories or expand[]=categories). Omitted unless expanded. Includes insufficient, stale, unknown and degraded rows; absence of a category is not proof of skill. The global grade is unchanged. Sports and esports only (#28827): a category outside them is omitted, as on GET /api/v1/trader/{address}/categories. |
category_skill_model | CategorySkillModelReadiness | No | |
price_edge | TraderPriceEdge | No | Edge over the price paid: the profile’s Edge badge and the leaderboard’s Edge measure (#32622). Present on every read of a wallet with at least one settled sports or esports market of $20 or more at a known entry price; omitted for a wallet with none, where there is nothing to measure. |
breakdowns | TraderBreakdowns | No | The profile’s strategy measures over the wallet’s sports and esports markets: P&L and win rate by UTC hour, hold-time and first-trade-hour bands, position sizes with category concentration, and entry-price buckets (#32622). Present only when expand=breakdowns or expand[]=breakdowns is requested, on GET /api/v1/trader/{address} only: POST /api/v1/traders/batch refuses the expand. Computed on the read from the wallet’s whole sports and esports history, so a large wallet can take seconds; a read that cannot finish answers 503 with Retry-After. |
category_numbers | CategoryNumbers | No | Whether category_strengths and category_records take the wallet’s latest settlements (#36089). Present exactly when expand=categories or expand[]=categories is requested. |
TraderBreakdowns
The profile’s strategy measures (expand=breakdowns, #32622), the same figures as the wallet profile’s Insights and Performance breakdown cards. Every figure counts the wallet’s sports and esports markets only, from the same read the profile makes.| Field | Type | Required | Description |
|---|---|---|---|
hourly_performance | TraderHourlyPerformance | Yes | |
time_breakdowns | TraderTimeBreakdowns | Yes | |
risk_metrics | object | Yes | Position sizes and category concentration. null when the wallet has no sports or esports position with trades, or its stored markets carry no freshness clock yet. |
entry_price_analysis | TraderEntryPriceAnalysis | Yes |
TraderCategoryRecord
| Field | Type | Required | Description |
|---|---|---|---|
category | string | Yes | Canonical category bucket, for example Soccer, Esports, Tennis. Esports is one bucket, and the Esports record carries its per-game records in games. Every record carries its per-scope records (esports titles, soccer leagues, other sports’ leagues) in scopes. |
wins | integer | Yes | Markets in this category the wallet closed with a profit. |
decided | integer | Yes | Markets it closed with a profit or a loss. A market that resolved at exactly zero P&L is in neither count, so this is not the wallet’s market count in the category. |
win_rate | number | null | Yes | wins / decided in [0,1], truncated to four decimals. Null when status is not_enough_data. |
status | measured | not_enough_data | Yes | measured: decided cleared min_decided_for_win_rate and win_rate carries the rate. not_enough_data: the counts are real but the sample is under the floor, so no percent is published. A failed read is an error response, never a status value. |
games | array of TraderEsportsGameRecord | No | The wallet’s record per esports title, busiest first. Present only on the Esports record, and only when the wallet has a settled market in at least one title; absent on every other category and on an Esports record whose markets are all in series that are not games (skin-price indices, streamer props) or carry no series. Absent means no per-game record, the same rule as an absent category. Each entry’s decided is a subset of the Esports record’s, read in the same statement from the same daily rebuild. |
scopes | array of TraderCategoryScopeRecord | No | The wallet’s record per scope of this category, busiest first: each esports title on the Esports record, each soccer league on the Soccer record (UEFA Champions League, LaLiga, Premier League, …), and each registered league of another sport on its record (NBA, NFL, ATP, …). The same records Pick of the Day and the holder chips name in category_win_rate_game. Present only when the wallet has a settled market in at least one scope; absent means no per-scope record, the same rule as an absent category. On the Esports record it lists the same titles as games, with the same counts. Each entry’s decided is a subset of its record’s, read in the same statement from the same daily rebuild. |
TraderCategoryRecords
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Prefixed trader id (trd_<wallet>). |
address | string | Yes | Resolved wallet address, lowercased. |
basis | settled_markets_all_sizes | Yes | Which sample the counts come from: every settled market in the category, at any position size. category_strengths on the trader endpoint reads the floored calibration sample instead, so the two differ in both directions: measured on production 2026-09-22 over the 122,497 wallet-category pairs with at least 20 decided markets on both bases, the floored rate was higher in 56.5% of pairs and lower in 34.5%, median +0.6 points, p10 -4.6, p90 +9.8, with 14.0% of pairs 10 points apart or more. Neither corrects the other. |
min_decided_for_win_rate | integer | Yes | Decided markets a category needs before win_rate is served. Published so a caller can apply its own sample rule to the raw counts. |
computed_at | string | null | Yes | When the served records were last rebuilt (RFC3339, Z): the newest stamp among every row served, game and scope rows included, which the daily rebuild, or the recount about an hour after a settlement, writes in one transaction. Null when the wallet has no record at all. |
records | array of TraderCategoryRecord | Yes | One entry per canonical category with at least one decided market, ordered by decided descending then category. A category with no decided market is omitted. The Esports entry carries its per-game records in games, and every entry its per-scope records in scopes. |
TraderCategoryScopeRecord
| Field | Type | Required | Description |
|---|---|---|---|
scope_key | string | Yes | The stable key the scope’s record is stored under: an esports series slug (league-of-legends, counter-strike), a soccer league’s season-stripped series stem (ucl, la-liga, premier-league), or another sport’s league stem (nba, nfl, atp). display_name is the label. |
display_name | string | Yes | The scope’s name as Pick of the Day and every holder chip print it in category_win_rate_game: LoL, CS2, UEFA Champions League, LaLiga, NBA. Match a chip to this row by string equality. |
wins | integer | Yes | Markets in this scope the wallet closed with a profit. |
decided | integer | Yes | Markets in this scope it closed with a profit or a loss. A subset of the parent record’s decided: the two are read from the same rebuild. |
win_rate | number | null | Yes | wins / decided in [0,1], truncated to four decimals. Null when status is not_enough_data. |
status | measured | not_enough_data | Yes | The same rule as the parent record: measured when decided cleared min_decided_for_win_rate, not_enough_data when the counts are real but the sample is under the floor. A chip on a market in this scope shows this row’s rate when it is measured and the parent record’s otherwise. |
TraderClv
Closing line value over one wallet’s large trades in a window (#32517).| Field | Type | Required | Description |
|---|---|---|---|
address | string | Yes | Wallet address, lowercase. |
basis_version | string | Yes | The CLV definition, clv@v1, each trade’s clv.basis_version. |
category | string | null | Yes | The category filter as sent, or null. |
excluded | object (in_play, pending, unavailable) | Yes | The window’s trades that carry no CLV, by clv.status. |
from | string | Yes | Window start, inclusive. |
id | string | Yes | trd_-prefixed trader id. |
large_trades | integer | Yes | Large trades in the window, every status. |
measured | object (market_ci95_cents, market_mean_clv_cents, markets, mean_clv_cents, share_beat_close, size_usd, stake_weighted_clv_cents, trades) | Yes | Figures over the trades whose clv.status is measured. |
min_size | number | Yes | Size floor in USDC, as /large-trades/history reads it. |
to | string | Yes | Window end, exclusive. |
TraderContext
| Field | Type | Required | Description |
|---|---|---|---|
trader | Trader | Yes | |
position_summary | object (markets_total, markets_synced, markets_pruned, markets_unstored, markets_combo, markets_resolved, markets_open, sync_coverage, synced_realized_pnl, total_realized_pnl, unrealized_mtm, cost_basis_locked, resolved_win_rate, resolved_wins, resolved_decided, as_of) | No | Aggregate position and P&L coverage for the trader, over its synced markets. markets_open, unrealized_mtm and cost_basis_locked cover the open positions on sports and esports markets, each market judged when the summary is read (#32119). markets_synced, markets_resolved and the resolved win figures count every stored market: since 2026-10-27 (#29366) those are mostly sports and esports markets, but a market that moved out of sports and esports, or one stored before its category was known, stays in them, and sync_coverage counts every category on both sides. markets_total, total_realized_pnl and synced_realized_pnl still cover every Polymarket market of the wallet. Omitted entirely (key absent, never null) when the trader is not in the local database or native net economics is unavailable. Realized fields remain numbers when present, including a genuine zero. |
data_as_of | string | null | Yes | RFC3339 freshness of the OPEN-position-level data: when a position_summary is present this mirrors its as_of byte-for-byte (latest /positions snapshot, else last completed sync) — the open-position freshness clock, since the snapshot advances only open positions; otherwise the trader’s last completed sync, even if an unserved position snapshot exists. Null when the selected clock is unavailable; a missing breakdown does not establish position or accounting freshness. |
freshness_note | string | Yes | Human-readable statement of the point-in-time snapshot semantics (data_as_of is the open-position clock — the latest /positions snapshot, else the last completed sync; the snapshot advances only open positions, so resolved counts and win rate can include settled markets recorded after the last full sync; native realized P&L follows its accounting snapshot — not a live feed; re-fetch for fresher data). |
TraderEntryPriceAnalysis
Results by the entry price the wallet paid for the side it held, over its settled sports and esports positions with a held entry price. coverage counts the settled positions the buckets leave out, and why.| Field | Type | Required | Description |
|---|---|---|---|
buckets | array of TraderEntryPriceBucket | Yes | One bucket per price band that has a market, in bucket_order. |
best_bucket | string | null | Yes | The bucket with the highest win rate among buckets of at least 3 markets. null when no bucket has 3. The 3 counts markets, not decided ones: best_measured_bucket is the pick behind the decided-market floor. |
worst_bucket | string | null | Yes | The bucket with the lowest win rate among buckets of at least 3 markets. null when no bucket has 3. The 3 counts markets, not decided ones: worst_measured_bucket is the pick behind the decided-market floor. |
coverage | TraderEntryPriceCoverage | Yes | What the buckets cover (since 2026-11-03, #32671). |
best_measured_bucket | string | null | Yes | Additive (since 2026-11-11, #34355): the bucket with the highest win rate among buckets whose win_rate_status is measured (5 or more decided markets), so one lucky market is never the best range at 100%. The 0xinsider profile shows this pick. null when no bucket has 5 decided markets. |
worst_measured_bucket | string | null | Yes | Additive (since 2026-11-11, #34355): the bucket with the lowest win rate among buckets whose win_rate_status is measured. Equal to best_measured_bucket when one bucket is measured. null exactly when best_measured_bucket is. |
TraderEntryPriceBucket
One entry-price band. Each measure is an analytic value: read state before value.| Field | Type | Required | Description |
|---|---|---|---|
bucket | string | Yes | The band: $0.00-$0.19 (any price below $0.20, sub-cent fills included), $0.20-$0.39, $0.40-$0.59, $0.60-$0.79 or $0.80-$0.99. Until 2026-11-03 the first band was $0.01-$0.19 and sub-cent fills had no bucket (#32671). |
bucket_order | integer | Yes | Display position, 0 first, from the lowest price up. |
markets | AnalyticInteger | Yes | Markets in the band. |
wins | AnalyticInteger | Yes | Of those, the markets that made money. |
win_rate | AnalyticNumber | Yes | wins over decided markets (a nonzero P&L), as a percentage 0-100. |
total_pnl | AnalyticNumber | Yes | Realized P&L of the band’s markets, USD. |
avg_pnl | AnalyticNumber | Yes | Mean realized P&L of a market in the band, USD. |
markets_decided | integer | Yes | Additive (since 2026-11-11, #34355): the band’s markets with a nonzero P&L, win_rate’s divisor. Present on every band. |
win_rate_status | measured | not_enough_data | Yes | Additive (since 2026-11-11, #34355): measured from 5 decided markets (markets_decided), not_enough_data below, the floor the 0xinsider profile applies before it shows a band’s win rate, so one lucky market never reads as 100%. Below it win_rate is still sent as before; quote wins of markets_decided instead of a rate. Present on every band. |
TraderEntryPriceCoverage
The settled sports and esports positions the entry-price section reads. The buckets’ markets plus every unbucketed row’s are settled_markets, and their realized P&L sums to settled_pnl. settled_pnl adds up the wallet’s per-market realized P&L, so it differs from pnl.in_scope.realized_pnl, which is Polymarket’s published sports and esports P&L with a share of the wallet’s rebates.| Field | Type | Required | Description |
|---|---|---|---|
settled_markets | integer | Yes | Settled sports and esports positions: bucketed_markets plus every unbucketed row’s markets. |
settled_pnl | number | Yes | Realized P&L of those positions, USD. |
bucketed_markets | integer | Yes | Positions in a bucket: the sum of buckets[].markets. |
bucketed_pnl | number | Yes | Realized P&L of the bucketed positions, USD: the sum of buckets[].total_pnl. |
unbucketed | array of TraderEntryPriceUnbucketed | Yes | The settled positions the buckets leave out: one row for each reason that has a position, ordered by reason. Empty when the buckets hold every settled position. |
TraderEntryPriceUnbucketed
Settled positions with no entry-price bucket, for one reason.| Field | Type | Required | Description |
|---|---|---|---|
reason | two_sided | held_side_unpriced | no_entry_price | freshness_unknown | Yes | two_sided: both outcomes bought at a price, a hedged book with no single side. held_side_unpriced: one outcome has a recorded price, but the wallet’s remaining shares are on the other. no_entry_price: no outcome has a recorded entry price. freshness_unknown: a bucket whose rows carry no freshness clock yet. |
markets | integer | Yes | Positions left out for this reason. |
total_pnl | number | Yes | Their realized P&L, USD. |
TraderEsportsGameRecord
| Field | Type | Required | Description |
|---|---|---|---|
game | string | Yes | The game, by the same name every holder chip carries in category_win_rate_game: LoL, CS2, Dota 2, Valorant, Call of Duty, Honor of Kings, Mobile Legends: Bang Bang, Overwatch, Rainbow Six Siege, Rocket League or StarCraft II. Match a chip to this row by string equality. |
series_slug | string | Yes | The Polymarket series slug the record is keyed on: league-of-legends, counter-strike, dota-2, valorant, call-of-duty, honor-of-kings, mobile-legends-bang-bang, overwatch, rainbow-six-siege, rocket-league or starcraft-2. The stable key; game is the label. |
wins | integer | Yes | Markets in this game the wallet closed with a profit. |
decided | integer | Yes | Markets in this game it closed with a profit or a loss. A subset of the parent Esports record’s decided: the two are read from the same rebuild. |
win_rate | number | null | Yes | wins / decided in [0,1], truncated to four decimals. Null when status is not_enough_data. |
status | measured | not_enough_data | Yes | The same rule as the parent record: measured when decided cleared min_decided_for_win_rate, not_enough_data when the counts are real but the sample is under the floor. A chip on a market in this game shows this row’s rate when it is measured and the Esports bucket’s otherwise. |
TraderExportArtifactManifest
| Field | Type | Required | Description |
|---|---|---|---|
manifest_version | string | Yes | Version of the artifact manifest contract. |
format | json | ndjson | csv | Yes | Serialization used for the decompressed content. |
schema_version | trader-export-json-v1 | trader-export-ndjson-v1 | trader-export-csv-v1 | Yes | Stable schema identifier for the selected serialization. |
coverage | full_envelope_and_trades | trades_only | Yes | Sections represented by the artifact. JSON and NDJSON carry the full envelope and trades; CSV carries trade rows only. |
generation | TraderExportGeneration | Yes | |
row_count | integer | Yes | Number of trade rows written. |
content_size_bytes | integer | Yes | Exact byte count of the decompressed content stream clients receive. |
content_sha256 | string | Yes | Lowercase SHA-256 of the decompressed content bytes. |
compressed_size_bytes | integer | Yes | Exact byte count of the gzip-compressed bytes stored by the object provider. |
compressed_sha256 | string | Yes | Lowercase SHA-256 of the stored gzip bytes; the multipart ETag is not used as this checksum. |
TraderExportCategoryWatermark
| Field | Type | Required | Description |
|---|---|---|---|
source | string | Yes | |
coverage | string | Yes | |
publication_fence | string | null | Yes | |
data_as_of | string | null | Yes |
TraderExportGeneration
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Opaque generation identity selected for the coherent read snapshot. |
selected_at | string | Yes | |
consistency | string | Yes | |
source_watermarks | TraderExportSourceWatermarks | Yes | |
product_scope | string | No | The markets the file’s trades and markets sections hold: sports and esports markets only (export_metadata.scope_note in a JSON or NDJSON file names the sections that still cover every market). Absent on a file written before 2026-10-22, which holds every market; a submit never reuses such a file. |
TraderExportJob
| Field | Type | Required | Description |
|---|---|---|---|
object | string | Yes | |
data | object (job_id, status, format, total_trades, processed_trades, file_size, error, terminal, next_action, poll_after_s, created_at, started_at, ready_at, failed_at, expires_at, expired_at, data_as_of, cancel_requested_at, cancelled_at, attempt, max_attempts, artifact) | Yes | |
meta | ResponseMeta | Yes |
TraderExportPnlWatermark
| Field | Type | Required | Description |
|---|---|---|---|
source | string | Yes | |
coverage | string | Yes | |
revision | integer | null | Yes | |
observed_at | string | null | Yes |
TraderExportPositionWatermark
| Field | Type | Required | Description |
|---|---|---|---|
source | string | Yes | |
coverage | string | Yes | |
generation | integer | null | Yes | |
data_as_of | string | null | Yes |
TraderExportSnapshot
| Field | Type | Required | Description |
|---|---|---|---|
address | string | Yes | |
product_scope | string | Yes | The markets the export file’s trades and markets sections hold: sports and esports markets only. counts.exported_markets, counts.estimated_trade_rows, counts.estimated_size_mb, reconciliation.exported_market_cost_basis and source_range.latest_trade_at and latest_market_activity_at describe those markets, and reconciliation.exported_activity_volume is the cash the wallet traded in sports and esports markets. source_range.first_pnl_date, last_pnl_date and pnl_series_status and counts.pnl_days describe the file’s pnl section, the wallet’s sports and esports realized P&L by day. completeness.sync_coverage is the wallet’s stored markets (its sports and esports markets since 2026-10-27, #29366) plus the markets of other categories whose rows were deleted and counted (position_summary.markets_pruned on the context) and those first traded since 2026-10-26, which are not stored and are counted as the wallet syncs (position_summary.markets_unstored, #30165) and its combo markets, which Polymarket counts and no position read lists (position_summary.markets_combo, #30218), over Polymarket’s count of every market it traded: both sides count every category, so a fully synced wallet reads 1.0 and complete. A wallet with nothing stored and no pnl day is empty whatever its coverage. |
generated_at | string | Yes | |
source_range | ExportSourceRange | Yes | |
completeness | ExportCompleteness | Yes | |
reconciliation | ExportVolumeReconciliation | Yes | |
counts | ExportCounts | Yes | |
large_export_policy | LargeExportPolicy | Yes |
TraderExportSourceWatermarks
| Field | Type | Required | Description |
|---|---|---|---|
positions | TraderExportPositionWatermark | Yes | |
pnl | TraderExportPnlWatermark | Yes | |
categories | TraderExportCategoryWatermark | Yes | |
trades | TraderExportTradeWatermark | Yes |
TraderExportTradeWatermark
| Field | Type | Required | Description |
|---|---|---|---|
source | string | Yes | |
coverage | string | Yes | sports_esports_rows: the file holds every stored trade in the wallet’s sports and esports markets. all_matching_rows on a file written before 2026-10-22, which holds every market’s trades. |
rows | integer | Yes | Trade rows the file holds, counted in the same read snapshot as the rows. |
first_activity_date | string | null | Yes |
TraderGradeAt
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Prefixed trader id (trd_<wallet>). |
address | string | Yes | Resolved wallet address, lowercased. |
as_of | string | Yes | Requested event or decision time. |
status | graded | ungraded | unknown | Yes | graded has a proven grade; ungraded is a proven null grade; unknown has no valid historical observation. |
grade | S | A | B | C | D | F | null | Yes | Grade only when status is graded; null otherwise. |
available_from | string | null | Yes | First proven visibility instant for this trader. Null when no observation exists. Earlier times remain unknown. |
observation | object (id, previous_observation_id, observed_at, published_by, model_version, model_build_sha, source_observed_by) | null | Yes | Proof row when status is graded or ungraded. Null when history is unknown. |
TraderHourlyPerformance
P&L and win rate by the UTC hour of the wallet’s first trade in each settled sports or esports market.| Field | Type | Required | Description |
|---|---|---|---|
entries | array of object (hour, markets, wins, win_rate, total_pnl, avg_pnl, markets_decided, win_rate_status) | Yes | One entry per UTC hour that has a settled market; an hour with none is absent. |
best_hour | integer | null | Yes | The hour with the highest win_rate. null when no entry exists. Picked over every hour, an hour of one decided market included: best_measured_hour is the pick behind the decided-market floor. |
best_win_rate | number | null | Yes | best_hour’s win_rate, percentage 0-100. null exactly when best_hour is. |
worst_hour | integer | null | Yes | The hour with the lowest win_rate. null when no entry exists. Picked over every hour, an hour of one decided market included: worst_measured_hour is the pick behind the decided-market floor. |
worst_win_rate | number | null | Yes | worst_hour’s win_rate, percentage 0-100. null exactly when worst_hour is. |
spread_pp | number | null | Yes | best_win_rate minus worst_win_rate, percentage points. null when either is null. |
is_approximate | boolean | Yes | true when at least 12 hours have markets and every one of them has the same P&L sign, so the hour-to-hour spread says little about timing. |
best_measured_hour | integer | null | Yes | Additive (since 2026-11-11, #34355): the hour with the highest win_rate among entries whose win_rate_status is measured (5 or more decided markets), so one lucky market is never the best hour at 100%. The 0xinsider profile shows this pick. null when no hour has 5 decided markets; the five measured fields are null together. |
best_measured_win_rate | number | null | Yes | Additive (since 2026-11-11, #34355): best_measured_hour’s win_rate, percentage 0-100. null exactly when best_measured_hour is. |
measured_spread_pp | number | null | Yes | Additive (since 2026-11-11, #34355): best_measured_win_rate minus worst_measured_win_rate, percentage points. null exactly when best_measured_hour is. |
worst_measured_hour | integer | null | Yes | Additive (since 2026-11-11, #34355): the hour with the lowest win_rate among entries whose win_rate_status is measured. Equal to best_measured_hour when one hour is measured. null exactly when best_measured_hour is. |
worst_measured_win_rate | number | null | Yes | Additive (since 2026-11-11, #34355): worst_measured_hour’s win_rate, percentage 0-100. null exactly when worst_measured_hour is. |
TraderPnl
A trader’s sports and esports daily P&L object.id, freshness_at, series_status and realized are always present. The five sections — entries, stats, monthly, year_totals, drawdown — are present unless the request’s sections parameter excluded them, so a request that sends no sections always carries all five. An excluded section is absent from the object, never null and never an empty array. While series_status is pending the sections are empty and never mean zero.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Prefixed trader ID (trd_...). |
view | object (from, to, sections, entries_total, entries_in_window, anchor) | No | Representation parameters applied to this body. Present only when the request sent from, to or sections; omitted otherwise, which is what keeps a no-parameter response identical to the one this route served before the parameters existed. |
freshness_at | string | null | Yes | RFC3339 served-freshness clock: when the wallet’s sports and esports record, which this series is read from, was last computed, or, for a wallet that traded no sports or esports market (#30589, #30657) or trades only combos (#30637) and so has no record, its last completed sync; null while series_status is pending. Always present, so read it as a value that can be null rather than a key that can be missing. |
series_status | ready | pending | Yes | ready when the series is served; an empty one is a wallet with no sports or esports day, or one that traded no sports or esports market (#30589, #30657) or trades only combos (#30637). pending when the wallet’s sports and esports record does not carry the daily series yet: every section is empty, realized is null, and the empty sections never mean zero. Retry later. |
realized | object (basis, realized_pnl, dated_pnl, undated_pnl) | null | Yes | How the daily series adds up to the wallet’s Sports P&L, full precision: dated_pnl + undated_pnl = realized_pnl. null while series_status is pending, and for a wallet that traded no sports or esports market or trades only combos, which has no record (#30589, #30657, #30637). |
entries | array of object (date, markets_traded, total_volume, cumulative_profit, total_pnl, daily_change) | No | Sports and esports daily P&L series (oldest-first): one point for each UTC day with realized P&L or sports and esports volume. Present unless the request’s sections excluded it, and clipped to from/to when either is set. cumulative_profit and total_pnl are the running sum of daily_change from the start of the history, so a clipped slice keeps the same economic meaning; view.anchor carries the point before the window. |
stats | object (all, d90, d30, d7) | No | Pre-derived period stats. Present unless the request’s sections excluded it. Always the published all/90d/30d/7d windows over the full stored history; from/to never recompute them over the request’s range. |
monthly | array of object (year, month, pnl, markets_traded) | No | Per-month P&L aggregation. Present unless the request’s sections excluded it. Whole months over the full stored history, never clipped to from/to, so a month is never a partial month. |
year_totals | array of object (year, pnl) | No | Per-year P&L totals (ascending by year). Present unless the request’s sections excluded it. Whole years over the full stored history, never clipped to from/to. |
drawdown | array of object (date, cumulative_profit, drawdown) | No | Underwater (drawdown) series. Present unless the request’s sections excluded it, and clipped to from/to when either is set. The running peak behind each point is the full-history peak, so a clipped slice is not rebased; view.anchor.drawdown carries the value at the point before the window. |
TraderPnlExact
Deprecated since 2026-10-27 and never sent: pnl.exact held the lossless counterpart of the retired wallet-wide pnl.realized (#29830). The member shape below is what the object held before; it is kept so existing type declarations still compile.| Field | Type | Required | Description |
|---|---|---|---|
realized | ExactDecimal | Yes | Native Polymarket realized P&L plus credited maker and taker rebates, with fees included, from the trusted matching trader_trading_pnl.net_realized_pnl snapshot. |
TraderPnlInScope
A wallet’s sports and esports record (#27311). basis names the rule behind realized_pnl (#29370): polymarket_sports_esports_v1 is Polymarket’s own realized P&L for the wallet in its sports and esports categories, plus the wallet’s maker and taker rebates apportioned by its sports and esports share of its Polymarket volume (by cost while Polymarket reports no overall volume) and the in-scope part of any published neg-risk conversion correction; sports_esports_split_v1, used until both of the wallet’s category figures are confirmed, is Polymarket’s published wallet-wide realized P&L (with any published correction) split into the part earned on sports and esports markets, with fees, refunds and rebates apportioned by cost. Refreshed after each wallet sync and each read of Polymarket’s category leaderboards; as_of dates the market counts.| Field | Type | Required | Description |
|---|---|---|---|
basis | string | Yes | The rule behind realized_pnl: polymarket_sports_esports_v1 (Polymarket’s sports and esports category figures plus apportioned rebates) or sports_esports_split_v1 (the published realized figure split by cost). A new value means the rule changed; compare figures only within one basis. |
realized_pnl | number | null | Yes | Sports and esports realized P&L in USD, display-safe. null when the split basis has no published realized figure to split. |
markets | integer | Yes | Sports and esports markets the wallet has traded, any status. |
markets_resolved | integer | Yes | Of those, the settled markets: the wallet closed its position by selling out, or the market resolved. Its P&L there is final. |
win_rate | number | null | Yes | Share of decided sports and esports markets the wallet won, 0 to 1. null with no decided market. |
markets_out_of_scope | integer | Yes | The wallet’s markets outside sports and esports, which 0xinsider no longer lists: those it still stores, those whose rows it deleted and counted, and those of other categories first traded since 2026-10-26, which it does not store and counts as the wallet syncs (#30165). |
as_of | string | Yes | When the record behind these figures was computed. |
markets_decided | integer | No | Additive (since 2026-11-11, #34333): sports and esports markets the wallet closed with a profit or a loss, the divisor of win_rate. A market that closed at zero P&L is in neither count, so it can be below markets_resolved. |
win_rate_status | measured | not_enough_data | No | Additive (since 2026-11-11, #34333): measured from 5 decided markets (markets_decided), not_enough_data below. It is the floor the 0xinsider leaderboards, profile and trade rows apply before they show a win rate, so one lucky market never reads as 100%. Below it win_rate is still sent; quote the decided count instead of win_rate as a rate. Sent with markets_decided. |
TraderPriceEdge
Edge over the price paid (#32270, #32622): how often the side a wallet bought won, minus the average price it paid, over its settled sports and esports markets of $20 or more at a known entry price. Probabilities throughout: edge 0.012 is 1.2 percentage points. The same figures as LeaderboardPriceEdge, plus the shrunk edge the profile badge and the leaderboard show. No hold: a hold is a fact of a leaderboard row, not of the wallet.| Field | Type | Required | Description |
|---|---|---|---|
markets | integer | Yes | Settled sports and esports markets of $20 or more at a known entry price that the edge is measured over. |
hit_rate | number | Yes | Share of those markets whose bought side won, 0-1. |
avg_price | number | Yes | Mean entry price paid, 0-1. |
edge | number | Yes | hit_rate minus avg_price, full precision, before any shrink. |
status | ranked | too_few_markets | sample_mismatch | Yes | Whether the edge ranks. ranked: at least 30 such markets, and the share of the decided ones that made money at settlement within 10 points of the win rate over the same markets. too_few_markets: fewer than 30. sample_mismatch: that share is more than 10 points away, so these markets do not describe the wallet’s record. |
shrunk_edge | number | No | The edge the profile badge shows and the leaderboard ranks: edge pulled toward field_average by how short the record is. A short record moves most of the way to the average; a long one keeps nearly all of its own edge. Present only when status is ranked. |
field_average | number | No | The mean edge of every ranked wallet that traded in the last 180 days, the value shrunk_edge is pulled toward. Present only with shrunk_edge. |
TraderRiskMetrics
Position sizes over the wallet’s sports and esports positions with trades, and how concentrated its volume is across categories. Each measure is an analytic value: read state before value. The four size measures are not_computed while any position’s cost is unknown; the counts are always measured.| Field | Type | Required | Description |
|---|---|---|---|
avg_position_size | AnalyticNumber | Yes | Mean cost basis of a position, USD. |
median_position_size | AnalyticNumber | Yes | Median cost basis of a position, USD. |
max_position_size | AnalyticNumber | Yes | Largest cost basis of a position, USD. |
position_size_stddev | AnalyticNumber | Yes | Population standard deviation of the cost basis, USD. |
total_positions | integer | Yes | Sports and esports positions with trades. |
large_position_count | integer | Yes | Positions whose cost is more than twice the mean. |
concentration | AnalyticNumber | Yes | Herfindahl index of the wallet’s volume across sports and esports categories: each category’s share of the volume, squared and summed. 1.0 is a single category; lower is more spread. not_computed while any category’s cost is unknown, and no value without volume. |
TraderStatsExact
Lossless counterparts for trader statistics. The object is present exactly when stats.total_volume is.| Field | Type | Required | Description |
|---|---|---|---|
total_volume | ExactDecimal | Yes | stats.total_volume as an exact decimal: the sports and esports USD volume, the sum of every stored trade day’s trader_trade_daily_rollups.in_scope_volume_total (#29830). Polymarket’s full-history wallet-wide user volume before 2026-10-27. |
TraderSyncedData
trader_synced data: a tracked wallet finished a sync pass and has a fresh grade. The deprecated spelling whale_trader_synced delivers the same object until its sunset on 2027-02-01 (#29352).
| Field | Type | Required | Description |
|---|---|---|---|
trader_id | integer | Yes | 0xinsider’s numeric id for the wallet. |
wallet | string | Yes | Proxy wallet address. |
TraderTimeBreakdownBand
One band of a time breakdown.| Field | Type | Required | Description |
|---|---|---|---|
category_value | string | Yes | The band’s label. |
n_markets | integer | Yes | Markets with a realized P&L in the band. |
win_rate | number | null | Yes | Resolved markets that made money over resolved markets with a nonzero P&L, 0-1. null when none is decided. |
expectancy | number | null | Yes | total_pnl over n_markets, USD. |
profit_factor | number | null | Yes | Gross profit over gross loss. null when the band has no loss. |
total_pnl | number | null | Yes | Realized P&L of the band’s markets, USD. |
markets_won | integer | No | Additive (since 2026-11-11, #34349): the band’s resolved markets that made money, win_rate’s numerator. Present on every band. |
markets_decided | integer | No | Additive (since 2026-11-11, #34349): the band’s resolved markets with a nonzero P&L, win_rate’s divisor. Present on every band. |
win_rate_status | measured | not_enough_data | No | Additive (since 2026-11-11, #34349): measured from 5 decided markets (markets_decided), not_enough_data below, the floor the 0xinsider profile applies before it shows a band’s win rate, so one lucky market never reads as 100%. Below it win_rate is still sent when present; quote markets_won of markets_decided instead of a rate. Present on every band. |
TraderTimeBreakdowns
The hold-time and first-trade-hour bands of the profile’s Performance breakdown card, over the wallet’s sports and esports markets with a realized P&L.| Field | Type | Required | Description |
|---|---|---|---|
by_duration | array of TraderTimeBreakdownBand | Yes | One row per band of time from the wallet’s first to its last trade in a market: < 1h, 1h – 1d, 1 – 3d, 3 – 7d, 1 – 4w, > 4w. A band with no market is absent. |
by_hour_bucket | array of TraderTimeBreakdownBand | Yes | One row per four-hour UTC band of the wallet’s first trade in a market: 00-03, 04-07, 08-11, 12-15, 16-19, 20-23. A band with no market is absent. |
insights | map of string | Yes | One-line summaries keyed by breakdown (by_duration, by_hour_bucket), from bands of at least 5 markets with a known P&L. A key is present only when there is a summary. |
TraderTrust
Field-level trust metadata returned only when GET /api/v1/trader/{address} includes expand=trust. A field served with a clock takes its data_quality group’s verdict: freshness.status is that group’s fresh or stale, with its as_of and max_age_s, so the two never disagree (since 2026-11-15, #35613).| Field | Type | Required | Description |
|---|---|---|---|
total_pnl | TrustMetadata | Yes | Since 2026-10-27 always not_computed: pnl.total is retired and never sent (#29830). The key stays so the object keeps its shape. |
realized_pnl | TrustMetadata | Yes | Since 2026-10-27 always not_computed: pnl.realized and pnl.exact are retired and never sent (#29830). The key stays so the object keeps its shape. |
net_total_pnl | TrustMetadata | Yes | Since 2026-10-27 always not_computed: pnl.net_total is retired and never sent (#29830). The key stays so the object keeps its shape. |
pnl_correction | TrustMetadata | No | Deprecated since 2026-10-27 and never sent: it was present only with pnl.correction, which is retired (#29830). |
unrealized_pnl | TrustMetadata | Yes | |
markets_traded | TrustMetadata | Yes | Computed, owned by trader_product_scope_records (markets) and dated by the record’s computed_at, since 2026-10-27 (#29830). For a wallet that traded no sports or esports market, which never gets a record, owned by traders (last_synced), the completed sync that found none, and dated by it, since 2026-10-29 (#30589, #30657; owned by traders (markets_traded) until #30657). |
win_rate | TrustMetadata | Yes | Computed, owned by trader_product_scope_records (win_rate) and dated by the record’s computed_at, since 2026-10-27 (#29830). |
daily_win_rate | TrustMetadata | Yes | Since 2026-10-27 always not_computed: stats.daily_win_rate is retired and never sent (#29830). The key stays so the object keeps its shape. |
total_volume | TrustMetadata | Yes | Computed, owned by trader_trade_daily_rollups (in_scope_volume_total) and dated by traders.last_synced, since 2026-10-27 (#29830). |
grade | TrustMetadata | Yes | |
score | TrustMetadata | Yes | |
forecast_score | TrustMetadata | Yes | |
forecast_evidence | TrustMetadata | Yes | |
rank | TrustMetadata | Yes | |
streak_tier | TrustMetadata | Yes | |
strategy | TrustMetadata | Yes | |
category_strengths | TrustMetadata | Yes | |
quant_metrics | TrustMetadata | Yes | |
last_active | TrustMetadata | Yes | |
synced_at | TrustMetadata | Yes | |
sync_status | TrustMetadata | Yes | |
category_records | TrustMetadata | Yes | |
category_skill_model | TrustMetadata | Yes |
TrendingWallet
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Prefixed trader ID (trd_...). |
address | string | Yes | |
rank | integer | Yes | 1-based rank within the full ranked set (stable across pages). |
username | string | No | |
profile_image_url | string | No | Official Polymarket avatar URL (profileImage). |
platform | polymarket | Yes | Real provider platform; surfaced, never coerced. Polymarket only. |
trending_pnl_usd | number | Yes | Polymarket weekly/monthly P&L for the wallet in USD, taken from Polymarket’s canonical leaderboard (data-api.polymarket.com/v2/leaderboard?time_period=week|month&sort_by=PNL). This is the ranking axis and the rows are returned in Polymarket’s by-PNL order; it is the provider’s number, not a locally summed realized-leaf total. |
window_volume_usd | number | No | Both-sides cash volume over the window in USD, from Polymarket GET /v2/user-volume (volume_usdc). Omitted when Polymarket served no volume for the wallet: an absent observation, never zero. Polymarket tracks volume in whole UTC days, so this window is the whole-day span covering the requested one, which is not the exact span trending_pnl_usd was scored over. |
window_volume_shares | number | No | Both-sides traded volume over the window in SHARES, from the Polymarket leaderboard row, whose own schema states the figure is never USD. Omitted when the row carried none. |
window_markets_traded | integer | Yes | |
window_trade_days | integer | Yes | Distinct in-window UTC trade days from our trades (0 if the winner is not in our DB). |
grade | S | A | B | C | D | F | No | All-time trader grade; a separate axis from streak_tier. A grade ranks realized profit on settled sports and esports markets against other graded wallets (since 2026-10-22, the sports and esports share of the wallet’s realized P&L). Win rate, forecasting edge, record length, drawdown and consistency count too, so a smaller earner with a stronger record can rank above a bigger one. S, A and B go only to wallets that have banked a profit on these markets, and the top grades also check record depth, money at stake, edge and the worst drawdown. Relative, so it drifts as the cohort moves. Omitted when the trader is Unranked (fewer than 5 sports or esports markets, or too little verified record to cohort-rank). |
streak_tier | hot | rising | neutral | cooling | cold | No | Hot-streak tier (trailing-7d cross-sectional percentile). Omitted when there is no recent activity. |
in_scope_realized_pnl | number | No | Additive (#29971): the wallet’s sports and esports realized P&L in USD, the same figure as pnl.in_scope.realized_pnl on GET /api/v1/trader/{address} and the 0xinsider profile’s Sports P&L, as of the board’s last rebuild. Context only: it does not affect the ranking, which follows trending_pnl_usd. Omitted when the wallet is not in the 0xinsider database or has no sports and esports record yet: absent means not computed, never zero. |
all_time_pnl_usd | number | No | Deprecated since 2026-10-27 and never sent. It was Polymarket’s net total P&L over every Polymarket market of the wallet, and wallet figures cover sports and esports markets only (#29971). Read in_scope_realized_pnl. |
pnl_correction | PnlCorrection | No | Deprecated since 2026-10-27 and never sent. It was the neg-risk conversion correction to the wallet-wide all_time_pnl_usd (#29971). Its sports and esports part is inside in_scope_realized_pnl. |
all_time_score | number | No | |
last_synced | string | No | |
daily_pnl_series | array of object (date, pnl_usd) | Yes | The wallet’s sports and esports realized P&L on each UTC day of the window, ascending, one point a day, pnl_usd 0 on a day with none: the same in-scope realized day series the trader P&L endpoint serves. Empty while daily_pnl_series_status is pending, which never means zero. It leaves out non-sports markets, so it does not sum to trending_pnl_usd, which is Polymarket’s leaderboard figure across all markets. |
daily_pnl_series_status | ready | pending | Yes | ready when daily_pnl_series is served; an all-zero one is a wallet with no sports or esports P&L in the window. pending when the wallet’s sports and esports record does not carry its daily series yet, or the wallet is not in the 0xinsider database: daily_pnl_series is empty and never means zero. Retry later. |
TrustCompleteness
Whether the described value or result set is complete for its stated contract.| Field | Type | Required | Description |
|---|---|---|---|
status | complete | partial | not_computed | not_applicable | unavailable | Yes | |
detail | string | No |
TrustFreshness
Freshness metadata for a trust-critical value. This is separate from transport cache fields in ResponseMeta.| Field | Type | Required | Description |
|---|---|---|---|
status | fresh | refreshing | stale | not_live | unknown | unavailable | Yes | |
as_of | string | No | |
max_age_s | integer | No |
TrustMetadata
Shared source/freshness/reconciliation/completeness metadata for public API values that may be cached, stale, partial, computed, or provider-unavailable. Unavailable provider values must be represented with explicit metadata instead of fabricated zeros or empty arrays.| Field | Type | Required | Description |
|---|---|---|---|
source | TrustSource | Yes | |
freshness | TrustFreshness | Yes | |
reconciliation | TrustReconciliation | Yes | |
completeness | TrustCompleteness | Yes |
TrustReconciliation
How provider-owned facts were reconciled with stored/read-model values.| Field | Type | Required | Description |
|---|---|---|---|
status | provider_backed | db_mirror | computed | partial | not_applicable | unavailable | Yes | |
detail | string | No |
TrustSource
Source metadata for a trust-critical value. Providers and DB/read models own business truth; clients should not infer missing provider facts from titles, slugs, zeros, or empty arrays.| Field | Type | Required | Description |
|---|---|---|---|
kind | provider | database | cache | computed | client_input | unavailable | Yes | |
owner | string | Yes | Provider, table/read-model, cache, or service that owns the value. |
field | string | No | Provider field, DB column, or computed field name when applicable. |
UpdateWebhookRequest
| Field | Type | Required | Description |
|---|---|---|---|
name | string | No | |
url | string | No | Replacement public HTTPS callback URL on the default port 443, validated and checked for uniqueness exactly like the create url. HTTPS scheme/host case, trailing DNS dots and port 443 normalize; path/query case is preserved. Changing it resets status to pending_verification and returns a new verification token; the new destination must pass the verification challenge before deliveries resume. |
event_types | array of WebhookEventType | No | |
trade_filters | LargeTradeSubscriptionFilters | No | |
price_move_filters | PriceMoveSubscriptionFilters | No | |
settlement_filters | SettlementSubscriptionFilters | No | |
enabled | boolean | No |
Usage
| Field | Type | Required | Description |
|---|---|---|---|
object | string | Yes | |
data | object (rate_limit, daily_usage, monthly_quota) | Yes | |
meta | ResponseMeta | Yes |
VerifyWebhookRequest
| Field | Type | Required | Description |
|---|---|---|---|
verification_token | string | Yes | The one-time token returned on create or on a url change. It is necessary but not sufficient: the destination must also answer the signed webhook.verification challenge with a 2xx. |
WalletGradeChangedData
wallet_grade_changed data (Pro and Max): a tracked wallet’s grade moved on a re-grade.
| Field | Type | Required | Description |
|---|---|---|---|
wallet | string | Yes | Lowercased proxy wallet address. |
trader_id | integer | Yes | 0xinsider’s numeric id for the wallet. |
old_grade | S | A | B | C | D | F | Yes | The grade before the move. Never equal to new_grade. |
new_grade | S | A | B | C | D | F | Yes | |
direction | upgrade | downgrade | Yes | upgrade when new_grade is better than old_grade, else downgrade. |
skill_index | number | Yes | Cohort skill index that drove the grade, 0 to 1. |
final_score | number | Yes | The new grade’s sort key, not a rating out of 100: the cohort percentile times 100, held inside the new grade’s band. |
date | string | Yes | The ranking date of the re-grade. |
WebhookDelivery
Owner-scoped view of one webhook delivery attempt. Deliberately omits the request body and the endpoint signing secret: a delivery log never re-exposes the payload or any secret material.| Field | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | |
object | string | Yes | |
event_id | string | Yes | Stable event id for this delivery; identical across retries of the same logical event. |
event_type | WebhookEventType | Yes | |
status | string | Yes | Delivery lifecycle state (e.g. pending, delivered, dead_letter). |
attempt_count | integer | Yes | Number of delivery attempts made so far. |
last_response_status | integer | No | HTTP status code of the most recent delivery attempt. Omitted until a response (or transport error) has been recorded. |
last_error | string | No | Short description of the most recent delivery failure. Omitted when the last attempt succeeded or none has failed. |
delivered_at | string | No | When the delivery was first accepted by the destination. Omitted until a delivery succeeds. |
next_attempt_at | string | null | Yes | When the next delivery attempt is due, for a delivery whose status is pending or retry. null while an attempt is in flight (processing) and once the delivery is terminal (delivered or dead_letter). |
retry_schedule_reason | receiver_retry_after | transient_failure | permanent_or_auth_failure | manual_redelivery | configuration_changed | null | Yes | Why next_attempt_at was scheduled: receiver_retry_after for an accepted Retry-After on a 408, 429, or 5xx response; transient_failure for a network or ordinary transient retry; permanent_or_auth_failure for another non-2xx response; manual_redelivery or configuration_changed for those queue actions. null while an attempt is in flight or once the delivery is terminal. |
created_at | string | Yes |
WebhookEndpoint
| Field | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | |
object | string | Yes | |
name | string | Yes | |
url | string | Yes | |
event_types | array of WebhookEventType | Yes | |
trade_filters | LargeTradeSubscriptionFilters | Yes | |
price_move_filters | PriceMoveSubscriptionFilters or null | Yes | The market_price_moved settings; null unless that event is subscribed. |
settlement_filters | SettlementSubscriptionFilters or null | Yes | The market_settled settings as stored, defaults filled in; null unless that event is subscribed. |
status | WebhookStatus | Yes | |
verified_at | string | null | Yes | |
verification_token_expires_at | string | Yes | |
failure_count | integer | Yes | |
created_at | string | Yes | |
updated_at | string | Yes | |
retry_policy | WebhookRetryPolicy | Yes | |
secret_rotation | WebhookSecretRotation | Yes | |
signing_secret | string | No | Returned only on create, immediate rotate-secret, staged rotate-secret/prepare, or staged rotate-secret/activate. Never returned by list, get, update, delete, verify, or retire. |
verification | WebhookVerification | No |
WebhookEventDescriptor
Self-describing entry in the webhook event catalog: the event type a subscriber lists in event_types, when it fires, the data payload shape, and whether it currently fires (active) or is reserved (dormant, subscribable but not yet delivered). Pro-only event types (large_trades_inserted, whale_trades_inserted, wallet_grade_changed, suspicious_trade_flagged, insider_radar_flag_raised, sharp_money_flow_detected, smart_money_flow_detected) only deliver to API keys on an active Pro subscription. Export lifecycle event types (export_job_ready, export_job_failed, export_job_expired, export_job_cancelled) are owner-scoped to the API-key account that created the export and contain no download URL; use the authorized export status/download routes. Some entries are two spellings of one event: large_trades_inserted and whale_trades_inserted, trader_synced and whale_trader_synced, suspicious_trade_flagged and insider_radar_flag_raised, sharp_money_flow_detected and smart_money_flow_detected. Either spelling subscribes, and an endpoint receives deliveries under the spelling it registered. The deprecated spellings (whale_trades_inserted, whale_trader_synced, insider_radar_flag_raised, smart_money_flow_detected) reach their sunset on 2027-02-01 (#29352); register the canonical spelling.| Field | Type | Required | Description |
|---|---|---|---|
id | WebhookEventType | Yes | |
description | string | Yes | One-line description of when the event fires. |
payload_shape | string | Yes | Short description of the data payload object’s shape. |
status | active | dormant | Yes | active: the event has a firing producer callsite. dormant: advertised and subscribable, but does not yet enqueue any delivery. |
WebhookEventType
String enum:large_trade_inserted_v2, large_trades_inserted, whale_trades_inserted, live_sports_updated, trader_synced, whale_trader_synced, large_positions_updated, wallet_grade_changed, suspicious_trade_flagged, insider_radar_flag_raised, sharp_money_flow_detected, smart_money_flow_detected, export_job_ready, export_job_failed, export_job_expired, export_job_cancelled, market_price_moved, market_settled.
WebhookRetryPolicy
| Field | Type | Required | Description |
|---|---|---|---|
max_attempts | integer | Yes | |
terminal_status | string | Yes | |
retry_horizon_seconds | integer | Yes | Total wait from a delivery’s first failed attempt to its last retry: 60, 120, 240, 480, 960, 1920 and 3600 seconds. A delivery still failing after that is dead_letter. |
disable_after_consecutive_failures | integer | Yes | Consecutive failed attempts, across all of this endpoint’s deliveries, after which the endpoint is disabled and its queued deliveries are dead-lettered. Any successful attempt resets the count. |
WebhookSecretRotation
| Field | Type | Required | Description |
|---|---|---|---|
status | idle | pending | overlap | Yes | idle when no staged rotation exists, pending after prepare, and overlap after activate while both signing secrets are accepted. |
overlap_expires_at | string | null | Yes | When the previous signing secret stops being emitted and accepted. null outside the overlap phase. |
WebhookStatus
String enum:pending_verification, active, disabled.
WebhookVerification
| Field | Type | Required | Description |
|---|---|---|---|
token | string | Yes | One-time verification token returned only on create or URL change. Pass it to POST /api/v1/webhooks/{id}/verify, which activates the endpoint only when the destination also answers the signed webhook.verification challenge with a 2xx. |
expires_at | string | Yes |
WebhookVerificationAttempt
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | |
object | string | Yes | |
webhook_id | integer | Yes | |
state | queued | running | verified | failed | cancelled | expired | Yes | queued/running are pending consent. verified means the same endpoint revision answered 2xx and activated atomically. failed/cancelled/expired are terminal and do not restart on polling or replay. |
outcome | verified | target_rejected | challenge_timeout | transport_failed | receiver_rejected | token_expired | endpoint_changed | owner_revoked | attempts_exhausted | internal_error | null | Yes | Sanitized last observation. Null before an observation; queued retries may retain their previous failure outcome. |
attempt_count | integer | Yes | |
max_attempts | integer | Yes | |
expires_at | string | Yes | Earlier of the verification-token deadline and 15 minutes after admission. Activation is forbidden at or after this instant. |
next_attempt_at | string | null | Yes | Scheduled retry/admission time while queued; null while running or terminal. |
last_response_status | integer | null | Yes | Actual receiver HTTP status, when one arrived. No receiver response body or resolved address is returned. |
started_at | string | null | Yes | |
completed_at | string | null | Yes | |
created_at | string | Yes | |
updated_at | string | Yes | |
status_url | string | Yes | Relative authorized API path for this attempt. Uses the same bearer credential as admission. |
WhaleDatasetArtifactManifest
| Field | Type | Required | Description |
|---|---|---|---|
manifest_version | string | Yes | Version of the artifact manifest contract. |
format | string | Yes | |
schema_version | string | Yes | |
coverage | string | Yes | |
generation | WhaleDatasetGeneration | Yes | |
row_count | integer | Yes | Number of trade rows written. |
content_size_bytes | integer | Yes | Exact byte count of the decompressed content stream clients receive. |
content_sha256 | string | Yes | Lowercase SHA-256 of the decompressed content bytes. |
compressed_size_bytes | integer | Yes | Exact byte count of the gzip-compressed bytes stored by the object provider. |
compressed_sha256 | string | Yes | Lowercase SHA-256 of the stored gzip bytes; the multipart ETag is not used as this checksum. |
WhaleDatasetContinuation
| Field | Type | Required | Description |
|---|---|---|---|
path | string | Yes | |
cursor | string | Yes | Opaque commit-safe replay cursor; replay the same condition_id and min_size. |
from_commit_xid | string | Yes | Writer floor included by the replay cursor. It can precede the snapshot horizon to include arrivals after the finite window end. |
condition_id | string | null | Yes | |
min_size | string | null | Yes | Normalized USD threshold; pass it to the replay query. |
deduplication_identity | string | Yes | |
time_window_applies_to_deltas | boolean | Yes | |
delivery | string | Yes |
WhaleDatasetFilters
Normalized immutable request; [from, to), maximum 31 days; min_size rounded to cents like durable replay.| Field | Type | Required | Description |
|---|---|---|---|
from | string | Yes | |
to | string | Yes | |
condition_id | string | null | Yes | |
min_size_cents | integer | null | Yes |
WhaleDatasetGeneration
| Field | Type | Required | Description |
|---|---|---|---|
dataset_schema_version | string | Yes | |
id | string | Yes | |
selected_at | string | Yes | |
consistency | string | Yes | |
filters | WhaleDatasetFilters | Yes | |
commit_horizon_xid | string | Yes | All snapshot rows have a writer xid strictly below this closed visibility horizon. Decimal string preserves integer precision. |
continuation | WhaleDatasetContinuation | Yes | |
source | string | Yes | |
coverage | string | Yes | Best-effort detected whale alerts only; not all provider fills. No trader or market enrichment. |
expires_at | string | Yes | |
extraction_elapsed_ms | integer | Yes |
WhaleDatasetJob
| Field | Type | Required | Description |
|---|---|---|---|
object | string | Yes | |
data | object (job_id, status, format, total_trades, processed_trades, file_size, error, terminal, next_action, poll_after_s, created_at, started_at, ready_at, failed_at, expires_at, expired_at, data_as_of, cancel_requested_at, cancelled_at, attempt, max_attempts, artifact, filters) | Yes | |
meta | ResponseMeta | Yes |
WhaleDatasetTrade
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | wt_<whale_alert_id>; deduplication identity shared with expanded replay. |
sequence | string | Yes | Decimal whale-alert ID. |
trader_id | string | Yes | trd_<local trader ID>. |
condition_id | string | Yes | |
platform | string | Yes | |
traded_at | string | Yes | |
side | BUY | SELL | Yes | |
outcome_index | integer | null | Yes | Provider outcome index, null before the canonical outcome trust boundary. |
price | string | Yes | Exact stored NUMERIC price; decimal string. |
size_usd | string | Yes | Exact stored NUMERIC USD notional; decimal string. |
inserted_xid | string | Yes | Writer transaction ID, decimal string. |
trade_event_id | string | Yes | Stored source trade identity. |
source_trade_ingested_at | string | null | Yes | |
clv | object (basis_version, close_anchor_at, close_price, clv_cents, pre_kickoff, status, unavailable_reason, clv_after_fees_cents, taker_fee_cents) | Yes | Closing line value: the clv object of the same trade on /api/v1/large-trades, judged at the generation’s selected_at from close states read inside the same snapshot. A pending row can be measured in a later generation. The close is stored once (GET /api/v1/market/{condition_id}/close), so a measured clv_cents changes only if the market’s kickoff or YES token changes afterwards, which makes it unavailable (anchor_stale, close_token_mismatch). |