Objects - 0xinsider API

These are the objects the API returns, generated directly from the OpenAPI schema so they always match the live contract. Each table lists a field, its type, whether it is always present, and what it means.

AccountIdentity

Field	Type	Required
`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.

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
`object`	string	Yes
`error`	object (`code`, `message`, `doc_url`, `param`, `retry_at`, `freshness`, `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`	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) and omitted otherwise. Always in the future. For pick_not_released: before the 11:00 UTC operating-window start, before a selected pick’s stored release, or after a skipped day, it names the automatic system’s next boundary. While no candidate exists in the live window it normally names the persisted next automatic selector attempt. Every value is advisory and can change before release. When the automatic schedule is absent/due or a pick is overdue it degrades to ~60s. Schedule one request and do not poll. Prefer Retry-After for the duration because it is immune to client clock skew.
`freshness`	`FreshnessFailure`	No
`reason`	`cursor_expired` \| `unknown_endpoint` \| `pick_not_released` \| `trader_not_tracked` \| `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` \| `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` \| `export_expired` \| `freshness_ceiling_unsatisfied`	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 outside the HOT/WARM sync tiers — stop asking for this wallet. 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. monthly_quota_exceeded: the account has used the requests Pro 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.

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
`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 the rendering edge.

Field	Type	Required	Description
`t`	integer	Yes	Bucket-start unix epoch (seconds): 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).

CategorySkillModelReadiness

Model-wide readiness, read in the same database snapshot as category_records. Individual category rows retain their own status.

Field	Type	Required
`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
`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

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`	Yes
`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

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, so a cached body reports the same ages 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` \| `partial` \| `unknown` \| `untracked` \| `unavailable`	Yes	fresh when every group is fresh, unavailable when every group is unavailable, 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` \| `partial` \| `unknown` \| `untracked` \| `unavailable`	Yes	fresh: served, and as_of carries this group’s real observation or computation clock. 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. fresh means the group is tracked and clocked, not that it is inside any particular tolerance: 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.

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
`cache_age_s`	integer	No
`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
`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
`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`	string \| null	Yes
`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
`rep_large_trades`	integer \| null	Yes	Canonical key since #16304; rep_whales is its deprecated spelling, emitted beside it with the same value.
`rep_whales`	integer \| null	Yes

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`	string \| null	Yes
`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
`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.
`whale_trade_count`	integer \| null	Yes
`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.
`whale_distinct_wallets`	integer \| null	Yes
`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.
`whale_total_usd`	number \| null	Yes
`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.
`whale_last_trade_at`	string \| null	Yes
`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
`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`)	No
`freshness`	object (`enrichment_status`, `price_status`)	No

ExploreStandalone

Field	Type	Required	Description
`type`	string	Yes
`market`	`ExploreMarket`	Yes

ExportCompleteness

Field	Type	Required
`status`	`complete` \| `partial` \| `empty`	Yes
`reason`	string	Yes
`sync_coverage`	number	Yes

ExportCounts

Field	Type	Required
`pnl_days`	integer	Yes
`exported_markets`	integer	Yes
`estimated_trade_rows`	integer	Yes
`estimated_size_mb`	number	Yes

ExportSourceRange

Field	Type	Required
`first_pnl_date`	string \| null	Yes
`last_pnl_date`	string \| null	Yes
`latest_trade_at`	string \| null	Yes
`latest_market_activity_at`	string \| null	Yes

ExportVolumeReconciliation

Field	Type	Required	Description
`provider_lifetime_volume`	number \| null	Yes	Verified full-history both-sides USD cash volume. Null without coverage; the local activity numerator may cover only a subset of history.
`exported_activity_volume`	number	Yes
`exported_market_cost_basis`	number	Yes
`provider_activity_volume_gap`	number \| null	Yes
`activity_volume_coverage`	number \| null	Yes

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` \| `partial` \| `unknown` \| `untracked` \| `unavailable`	Yes	The trader body’s whole-response data-quality status. Only fresh can satisfy max_age_s.

Game

One sports or esports game: both sides, its schedule, provider status, linked Polymarket markets and their available provider moneyline price states. 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. For a team league the provider lists the home side first. 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 one of this game’s markets pays on a draw. Read this instead of assuming a two-outcome moneyline.
`markets`	array of `GameMarket`	Yes	Every market this read linked to the game, ordered by condition_id.
`freshness`	`GameFreshness`	Yes
`coverage`	`GameCoverage`	Yes
`url`	string	Yes	The game’s page on 0xinsider.

GameCompetitor

One side of the game.

Field	Type	Required	Description
`name`	string	Yes	The competitor’s name as the provider gives it.
`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 this game’s scores.
`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`	Yes	Which board half produced this game.
`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.
`source_observed_at`	string	No	The source body’s data vintage. Omitted when the read has no vintage anchor, which is not age zero.
`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 live-score frame was observed. Omitted when there is no frame.
`scores_source_at`	string	No	The provider’s own frame clock. Omitted when the frame carries none.

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.
`platform`	string	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. draw is a real value: a 1X2 market’s third leg is not a competitor. Omitted when the provider ids do not classify the leg, 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.

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.

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 calls it scheduled. 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. 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.
`provider_status`	string	No	The provider’s status string, verbatim. Omitted when the provider sent none.
`period`	string	No	The provider’s period label, for example Q3, End Q2 or T5. 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	The provider’s own in-play flag. Omitted when no live-score frame exists, which is not the same as false.
`ended`	boolean	Yes	Whether the game is over. Always present.

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.
`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
`status`	`live` \| `insufficient` \| `stale` \| `unknown` \| `degraded`	Yes
`canonical_category`	string	No
`skill`	`CategorySkillV2`	No

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	Yes
`async_job`	object	Yes
`rate_limit`	object	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`, `markets_traded`)	Yes
`market`	object (`id`, `condition_id`, `title`, `slug`, `event_slug`, `category`)	Yes

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, whose stored outcome_index is not trusted (a defaulted 0 for about a third of those rows; the 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, where the traded side is unknown.
`price`	number	Yes
`review_score`	number	Yes	Current 0.0–1.0 review score, computed at request time from the trade’s size, the trader’s win rate today, a bonus when a trader with a win rate above 55% trades at a price below 30¢, and the trade’s age now. A higher score means read this trade first; it does not measure edge or predict an outcome. On a historical row it is today’s view of the trade, not what a reader saw then; use recorded_review_score for that. Canonical since #16311; signal_score carries the same value.
`signal_score`	number	Yes	Current 0.0–1.0 review score, computed at request time from the trader’s win rate today and the trade’s age now. Deprecated (#16311): `review_score` is the canonical spelling and carries the same value; this key stays on the wire.
`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.
`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: size_usd divided by a market volume figure recorded at or after the trade, so the value always falls between 0 and 1 inclusive. A $10,000 fill is 0.00005 of a$ 200M market and 0.125 of an $80,000 one, which size_usd alone cannot distinguish. Absent when no volume figure recorded at or after the trade is available; 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`)	Yes
`market`	object (`id`, `condition_id`, `title`, `slug`, `category`)	Yes

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

LargeTradeSubscriptionFilters

All present fields narrow large_trade_inserted_v2 delivery. Grade is observed at publication; ungraded trades do not match min_grade. 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.
`min_size_usd`	string	No	Positive USD notional as an exact decimal string.

LeaderboardEntry

Field	Type	Required	Description
`id`	string	Yes
`address`	string	Yes
`username`	string	No
`grade`	string	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	All-time P&L in USD (total_pnl), including unrealized open positions. Kept for back-compat; prefer realized_pnl for the banked figure.
`realized_pnl`	number	No	Native realized P&L plus credited maker and taker rebates in USD, with fees already included. The exact numeric value is truncated toward zero to cents before JSON conversion. Wallets without a native snapshot retain their historical stored realized P&L. Omitted when the native snapshot has no net realized value.
`volume`	number	No	Full-history both-sides USD cash volume from a verified Polymarket user-volume observation. Omitted without coverage.
`markets_traded`	integer	No
`win_rate`	number	No	The wallet’s win rate across ALL categories, not the filtered one. ?category= decides WHICH wallets are listed (the wallet must be ranked in that category); it does not rescope this field, so a soccer-filtered list still reports each wallet’s overall rate. For a per-category record use GET /api/v1/trader/{address}/categories.
`strategy_type`	string	No
`platform`	string	Yes
`last_active`	string	No

MarketCandles

Provider-first bucketed OHLC price candles for a market’s outcome tokens, derived from the stored token_price_snapshots series (covers open and resolved markets).

Field	Type	Required	Description
`condition_id`	string	Yes	Market condition id the candles were read for.
`resolution`	`1d` \| `1w`	Yes	Bucketing granularity that produced these candles.
`outcomes`	array of `OutcomeCandles`	Yes	One entry per present provider token (YES first, then NO); empty when no tokens have been fetched yet.

MarketFlow

Field	Type	Required	Description
`market`	object (`id`, `condition_id`, `title`, `slug`, `category`, `platform`)	Yes
`sharp_money`	object (`net_flow_usd`, `direction`, `token_id`, `large_trade_count`, `whale_trade_count`, `buy_volume_usd`, `sell_volume_usd`, `top_positions`, `oldest_snapshot_as_of`)	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`	object (`net_flow_usd`, `direction`, `token_id`, `large_trade_count`, `whale_trade_count`, `buy_volume_usd`, `sell_volume_usd`, `top_positions`, `oldest_snapshot_as_of`)	Yes	Deprecated alias of sharp_money; byte-identical and retained for backward compatibility.
`timeframe`	string	Yes

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	Shares held on `side`, from the complete provider scan.
`current_value_usd`	number \| null	Yes	Polymarket’s own currentValue for this leg, in USD. 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 resolved markets in that category 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 resolved Polymarket market the wallet traded in the market’s canonical category, at any position size, rebuilt daily. Present only with `category_win_rate_status` = `measured`.
`category_win_rate_game`	string	No	For an esports market, the game `category_win_rate` and `category_win_record` were measured in: `LoL`, `CS2`, `Dota 2`, `Valorant`, `Call of Duty`, `Honor of Kings`, `Mobile Legends: Bang Bang`, `Overwatch`, `Rainbow Six Siege`, `Rocket League` or `StarCraft II`. Present only when the wallet’s record in that game clears the 5-resolved-market floor, in which case the rate and record are the game’s rather than the `Esports` bucket’s. Absent when the rate is the bucket’s (the wallet’s game history is under the floor), on every non-esports 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`	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). Always present on this route.
`category_evidence`	`HolderCategoryEvidence`	No
`wallet_age_days`	number \| null	No	Days since this wallet’s first trade. 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.

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.

MarketHoldersSideGrades

Field	Type	Required
`s`	integer	Yes
`a`	integer	Yes
`b`	integer	Yes

MarketHoldersTotals

Roster totals BEFORE any outcome 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	Polymarket currentValue summed over the graded wallets netting YES.
`no_usd`	number	Yes	Polymarket currentValue summed over the graded wallets netting NO.
`yes_grades`	`MarketHoldersSideGrades`	Yes
`no_grades`	`MarketHoldersSideGrades`	Yes

MarketSearchResult

Field	Type	Required	Description
`id`	string	Yes
`condition_id`	string	Yes
`title`	string	Yes
`slug`	string \| null	Yes
`category`	string \| null	Yes
`platform`	string \| null	Yes
`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.

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`)	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`, `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.

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
`status`	`available` \| `unavailable`	Yes
`source`	string	Yes
`best_bid`	number	No
`best_ask`	number	No
`spread_bps`	integer	No
`bid_depth_usdc`	number	No
`ask_depth_usdc`	number	No
`reason`	string	No

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

McpJsonRpcError

Field	Type	Required
`jsonrpc`	string	Yes
`id`	string or number or null	No
`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).
`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
`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 and is labelled with it): the share of the wallet’s resolved markets in that category 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 resolved-market floor; recomputed at serve time from the current category read model, not frozen with the pick. 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 resolved Polymarket market the wallet traded in the pick’s canonical category (or in its game, 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_win_rate_game`	string	No	For an esports pick, the game `category_win_rate` and `category_win_record` were measured in, by the same name the pick’s `display_category` uses for it: `LoL`, `CS2`, `Dota 2`, `Valorant`, `Call of Duty`, `Honor of Kings`, `Mobile Legends: Bang Bang`, `Overwatch`, `Rainbow Six Siege`, `Rocket League` or `StarCraft II`. Present only when the wallet’s record in that game clears the 5-resolved-market floor, in which case the rate and record are the game’s rather than the `Esports` bucket’s. Absent when the rate is the bucket’s (the wallet’s game history is under the floor), on every non-esports 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`	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 resolved-market floor of 5 in the category), or `unavailable` (the annotation read failed; retry later). Absent entirely on `holders` entries, legacy rows, and payloads predating the field — absence means the roster was never annotated, not a small sample.
`wallet_age_days`	number \| null	No	Days since this wallet’s first trade. 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_evidence`	`HolderCategoryEvidence`	No

PickOfTheDay

Field	Type	Required	Description
`state`	`full`	Yes	Always ‘full’ for an authenticated Pro key.
`pick_date`	string	No	The pick’s local publication date (YYYY-MM-DD).
`pick_rank`	integer	No	Stable 1-based slot within the product day’s ranked picks.
`picks`	array of `PickOfTheDay`	No	The complete ranked picks for this product day, ordered by pick_rank. Thin days contain fewer items; the selector never fabricates rows.
`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	Same-day picks selected but not yet released, ordered by pick_rank. Additive and optional: present only while at least one unreleased slot exists. Each slot exposes only its rank and schedule — no market identity before release. Schedule the next read from the earliest release_at instead of polling.
`matchup`	string	No	Human-readable matchup (e.g. “Portugal vs. Uzbekistan”).
`category`	string	No	Frozen canonical calibration/report 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. For supported Polymarket sports this is the exact verified provider event identity: an official league (e.g. “WNBA” or “UFC”), the esports title (e.g. “CS2”, “LoL”, “Dota 2” or “Valorant”), or a soccer competition whose official mark we vendor (e.g. “LaLiga”, “Premier League”, “Serie A” or “UEFA Champions League”). Only identities with a vendored official mark are split out; every other competition keeps its canonical bucket, so “Soccer” remains a live value; otherwise it equals category. An esports pick keeps the pooled “Esports” bucket in category, so a per-title label never implies a per-title measured cohort. Additive and optional for mixed-version client compatibility.
`platform`	string	No	Provider platform (e.g. “polymarket”).
`release_at`	string	No	The pick’s stored release instant. Normally the current provider kickoff minus one hour; an operator may override it. The actual publish instant can trail it because of worker or claim delay.
`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’s kickoff has passed (kickoff <= now). When true the snapshotted pre-game price is no longer actionable. Absent for a legacy pick with no stored kickoff (treat as not-started).
`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 phrased as a bet: a team for a moneyline (e.g. “Portugal”), the handicap line for a spread (e.g. “Belgium (-2.5)”), 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 phrased as a bet (e.g. “Portugal to win”).
`side_summary`	string	No	One-line summary of which side sharp money is backing. 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	Public V1 compatibility count of S/A sharp-money wallets on the backed side. The first-party/internal current policy counts S/A/B; historical rows retain their frozen policy’s count. 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. Canonical key since #16308; smart_wallet_count is its deprecated spelling, emitted beside it with the same value.
`smart_wallet_count`	integer	No	Deprecated spelling of sharp_wallet_count, emitted beside it with the same value and never removed. Public V1 compatibility count of S/A sharp-money wallets on the backed side. The first-party/internal current policy counts S/A/B; historical rows retain their frozen policy’s count. 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.
`top_grade`	string	No	Best public V1-compatible S/A sharp-money grade on the backed side. The first-party/internal current policy can select B, but a current B-only grade is omitted by the stable V1 adapter. Historical rows retain their frozen policy’s grade. A current-day published pick with pending legacy proof, unknown-future proof, or structurally invalid current-policy proof returns 503 before this success schema is served. Resolved legacy proof remains readable on both current-day and archive/history responses.
`category_edge_pct`	number	No	Deprecated (#7170): no longer populated for picks selected on/after the calibration-edge change; omitted (absent) for new picks (the field uses skip_serializing_if, so a null value is dropped from the JSON rather than serialized as null). Permanently frozen-legacy — retained for historical picks, with no removal or replacement planned, so no v2 is implied. Historical picks may still carry a value. Legacy meaning: category win-rate edge as a fraction (the backed-side cohort’s win rate in this category minus the non-market-maker category baseline, e.g. 0.09 = +9 points), paired with category_edge_sample.
`category_edge_sample`	integer	No	Deprecated (#7170): no longer populated for picks selected on/after the calibration-edge change; omitted (absent) for new picks (the field uses skip_serializing_if, so a null value is dropped from the JSON rather than serialized as null). Permanently frozen-legacy — retained for historical picks, with no removal or replacement planned, so no v2 is implied. Historical picks may still carry a value. Legacy meaning: pooled count of resolved markets behind category_edge_pct (the headline’s n).
`sharp_usd`	number	No	Recency-weighted graded-flow magnitude in USD; omitted when <= 0. Canonical key since #16308; smart_usd is its deprecated spelling, emitted beside it with the same value.
`smart_usd`	number	No	Deprecated spelling of sharp_usd, emitted beside it with the same value and never removed. Recency-weighted graded-flow magnitude in USD; omitted when <= 0.
`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	First-party/internal backed-side sharp-money dollar consensus as a fraction 0..1: the share of current-policy sharp dollars on the backed side. Omitted on current public V1 rows when the B-inclusive value has no reconstructible S/A equivalent. A conviction signal, NOT a probability or expected-value claim. Frozen at generation.
`market_pct`	number	No	Market-implied probability of the backed side as a fraction 0..1 (equals backed_price), re-exposed alongside sharp_pct for the WHY breakdown.
`consensus_edge_pct`	number	No	First-party/internal consensus edge = sharp_pct - market_pct, the conviction-vs-price gap (how much more of the current-policy sharp money sits on this side than the price implies). Omitted on current public V1 rows when the B-inclusive value has no reconstructible S/A equivalent. This is NOT an expected-value or guaranteed edge. Omitted when either input is unavailable.
`directional_confidence`	number	No	First-party/internal team-directional commitment read at selection time: the fraction (0..1) of the backed side’s current-policy graded sharp-money DOLLARS held by wallets read one-way rather than hedged: no opposite leg on this market worth at least 10% of the backed leg (Polymarket’s own currentValue pair), and no opposing team across the game’s markets where the wallet’s synced legs are fresh. Current public V1 rows omit this B-inclusive read because its historical S/A equivalent is not reconstructed. A high value means the graded pile is really committed to this side; a low one means much of it is hedged or unreadable. Omitted when the read was not computed (a pick selected before the field existed, an ungroupable game, an empty graded pile, or a pile where no holder carried usable evidence) — which is NOT the same as 0.0, a computed reading that classified holders and found none one-way.
`one_way_holder_count`	integer	No	Graded backed-side holders read as one-way-committed on this game.
`hedged_holder_count`	integer	No	Graded backed-side holders read as HEDGED across the game’s markets.
`one_way_graded_usd`	number	No	The one-way holders’ share of the backed-side graded dollars (the confidence’s numerator).
`total_graded_usd`	number	No	Backed-side graded dollars the confidence is measured against (its denominator).
`qualifying_expert`	object (`address`, `name`, `grade`, `canonical_category`, `win_rate`, `n_resolved`, `source`, `edge_lower_95`, `edge_mean`, `independent_event_count`, `position_usd`, `opposite_position_usd`, `stats_computed_at`, `lane`, `lane_probability`, `lane_probability_source`)	No	The qualifying category expert whose sport-specific record and real position earned this pick its top selection tier. The first-party/internal current policy admits S/A/B; public V1 exposes a compatible S/A expert and omits a current-policy B-grade expert: a candidate backed by one outranks every candidate without one. Present only on the full payload. Omitted when no wallet qualified on the backed side, on picks generated before the field existed, and on the first-party web teaser, which withholds all backed-side evidence. Frozen at SELECTION time — the wallet’s position can move before the pick renders.
`trust`	`PickTrust`	No
`traders`	integer	No	Public V1 S/A compatibility count on the backed side (equals the adapted sharp_wallet_count). The first-party/internal current policy counts S/A/B. Historical rows retain their frozen policy’s count.
`backed_sharp_usd`	number	No	Raw backed-side sharp-money USD frozen at generation. This is the Sharp USD value, not the recency-weighted sharp_usd which decays. Omitted on current public V1 rows when the B-inclusive value has no reconstructible S/A equivalent.
`holders`	array of `PickHolder`	No	Bounded S/A compatibility projection of the frozen sharp-money holders on the backed side. Current full payloads expose the complete S/A/B roster in display_holders; historical rows can retain their earlier frozen shape.
`display_holders`	array of `PickHolder`	No	Full-only complete provider-confirmed S/A/B holder roster for the current Pick of the Day backing policy. Omitted for teaser, no-pick, and historical rows whose frozen holder proof predates this policy. Each entry may additionally carry `category_win_rate` / `category_win_rate_status`: the wallet’s win rate in the pick’s canonical `category`, stamped at serve time from the current category read model (the same annotation the sports sharp-money chips carry). The bounded `holders` compatibility projection never carries these fields.
`holder_count`	integer	No	Exact S/A sharp-money proof count on the backed side. The current display_holders roster can be longer because it also carries B-grade sharp-money holders.
`editorial_note`	string	No	Optional editorial note attached to the pick.
`thesis`	string	No	Required truthful thesis. With at least one profitable-wallet holder: Profitable wallets hold {pick_outcome_label}[, led by a grade-{top_grade} trader]. Without holder backing: 0xInsider’s Pick of the Day is {pick_outcome_label}. Wallet counts are not appended.
`market_url`	string	No	Canonical web market URL.
`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	No	Backend-resolved /event destination slug for this pick’s source market; its absence 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	Published same-day picks whose holder proof is not readable yet, ordered by pick_rank. Additive and optional: present only while at least one such pick exists. While present, `picks` carries only the proof-readable picks and `pick_count` counts them. Schedule the next read from the earliest retry_at instead of polling. The route returns 503 read_model_warming only when no published pick has readable proof.
`selection_lane`	`standard` \| `longshot_specialist`	No	Frozen admission classification, full payload only. The specialist lane exempts two probability rejects and adds no rank bonus. Historical rows remain standard.
`entry_authorization`	`PotdEntryAuthorization`	No	Optional full-only authorization for newly issued policy-7 picks; omitted for legacy or unissued picks and teasers. It remains historical after expiry.

PickOfTheDayArchive

Field	Type	Required	Description
`picks`	array of `PickOfTheDayArchiveEntry`	Yes	Every published Pick of the Day, newest first by pick_date and then pick_rank within each product day.
`days`	array of `PickOfTheDayArchiveDay`	Yes	One entry per product day that has a published pick, 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

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 (stake refunded).
`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, decided (win/loss) picks: the same population staked_usd runs over. Omitted when the day has not scored — every pick still pending, every pick 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	No	Stable 1-based slot within the product day’s ranked picks.
`matchup`	string	Yes	Human-readable matchup (e.g. “Portugal vs. Uzbekistan”).
`category`	string	Yes	Frozen canonical calibration/report 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. For supported Polymarket sports this is the exact verified provider event identity: an official league (e.g. “WNBA” or “UFC”), the esports title (e.g. “CS2”, “LoL”, “Dota 2” or “Valorant”), or a soccer competition whose official mark we vendor (e.g. “LaLiga”, “Premier League”, “Serie A” or “UEFA Champions League”). Only identities with a vendored official mark are split out; every other competition keeps its canonical bucket, so “Soccer” remains a live value; otherwise it equals category. An esports pick keeps the pooled “Esports” bucket in category, so a per-title label never implies a per-title measured cohort. Additive and 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	Best public V1-compatible S/A sharp-money grade on the backed side; a current B-only grade is omitted by the stable V1 adapter, while historical rows retain their frozen policy’s grade. Omitted when no sharp-money wallet backs the pick, when a pending legacy proof has not yet upgraded, or when the stored holder policy is unknown-future or structurally invalid. Resolved legacy history remains supported.
`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.
`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, a loss returns 0, a void refunds stake_usd. A loss always returns 0 (the whole stake is lost regardless of price). The operand is published beside it as backed_price on exactly the same rows, so the entry never has to be recovered by inverting this number. Omitted (not null) only for a still-pending pick or 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, a void 100), 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, 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 exactly when return_usd is, so it is omitted for a 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.

PickOfTheDayCommitmentPayload

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`	string	Yes	Provider platform.

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	No	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 decided picks: a priced win pays stake_usd/backed_price - stake_usd, every visible loss pays -stake_usd independent of price, and a void pays 0. 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 decided picks: every visible loss plus every priced win. Void, 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`)	No	Cumulative track-record series, one point per decided (win/loss) pick in ascending pick_date order (void and pending 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.

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. Read state 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	1-based daily slot within the product day.
`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.
`matchup`	string	Yes	Frozen matchup, for a reader.
`category`	string	Yes	Frozen canonical sport bucket used for selection calibration (Basketball, MMA), not the exact public league identity; the archive owns that.
`permalink`	string	Yes	The pick’s public page.

PickOfTheDayLedgerSealedEntry

A published pick that has not settled. Carries the commitment and nothing that states a side or a price: no nonce, no payload, no outcome. Publishable the instant the pick releases.

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	1-based daily slot within the product day.
`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.
`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.
`permalink`	string	Yes	The pick’s public page.

PickOfTheDayLedgerUncommittedEntry

A published pick with no commitment: it predates the scheme, or it reached kickoff unsealed. Nothing here is evidence of WHEN the pick was made. It is emitted rather than skipped, because a ledger with holes where the unprovable picks were would silently flatter the record. Once the pick settles, payload names its market, side and price, so the outcome can still be checked against the market’s own resolution.

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	1-based daily slot within the product day.
`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.
`matchup`	string	Yes	Frozen matchup, for a reader.
`category`	string	Yes	Frozen canonical sport bucket used for selection calibration (Basketball, 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 public page.

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`	string	Yes	Provider platform.

PickSportsContext

Provider-first sports context for a Pick of the Day market: team crests, league branding, and live score. Team logos and league logo are provider-owned (Polymarket /teams crests for clubs, country flags for national teams and tennis players); no local derivation.

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. 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` \| null	Yes	The team mapped to the market’s YES outcome, or the parent-event home/first team when event_matchup is true.
`no_team`	`PickSportsTeam` \| null	Yes	The team mapped to the market’s NO outcome, or the parent-event away/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).
`matchup_title`	string	No	The two teams as a single whole-game label, joined “<home> – <away>” (en-dash) in provider display order (e.g. “Portugal – Uzbekistan”). 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, 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	Abbreviated team label (e.g. “POR”).
`full_name`	string \| null	Yes	Full team or competitor name (e.g. “Portugal national football team”).
`provider_id`	integer \| null	Yes	Provider team identifier (Polymarket /teams id).
`logo`	string \| null	Yes	Team crest or flag URL. Provider-owned for most teams (Polymarket /teams crest for clubs, country flag for national teams and tennis players). A club with a vendored crest carries it instead, served same-origin as a relative path (`/api/sports/team-logos/{league}/{abbr}.svg?v=<content hash>` or `.png`, resolve it against this server): every NFL and WNBA team, whose provider asset is a text tile, and the soccer clubs whose provider asset is an empty object.
`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.

PickTrust

Field-level trust metadata for the full Pick of the Day payload. Present on the full shape only (omitted on the teaser and the no-pick state, because whether a specialist backs the pick is itself backed-side evidence). Unlike TraderTrust it is not gated behind expand=trust: it carries one member on an endpoint that returns a single object per day.

Field	Type	Required	Description
`qualifying_expert`	`TrustMetadata`	Yes	Provenance of the frozen qualifying category expert. source.kind=database with reconciliation.status=db_mirror means the evidence deserialized, still satisfies every frozen selection gate, and is being served. On that arm freshness.status is always not_live and never fresh, because this evidence is frozen at selection and never refreshed, so on an archived pick the as_of (the expert’s own stats_computed_at) can be days or months old by design. source.kind=computed with reconciliation.status=not_applicable means the selector evaluated the backed side and nobody qualified — a real negative. source.kind=computed with freshness.status=unknown and completeness.status=not_computed means the selector never evaluated this field, as on a pre-feature pick. source.kind=unavailable means the payload is malformed, violates a selection gate, or conflicts with its persisted status, or the public V1 adapter intentionally omitted a current-policy B-grade expert; read the reason before treating it as a negative. Do not read an omitted qualifying_expert as ‘no specialist’ without checking this field.

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.
`whale_signal`	`PlatformCapabilityStatus`	Yes
`suspicious_trades`	`PlatformCapabilityStatus`	Yes
`insider_radar`	`PlatformCapabilityStatus`	Yes
`market_snapshot`	`PlatformCapabilityStatus`	Yes

PlatformCapabilityStatus

String enum: supported, partial, unsupported.

Platforms

Field	Type	Required	Description
`platforms`	object (`polymarket`)	Yes

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`, `markets`, `wallet_age_days`, `is_new_wallet`)	Yes
`market`	object (`id`, `condition_id`, `title`, `slug`, `event_slug`, `category`, `outcome_label`, `end_date`)	Yes

PositionExact

Lossless position atoms from wallet_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	Prefixed ID (pe_…).
`event_timestamp`	string	Yes	ISO 8601 timestamp of the on-chain fill.
`action`	`buy` \| `sell`	Yes	From the taker’s perspective.
`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	Yes	Polygon transaction hash of the fill.
`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.

PotdEntryAuthorization

Policy-7 issuance binds one condition, selected token, outcome, canonical event and sport. Reuse the same authorization across public/private discovery and retries. Require a new account-size executable book and current market eligibility; this frozen reference does not prove current liquidity or positive expected value. Absence or expiry cannot authorize a new automated entry.

Field	Type	Required	Description
`version`	`1`	Yes
`authorization_id`	string	Yes
`policy_version`	`7`	Yes
`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	Immutable decimal limit: first fresh selected-token ask plus 0.02, floored to the provider tick below 1. Fees excluded. Never a calibrated fair probability.
`reference_best_ask`	string	Yes
`reference_book_hash`	string	Yes
`reference_book_at`	string	Yes
`issued_at`	string	Yes
`expires_at`	string	Yes	Original provider kickoff ceiling. Never extended on retry.

PreGameSide

One ranked pre-game sports market where graded sharp money is piled on one side, with required-status shadow 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	Grade-weighted holders times the share of their money on the side: (5s + 4a + 3b) sharp_pct. Canonical spelling of conviction_score (#16310), same value.
`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`	string \| 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); a lower-order ranking tiebreak (after directional_rank_score and conviction_score). Deprecated (#16310): `side_share` is the canonical spelling and carries the same value; this key stays on the wire.
`volume`	number \| null	Yes	Market volume (USD).
`net_side`	`BUY` \| `SELL` \| null	Yes	Aggregate recent flow direction on the market; null when unavailable.
`conviction_score`	number	Yes	Grade-weighted pile score (5s + 4a + 3b) sharp_pct; the raw conviction input to the ranking (see directional_rank_score). Deprecated (#16310): `backing_score` is the canonical spelling and carries the same value; this key stays on the wire.
`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 of the piled graded dollars, in [0, 1] — the metric orthogonal to sharp_pct. Stale, unknown, hedged, and two-sided dollars dilute it toward zero (conservative). Null when the directional read was not computed or classified nobody.
`directional_rank_score`	number	Yes	The ranking key, descending: conviction_score * (1 + 0.25 * directional_confidence). Equals conviction_score when the directional read is null/zero, so signals without the read rank exactly as before.
`category_skill`	`PreGameSideCategorySkill`	Yes
`rank`	integer	Yes	1-based rank within the (min_grade-filtered) ranked result.

PreGameSideCategorySkill

Shadow-only 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
`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

PreGameSideFunnelReport

Per-sport accountable funnel for the full observation snapshot, returned on every page.

Field	Type	Required	Description
`sports`	array of `PreGameSideSportFunnelReport`	Yes

PreGameSideObservation

One explicitly observation-only holder-pile measurement. It is evidence for cohort evaluation, not an execution instruction, and is isolated from the funded sports-edge-signals route.

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	Grade-weighted holder-pile score before directional enrichment. Canonical spelling of conviction_score (#16310), same value.
`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.
`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	Provider-backed implied price for the piled outcome at observation time.
`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	Strictly positive stored market volume in USD. Missing, zero, or non-finite volume terminates as invalid_market and is never emitted as an observation.
`conviction_score`	number	Yes	Grade-weighted holder-pile score before directional enrichment. Deprecated (#16310): `backing_score` is the canonical spelling and carries the same value; this key stays on the wire.
`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 neither provider outcome holder page hit the top-100 scan bound. False means the pile is a positive lower bound and 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. 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	Default cohort ordering key: conviction_score * (1 + 0.25 * directional_confidence), or conviction_score when confidence is null.
`rank`	integer	Yes	1-based rank within this observation cohort and snapshot.

PreGameSideObservationTerminalReason

Closed 25-value terminal-reason vocabulary for the accountable sports-edge 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 an attempted holder-provider failure; holder_deadline_unavailable is holder cache/provider absolute-deadline exhaustion. 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.

PreGameSideSportFunnelReport

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 (it reads unknown, i.e. no recorded cause, only on a snapshot cached before that field existed, which self-clears within one TTL): 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 NCAAB and 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 3,000 rows or 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: exactly one cause — a snapshot cached before this field existed whose legacy flags recorded an unavailable-but-configured half without saying why. Every freshly computed snapshot reports a concrete status, and a legacy available or not-configured row is reconstructed exactly, so unknown self-clears within one TTL. board_upcoming_available is exactly board_upcoming_status == available.
`board_upcoming_unavailable_scopes`	array of `category` \| `nfl` \| `cfb` \| `nba` \| `wnba` \| `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, 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 exact admission by the funded route’s raw shared signals query before provider/holder enrichment; recent-flow rows rejected by its event, bucket, or total caps remain eligible for wider_holder measurement. 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 an attempted holder-provider read failed; holder_deadline_unavailable means holder cache/provider work missed the absolute request deadline; 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.

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 in picks 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	Stable 1-based slot within the product day’s ranked picks. The pick keeps this rank once its proof is readable and it moves into `picks`.
`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.

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.
`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.
`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`) \| null	Yes	Canonical key since #16304; top_whale_trades is its deprecated spelling, emitted beside it with the same value.
`top_whale_trades`	array of object (`outcome`, `side`, `title`, `size`, `price`, `token_id`, `id`, `trade_time`, `market_category`, `platform`, `name`, `pseudonym`, `trader_grade`) \| null	Yes
`categories`	array of object \| null	Yes
`grade_distribution`	array of object \| 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.

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
`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
`start_date`	string	Yes
`end_date`	string	Yes
`timezone`	string	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.
`directional_source`	`live` \| `degraded`	No	Which path produced the team-directional read on this response. Only present on endpoints that compute one (today: GET /api/v1/sports-edge-signals). “live” means the read RAN. “degraded” means it FAILED, so nothing was measured and the ranking fell back to raw conviction. The flag describes the READ, not its consequence: a read that ran and found nothing groupable also leaves the directional fields null, and that is honestly “live” — the per-signal nulls already say “nothing to enrich here”, so this snapshot-level flag carries only what they cannot, namely whether the read ran at all. A degraded response is cached on the shorter degraded TTL so it self-heals. Reported SEPARATELY from ranking_source because the two degradations are independent — a sharp-money DB miss weakens the ranking DATA, a directional failure removes a ranking WEIGHT — and a consumer down-weighting a degraded response needs to know which input it lost. Omitted on endpoints that compute no directional read.
`ranking_source`	`live` \| `db_only`	No	Which ranking-data path produced this response. Only present on endpoints that can degrade a ranking (today: GET /api/v1/sports-edge-signals). “live” is the normal path (the current holder pile from the provider batch); “db_only” is the degraded fallback (a truthful but weaker trader_markets ranking) served when the live sharp-money ranking batch is unavailable (a sharp-money DB read failure, not a Polymarket outage) and cached on a shorter TTL, so a consumer can down-weight or skip it. Omitted on endpoints that never degrade.
`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 sports-edge-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. Sports-edge-signals 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 shadow enrichment did not change funded inputs. Sports-edge-signals only.

ScheduledPickSlot

One same-day pick that is selected but not yet released: its stable slot rank plus the backend-owned release and kickoff instants. Deliberately minimal — no matchup, category, platform, side, price, or holder fields exist on this shape before release.

Field	Type	Required	Description
`pick_rank`	integer	Yes	Stable 1-based slot within the product day’s ranked picks. The slot keeps this rank when it releases.
`release_at`	string	Yes	The slot’s scheduled release instant, normally the current provider kickoff minus one hour. The actual publish can trail it by bounded worker delay.
`kickoff`	string	Yes	The backed game’s current kickoff instant.

ScoreCell

One side’s score in a single set. The verbatim provider text stays on the team’s score 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.

SmartMoneyFlowMarket

Field	Type	Required	Description
`market`	object (`id`, `condition_id`, `title`, `slug`, `category`, `platform`)	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 and retained for backward compatibility.
`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	No	Canonical key since #16304; covered_days_with_whale_activity is its deprecated spelling, emitted beside it with the same value.
`covered_days_with_whale_activity`	integer	Yes

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.

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`)	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.

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	Capital-normalized forecasting score: the cohort percentile (0-100) of the EB-shrunk calibration edge. Omitted when the forecasting signal is unavailable; never replaced with zero.
`forecast_evidence`	number	No	Share of forecast_score supported by the trader’s own resolved-market record rather than the cohort prior: n / (n + 30). Omitted when forecast_score is unavailable.
`rank`	integer	No
`pnl`	object (`total`, `realized`, `unrealized`, `last_7d`, `last_30d`, `exact`)	Yes
`stats`	object (`markets_traded`, `win_rate`, `daily_win_rate`, `total_volume`, `exact`)	Yes
`strategy`	object (`strategy_type`, `description`, `confidence`)	No
`category_strengths`	object	No	Per-category performance breakdown (expand=categories or expand[]=categories). Omitted unless expanded. Object keyed by category name; each value is the precomputed trader_rankings.category_ranks payload (rank, total_in_category, total_pnl, scaled_total_pnl, n_markets, wins, losses, win_rate; scaled_total_pnl is a legacy alias that currently equals total_pnl). BASIS: the calibration sample, which admits a position only above a 20 USD notional floor and with a chosen-side entry price strictly inside (0,1), because the ranks and the calibration edge derived from it depend on both rules. That is a different sample from GET /api/v1/trader/{address}/categories, which counts every settled market at any size, and 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, lower in 34.5% and equal in 9.0%, median +0.6 points, p10 -4.6, p90 +9.8, and 14.0% of pairs differ by 10 points or more. The difference is not only small positions: on a 1-in-250 wallet sample the same day, admitted markets won 56.6% while markets dropped by the notional floor alone won 45.2% and markets dropped by the entry-price rule alone won 48.7%. n_markets counts every admitted market including the ones that resolved at exactly zero P&L, so it is not the denominator of win_rate: it differed from wins + losses in 15.8% of pairs with at least 5 decided markets. The two tables also run on different clocks, this one updated incrementally and that route rebuilt daily, so a same-day read can differ on timing alone. Use this for rank context and that route for the wallet’s plain record. Pass-through DB JSON: keys and value shape are DB-owned, so the inner shape is intentionally unconstrained and may carry 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	Curated advanced risk/performance metrics (expand=quant_metrics or expand[]=quant_metrics). Omitted unless expanded and backed by a computed row strictly under six hours old; a missing row, NULL computed_at, or age of exactly six hours or more is stale and omitted. Provider-input changes may intentionally lag inside the bounded six-hour window. When present, all listed fields are present (each is a number or null); null means insufficient trade history and must not be treated as 0. The fixed field shape is unchanged.
`last_active`	string	No
`synced_at`	string	No
`sync_status`	string	No	synced, unknown, or pending.
`data_quality`	`DataQuality`	Yes	Data age and coverage for this trader body. Always present. Its five groups are sync (traders.last_synced, covering pnl.total, pnl.realized, stats.markets_traded, stats.win_rate, stats.daily_win_rate, last_active, synced_at and sync_status), 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 (trader_usd_volume.observed_at, covering stats.total_volume) and positions (trader_position_snapshots.last_refreshed_at with traders.last_synced as fallback, covering pnl.unrealized, the open-position aggregate). The positions clock is the latest successful /positions snapshot when one exists, otherwise the last completed trader sync; it does not date closed or native accounting values. 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.
`category_skill_model`	`CategorySkillModelReadiness`	No

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.
`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.

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 rows included, which the daily rebuild 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.

TraderContext

Field	Type	Required	Description
`trader`	`Trader`	Yes
`position_summary`	object (`markets_total`, `markets_synced`, `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. 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 date to the last full sync; native realized P&L follows its accounting snapshot — not a live feed; re-fetch for fresher data).

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 daily 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
`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

TraderExportJob

Field	Type	Required
`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
`source`	string	Yes
`coverage`	string	Yes
`revision`	integer \| null	Yes
`observed_at`	string \| null	Yes

TraderExportPositionWatermark

Field	Type	Required
`source`	string	Yes
`coverage`	string	Yes
`generation`	integer \| null	Yes
`data_as_of`	string \| null	Yes

TraderExportSnapshot

Field	Type	Required
`address`	string	Yes
`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
`positions`	`TraderExportPositionWatermark`	Yes
`pnl`	`TraderExportPnlWatermark`	Yes
`categories`	`TraderExportCategoryWatermark`	Yes
`trades`	`TraderExportTradeWatermark`	Yes

TraderExportTradeWatermark

Field	Type	Required
`source`	string	Yes
`coverage`	string	Yes
`rows`	integer	Yes
`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.

TraderPnl

A trader’s daily P&L object. id is 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.

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 for this trader’s PnL history = traders.daily_pnl_recomputed_at, when the daily_pnl read model this response is served from was last rebuilt; null when it has never been recomputed for the trader. Always present, so read it as a value that can be null rather than a key that can be missing.
`entries`	array of object (`date`, `markets_traded`, `total_volume`, `cumulative_profit`, `total_pnl`, `daily_change`)	No	Daily cumulative-P&L series (oldest-first). Present unless the request’s `sections` excluded it, and clipped to `from`/`to` when either is set. cumulative_profit and total_pnl stay cumulative from the start of the stored 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

Lossless counterparts for trader P&L values. The object is omitted when no trusted native realized-P&L snapshot is available.

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.

TraderStatsExact

Lossless counterparts for trader statistics. The object is omitted when the verified provider observation is unavailable.

Field	Type	Required	Description
`total_volume`	`ExactDecimal`	Yes	Full-history both-sides Polymarket user-volume atom from the verified `trader_usd_volume` observation.

TraderTrust

Field-level trust metadata returned only when GET /api/v1/trader/{address} includes expand=trust.

Field	Type	Required
`total_pnl`	`TrustMetadata`	Yes
`realized_pnl`	`TrustMetadata`	Yes
`unrealized_pnl`	`TrustMetadata`	Yes
`markets_traded`	`TrustMetadata`	Yes
`win_rate`	`TrustMetadata`	Yes
`daily_win_rate`	`TrustMetadata`	Yes
`total_volume`	`TrustMetadata`	Yes
`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/v1/leaderboard?timePeriod=week\|month&orderBy=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. Led by realized profit (the money actually banked, about 95 percent of the grade), with forecasting calibration, risk-adjusted returns, and consistency as the tie-breaker and proven-trader guardrails: any grade above C requires verified net-positive realized profit, and the top grades also require a real resolved-market track record plus a survivable drawdown. Relative, so it drifts as the cohort moves. Omitted when the trader is Unranked (fewer than 5 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.
`all_time_pnl_usd`	number	No
`all_time_score`	number	No
`last_synced`	string	No
`daily_pnl_series`	array of object (`date`, `pnl_usd`)	Yes	Shape-only daily P&L sparkline across the window, derived from Polymarket’s documented user-pnl cumulative curve (GET /v2/user-pnl) converted to per-day deltas. It conveys the trend of the curve only and is NOT guaranteed to sum to trending_pnl_usd, which is the canonical leaderboard total.

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
`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
`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
`enabled`	boolean	No

Usage

Field	Type	Required
`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.

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
`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.

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.

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

​AccountIdentity

​AgentRegistration

​ApiDiscovery

​ApiError

​ApiErrorBody

​BatchMarketFlowItem

​BatchRateLimitMeta

​BatchResponseMeta

​BatchTraderItem

​Candle

​CategorySkillModelReadiness

​CategorySkillV2

​ContentSearchResult

​CounterpartyAnalysis

​CounterpartyExecution

​CounterpartyMakerPage

​CounterpartyMatchBreakdown

​CounterpartyParticipant

​CreateWebhookRequest

​DataQuality

​DataQualityGroup

​EventReplayEvent

​EventReplayFreshness

​EventReplayMeta

​EventReplaySource

​ExactDecimal

​ExploreEntry

​ExploreFacetValue

​ExploreFacets

​ExploreGroup

​ExploreMarket

​ExploreStandalone

​ExportCompleteness

​ExportCounts

​ExportSourceRange

​ExportVolumeReconciliation

​FreshnessFailure

​Game

​GameCompetitor

​GameCoverage

​GameFreshness

​GameMarket

​GameMarketPriceBindingProvenance

​GameMarketPriceCompetitor

​GameMarketPriceIncomplete

​GameMarketPriceInvalid

​GameMarketPricePaired

​GameMarketPrices

​GameMarketProviderPrices

​GameStatus

​GamesCoverage

​HolderCategoryEvidence

​LargeExportPolicy

​LargePosition

​LargeTrade

​LargeTradeDetail

​LargeTradeHistoryMeta

​LargeTradeSubscriptionFilters

​LeaderboardEntry

​MarketCandles

​MarketFlow

​MarketHolder

​MarketHoldersMarket

​MarketHoldersScan

​MarketHoldersSideGrades

​MarketHoldersTotals

​MarketSearchResult

​MarketSnapshot

​MarketSnapshotFreshness

​MarketSnapshotTopOfBook

​MarketSnapshotTrust

​McpJsonRpcError

​OutcomeCandles

​PickHolder

​PickOfTheDay

​PickOfTheDayArchive

​PickOfTheDayArchiveDay

​PickOfTheDayArchiveEntry

​PickOfTheDayCommitmentPayload

​PickOfTheDayHitRate