Skip to main content
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.

ApiDiscovery

FieldTypeRequiredDescription
api_base_urlstringYesCanonical API origin for public V1 requests.
docs_urlstringYesFull agent-readable API reference.
openapi_urlstringYesCanonical web-origin OpenAPI JSON document.
health_urlstringYesUnauthenticated API health endpoint.
authenticationstringYes
authenticated_routesarray of stringYesRepresentative authenticated data routes. Full route coverage lives in OpenAPI and llms-full.txt.

ApiError

FieldTypeRequiredDescription
objectstringYes
errorobjectYes
metaResponseMetaYes

ApiErrorBody

FieldTypeRequiredDescription
codestringYes
messagestringYes
doc_urlstringNo
paramstringNo

BatchMarketIntelItem

FieldTypeRequiredDescription
indexintegerYesZero-based request index. Duplicate inputs keep separate result rows.
inputstringYes
statusok | errorYes
dataMarketIntelNo
errorApiErrorBodyNo

BatchRateLimitMeta

FieldTypeRequiredDescription
basisstringYes
limitintegerYes
remainingintegerYes
resetintegerYesUnix timestamp when the batch item window resets.

BatchResponseMeta

FieldTypeRequiredDescription
request_idstringYes
cachedbooleanYes
total_itemsintegerYes
successful_itemsintegerYes
failed_itemsintegerYes
request_costintegerYesNumber of batch item units reserved before execution.
rate_limitBatchRateLimitMetaYes

BatchTraderItem

FieldTypeRequiredDescription
indexintegerYesZero-based request index. Duplicate inputs keep separate result rows.
inputstringYes
statusok | errorYes
dataTraderNo
errorApiErrorBodyNo

CreateWebhookRequest

FieldTypeRequiredDescription
namestringYes
urlstringYesPublic HTTPS callback URL. Local/private/internal targets are rejected.
event_typesarray of WebhookEventTypeYes

EventReplayEvent

FieldTypeRequiredDescription
idstringYesOpaque event ID; currently identical to cursor for the whale_alerts.id sequence.
typewhale_trades_insertedYes
cursorstringYesCursor positioned at this event.
sequenceintegerYesGlobal whale_alerts.id sequence.
published_atstringYes
payloadobjectYes
sourceEventReplaySourceYes
freshnessEventReplayFreshnessYes

EventReplayFreshness

FieldTypeRequiredDescription
statusstringYes
observed_atstringYes

EventReplayMeta

FieldTypeRequiredDescription
request_idstringYesUnique request ID (req_ prefix).
cachedbooleanYes
cache_age_sintegerNo
replayobjectYes
retentionobjectYes
completenessobjectYes

EventReplaySource

FieldTypeRequiredDescription
kindstringYes
producer_familywhale_tradesYes
ownerstringYes
provider_fetch_at_request_timebooleanYes

ExploreEntry

One of: ExploreGroup, ExploreStandalone. Discriminated by type.

ExploreFacetValue

FieldTypeRequiredDescription
valuestringYes
labelstringYes
countintegerYes

ExploreFacets

FieldTypeRequiredDescription
categoriesarray of ExploreFacetValueYes
platformsarray of ExploreFacetValueYes

ExploreGroup

FieldTypeRequiredDescription
typestringYes
event_slugstringYes
parent_titlestringYes
imagestringNo
platformstringNo
categorystringNo
marketsarray of ExploreMarketYes
rep_volumenumberNo
rep_whalesintegerNo

ExploreMarket

FieldTypeRequiredDescription
idstringYes
condition_idstringYes
titlestringYesNon-empty market title.
slugstringNoProvider-native market slug.
url_slugstringNoFirst-party market page slug used for internal links.
imagestringNo
iconstringNo
categorystringNo
platformstringNo
statusactive | closedYes
volumenumberNo
liquiditynumberNo
whale_trade_countintegerNo
whale_distinct_walletsintegerNo
whale_total_usdnumberNo
whale_last_trade_atstringNo
end_datestringNo
created_atstringNo
outcome_yesstringNo
outcome_nostringNo
event_slugstringNo
kalshi_series_slugstringNo
smart_scorenumberNo
smart_countintegerNo
smart_labelstringNo
outcome_yes_labelstringNoDisplay label for the YES/outcome_index=0 side, enriched from provider outcome metadata when available.
outcome_no_labelstringNoDisplay label for the NO/outcome_index=1 side, enriched from provider outcome metadata when available.
outcome_yes_provider_idintegerNoProvider-owned YES/outcome_index=0 identifier when available for trade-ticket wiring.
outcome_no_provider_idintegerNoProvider-owned NO/outcome_index=1 identifier when available for trade-ticket wiring.
open_interestnumberNo
oi_change_pctnumberNo
price_pointsarray of array of numberNo
no_price_pointsarray of array of numberNo
last_pricenumberNo
no_last_pricenumberNo
change_pct_24hnumberNo
no_change_pct_24hnumberNo
discover_scorenumberNoBackend-owned deterministic market discovery score used by the hot sort.
score_componentsobjectNo
freshnessobjectNo

ExploreStandalone

FieldTypeRequiredDescription
typestringYes
marketExploreMarketYes

ExportCompleteness

FieldTypeRequiredDescription
statuscomplete | partial | emptyYes
reasonstringYes
sync_coveragenumberYes

ExportCounts

FieldTypeRequiredDescription
pnl_daysintegerYes
exported_marketsintegerYes
estimated_trade_rowsintegerYes
estimated_size_mbnumberYes

ExportSourceRange

FieldTypeRequiredDescription
first_pnl_datestringNo
last_pnl_datestringNo
latest_trade_atstringNo
latest_market_activity_atstringNo

ExportVolumeReconciliation

FieldTypeRequiredDescription
provider_lifetime_volumenumberNo
exported_activity_volumenumberYes
exported_market_cost_basisnumberYes
provider_activity_volume_gapnumberNo
activity_volume_coveragenumberNo

LargeExportPolicy

FieldTypeRequiredDescription
modestringYes
current_internal_routestringYes
direct_streamingobjectYes
async_jobobjectYes
rate_limitobjectYes

LargePosition

FieldTypeRequiredDescription
idstringYesComposite prefixed ID pos_<wallet>:<condition_id>:<outcome_index>.
platformpolymarket | kalshiYesProvider discriminator. Always polymarket today (scanner is Polymarket-only); kept in the shape so Kalshi can land without a breaking change.
total_size_usdnumberNoAggregate provider currentValue for this position leg in USD.
position_unrealized_pnlnumberNoProvider per-position unrealized P&L (trader_markets.unrealized_pnl_num, from Polymarket cashPnl).
share_countnumberYesLive share count for this position.
avg_entry_pricenumberNoVolume-weighted entry price.
current_pricenumberNoLatest provider mark price for the position’s token.
outcome_labelstringNoBackend-resolved outcome label (provider outcome, else Yes/No from the binary index).
event_leg_countintegerYesLegs collapsed into this representative row for one (wallet, event, outcome side) group. 1 means standalone.
event_total_value_usdnumberNoAggregate provider currentValue across collapsed sibling legs; equals total_size_usd when event_leg_count = 1.
first_seen_atstringYes
last_updated_atstringYes
traderobjectYes
marketobjectYes

LeaderboardEntry

FieldTypeRequiredDescription
idstringYes
addressstringYes
usernamestringNo
gradestringNo
streak_tierhot | rising | neutral | cooling | coldNoHot-streak tier (trailing-7d cross-sectional percentile); a separate axis from the all-time grade. Null when no recent activity.
scorenumberNo
pnlnumberNo
volumenumberNo
markets_tradedintegerNo
win_ratenumberNo
strategy_typestringNo
platformstringYes
last_activestringNo

MarketIntel

FieldTypeRequiredDescription
marketobjectYes
smart_moneyobjectYes
timeframestringYes

MarketSearchResult

FieldTypeRequiredDescription
idstringYes
condition_idstringYes
titlestringYes
slugstringNo
categorystringNo
platformstringNo
statusactive | closedYes

MarketSnapshot

FieldTypeRequiredDescription
marketobjectYes
outcomesarray of objectYes
liquidityobjectYes
sportsobjectYes
freshnessobjectYes
trustMarketSnapshotTrustNoPrice and spread trust metadata. Present only when expand=trust or expand[]=trust is requested.

MarketSnapshotFreshness

FieldTypeRequiredDescription
statusfresh | stale | available | not_live | unavailableYes
sourcestringYes
as_ofstringNo
stale_after_sintegerNo
reasonstringNo

MarketSnapshotTopOfBook

FieldTypeRequiredDescription
statusavailable | unavailableYes
sourcestringYes
best_bidnumberNo
best_asknumberNo
spread_bpsintegerNo
bid_depth_usdcnumberNo
ask_depth_usdcnumberNo
reasonstringNo

MarketSnapshotTrust

Price and spread trust metadata returned only when GET /api/v1/market//snapshot includes expand=trust.
FieldTypeRequiredDescription
current_priceTrustMetadataYes
spread_bpsTrustMetadataYes

PlatformCapabilities

FieldTypeRequiredDescription
gradePlatformCapabilityStatusYes
pnlPlatformCapabilityStatusYes
strategyPlatformCapabilityStatusYes
timelinePlatformCapabilityStatusYes
whale_signalPlatformCapabilityStatusYes
insider_radarPlatformCapabilityStatusYes
market_snapshotPlatformCapabilityStatusYes

PlatformCapabilityStatus

String enum: supported, partial, unsupported.

Platforms

FieldTypeRequiredDescription
platformsobjectYes

Position

FieldTypeRequiredDescription
idstringYesComposite prefixed ID pos_<wallet>:<condition_id>:<outcome_index>.
platformpolymarket | kalshiYesProvider discriminator. Slice 5 ships Polymarket only; the field stays in the response shape so Kalshi positions can land without a breaking change.
walletstringYesLowercased proxy wallet address.
sideYES | NOYesBinary outcome side. Non-binary positions are not surfaced on V1.
sharesnumberYesLive share count from the wallet_positions mirror.
avg_pricenumberNoVolume-weighted entry price for this leg.
current_value_usdnumberYesCurrent mark-to-market value in USD (always non-null on V1 — pre-reconcile rows are excluded).
initial_value_usdnumberNo
cash_pnlnumberNoUnrealized P&L for the open position (Polymarket cashPnl).
realized_pnlnumberNoClosed-leg P&L rolled up (Polymarket realizedPnl).
last_reconciled_atstringNoMax updated_at across mirror legs for this pair.
freshnessfresh | refreshing | stale | unknownYesBackend-computed staleness bucket derived from last_reconciled_at.
traderobjectYes
marketobjectYes

PositionTimelineEvent

FieldTypeRequiredDescription
idstringYesPrefixed ID (pe_…).
event_timestampstringYesISO 8601 timestamp of the on-chain fill.
actionbuy | sellYesFrom the taker’s perspective.
outcome_sideyes | noYes
amount_deltanumberYesSigned share delta (+ on buy, − on sell).
pricenumberYesFill price in USDC per share, in [0,1].
usdc_notionalnumberYesPositive USDC notional of the fill.
tx_hashstringYesPolygon transaction hash of the fill.
running_amountnumberYesCumulative signed share balance after this fill.
running_avg_pricenumberYesBuy-weighted entry basis (matches Polymarket /positions avgPrice semantics). Sells do not change this value. 0 when no buys have occurred yet.

RadarFlag

FieldTypeRequiredDescription
idstringYesPrefixed ID (rf_…).
suspicion_scorenumberYes
severityflag | watchYes
traderobjectYes
marketobjectYes
scoresobjectYes
evidenceobjectYesStructured evidence JSON.
created_atstringYes

ReportPayload

FieldTypeRequiredDescription
total_whale_tradesintegerNo
total_whale_volumenumberNo
biggest_trade_sizenumberNo
active_tradersintegerNo
top_whale_tradesarray of objectNo
categoriesarray of objectNo
grade_distributionarray of objectNo

ReportReconciliation

FieldTypeRequiredDescription
volume_kindstringYes
whale_volume_sourcestringYes
notesstringYes

ReportSnapshot

FieldTypeRequiredDescription
kinddaily | weekly | monthlyYes
generated_atstringYes
source_rangeReportSourceRangeYes
snapshotSnapshotStateYes
completenessSnapshotCompletenessYes
reconciliationReportReconciliationYes
reportReportPayloadYes

ReportSourceRange

FieldTypeRequiredDescription
start_datestringYes
end_datestringYes
timezonestringYes

ResponseMeta

FieldTypeRequiredDescription
request_idstringYesUnique request ID (req_ prefix).
cachedbooleanYes
cache_age_sintegerNoCache age in seconds, null if not cached.

SmartMoneyFlowMarket

FieldTypeRequiredDescription
marketobjectYes
smart_moneyobjectYes
timeframestringYes

SnapshotCompleteness

FieldTypeRequiredDescription
statuscomplete | partial | emptyYes
reasonstringYes
expected_daysintegerYes
covered_days_with_whale_activityintegerYes

SnapshotState

FieldTypeRequiredDescription
statusfinal | rollingYes
generated_atstringYes
mutable_untilstringNo

Trader

FieldTypeRequiredDescription
idstringYesPrefixed ID (trd_…).
addressstringYes
usernamestringNo
gradeS | A | B | C | D | FNo
streak_tierhot | rising | neutral | cooling | coldNoHot-streak tier (trailing-7d cross-sectional percentile); a separate axis from the all-time grade. Null when no recent activity.
scorenumberNo
rankintegerNo
pnlobjectYes
statsobjectYes
strategyobjectNo
category_strengthsobjectNoPer-category performance breakdown (expand=categories or expand[]=categories). Null 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). 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_metricsobjectNoAdvanced risk/performance metrics (expand=quant_metrics or expand[]=quant_metrics). Null unless expanded. Pass-through of the advanced_metrics row as JSON (trader_id and id stripped); the metric key-set is DB-owned and additive, so the inner shape is intentionally unconstrained.
last_activestringNo
synced_atstringNo
sync_statusstringNosynced, unknown, or pending.
trustTraderTrustNoField-level trust metadata. Present only when expand=trust or expand[]=trust is requested.

TraderExportSnapshot

FieldTypeRequiredDescription
addressstringYes
generated_atstringYes
source_rangeExportSourceRangeYes
completenessExportCompletenessYes
reconciliationExportVolumeReconciliationYes
countsExportCountsYes
large_export_policyLargeExportPolicyYes

TraderPnl

FieldTypeRequiredDescription
idstringYesPrefixed trader ID (trd_...).
entriesarray of objectYesDaily cumulative-P&L series (oldest-first).
statsobjectYes
monthlyarray of objectYesPer-month P&L aggregation.
year_totalsarray of objectYesPer-year P&L totals (ascending by year).
drawdownarray of objectYesUnderwater (drawdown) series.

TraderTrust

Field-level trust metadata returned only when GET /api/v1/trader/ includes expand=trust.
FieldTypeRequiredDescription
total_pnlTrustMetadataYes
realized_pnlTrustMetadataYes
unrealized_pnlTrustMetadataYes
markets_tradedTrustMetadataYes
win_rateTrustMetadataYes
daily_win_rateTrustMetadataYes
total_volumeTrustMetadataYes
gradeTrustMetadataYes
scoreTrustMetadataYes
rankTrustMetadataYes
streak_tierTrustMetadataYes
strategyTrustMetadataYes
category_strengthsTrustMetadataYes
quant_metricsTrustMetadataYes
last_activeTrustMetadataYes
synced_atTrustMetadataYes
sync_statusTrustMetadataYes

TrendingWallet

FieldTypeRequiredDescription
idstringYesPrefixed trader ID (trd_...).
addressstringYes
rankintegerYes1-based rank within the full ranked set (stable across pages).
usernamestringNo
profile_image_urlstringNoOfficial Polymarket avatar URL (profileImage).
platformpolymarket | kalshiYesReal provider platform; surfaced, never coerced. Polymarket-only today.
trending_pnl_usdnumberYesRealized P&L over the trailing window in USD (ranking axis).
window_volume_usdnumberYes
window_markets_tradedintegerYes
window_trade_daysintegerYes
gradeS | A | B | C | D | FNoAll-time cohort-relative skill grade (forecasting calibration, risk-adjusted returns, consistency); a separate axis from streak_tier. Not a profit ranking, and relative, so it drifts as the cohort moves. Omitted when the trader is Unranked (fewer than 5 markets, insufficient track record to cohort-rank).
streak_tierhot | rising | neutral | cooling | coldNoHot-streak tier (trailing-7d cross-sectional percentile). Null when no recent activity.
all_time_pnl_usdnumberNo
all_time_scorenumberNo
last_syncedstringNo
daily_pnl_seriesarray of objectYesZero-filled daily P&L series across the window.

TrustCompleteness

Whether the described value or result set is complete for its stated contract.
FieldTypeRequiredDescription
statuscomplete | partial | not_computed | not_applicable | unavailableYes
detailstringNo

TrustFreshness

Freshness metadata for a trust-critical value. This is separate from transport cache fields in ResponseMeta.
FieldTypeRequiredDescription
statusfresh | refreshing | stale | not_live | unknown | unavailableYes
as_ofstringNo
max_age_sintegerNo

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.
FieldTypeRequiredDescription
sourceTrustSourceYes
freshnessTrustFreshnessYes
reconciliationTrustReconciliationYes
completenessTrustCompletenessYes

TrustReconciliation

How provider-owned facts were reconciled with stored/read-model values.
FieldTypeRequiredDescription
statusprovider_backed | db_mirror | computed | partial | not_applicable | unavailableYes
detailstringNo

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.
FieldTypeRequiredDescription
kindprovider | database | cache | computed | client_input | unavailableYes
ownerstringYesProvider, table/read-model, cache, or service that owns the value.
fieldstringNoProvider field, DB column, or computed field name when applicable.

UpdateWebhookRequest

FieldTypeRequiredDescription
namestringNo
urlstringNo
event_typesarray of WebhookEventTypeNo
enabledbooleanNo

Usage

FieldTypeRequiredDescription
objectstringYes
dataobjectYes
metaResponseMetaYes

VerifyWebhookRequest

FieldTypeRequiredDescription
verification_tokenstringYes

WebhookEndpoint

FieldTypeRequiredDescription
idintegerYes
objectstringYes
namestringYes
urlstringYes
event_typesarray of WebhookEventTypeYes
statusWebhookStatusYes
verified_atstringNo
verification_token_expires_atstringYes
failure_countintegerYes
created_atstringYes
updated_atstringYes
retry_policyWebhookRetryPolicyYes
signing_secretstringNoReturned only on create or rotate-secret.
verificationWebhookVerificationNo

WebhookEventType

String enum: whale_trades_inserted, live_sports_updated, whale_trader_synced, large_positions_updated.

WebhookRetryPolicy

FieldTypeRequiredDescription
max_attemptsintegerYes
terminal_statusstringYes

WebhookStatus

String enum: pending_verification, active, disabled.

WebhookVerification

FieldTypeRequiredDescription
tokenstringYesOne-time verification token returned only on create or URL change.
expires_atstringYes

WhaleTrade

FieldTypeRequiredDescription
idstringYesPrefixed ID (wt_…).
traded_atstringYes
size_usdnumberYes
sideBUY | SELLYes
pricenumberYes
signal_scorenumberYes0.0–1.0 normalized signal score.
traderobjectYes
marketobjectYes

WhaleTradeHistoryMeta

FieldTypeRequiredDescription
request_idstringYesUnique request ID (req_ prefix).
cachedbooleanYes
cache_age_sintegerNoCache age in seconds, null if not cached.
sourceobjectYes
completenessobjectYes