@0xinsider/mcp 2.6.0 → 2.9.0

package/dist/sdk/schema.d.ts

@@ -59,7 +59,7 @@ export type ApiDiscovery = {
     openapi_url: string;
     /** Unauthenticated API health endpoint. */
     health_url: string;
-    authentication: "Bearer API key required for data endpoints; discovery (/api/v1), health, /api/v1/platforms, the Pick of the Day commitment ledger (/api/v1/pick-of-the-day/ledger), and the MCP handshake (initialize, ping, tools/list on /api/v1/mcp) are public. A 401 carries WWW-Authenticate with the resource_metadata URL.";
+    authentication: "Bearer API key required for data endpoints; discovery (/api/v1), health, coverage (/api/v1/coverage, and its deprecated alias /api/v1/platforms), the Pick of the Day commitment ledger (/api/v1/pick-of-the-day/ledger), and the MCP handshake (initialize, ping, tools/list on /api/v1/mcp) are public. A 401 carries WWW-Authenticate with the resource_metadata URL.";
     /** 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. */
     protected_resource_metadata_url: string;
     /** 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. */
@@ -75,8 +75,9 @@ export type ApiError = {
         param?: string;
         /** The recommended next request instant (RFC3339), always in the future. Present on every retryable error: `pick_not_released`, `rate_limited`, `rate_limit_unavailable`, and `read_model_warming`. Omitted otherwise. The absolute twin of `Retry-After`; prefer the header for the sleep duration. For `pick_not_released`, the earliest of the next scheduled release, the next automatic selector attempt, the operating-window start, or about 60 seconds. See that response. */
         retry_at?: string;
+        freshness?: FreshnessFailure;
         /** 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. */
-        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";
+        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";
     };
     meta: ResponseMeta;
 };
@@ -88,15 +89,16 @@ export type ApiErrorBody = {
     param?: string;
     /** 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 under supported operator actions: manual publication, release-time override, or admin generation can make a pick available first. 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. */
     retry_at?: string;
+    freshness?: FreshnessFailure;
     /** 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. */
-    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";
+    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";
 };
-export type BatchMarketIntelItem = {
+export type BatchMarketFlowItem = {
     /** Zero-based request index. Duplicate inputs keep separate result rows. */
     index: number;
     input: string;
     status: "ok" | "error";
-    data?: MarketIntel;
+    data?: MarketFlow;
     error?: ApiErrorBody;
 };
 export type BatchRateLimitMeta = {
@@ -250,6 +252,7 @@ export type CreateWebhookRequest = {
     /** 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. */
     url: string;
     event_types: WebhookEventType[];
+    trade_filters?: LargeTradeSubscriptionFilters;
 };
 /** 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. */
 export type DataQuality = {
@@ -497,7 +500,17 @@ export type ExportVolumeReconciliation = {
     provider_activity_volume_gap: number | null;
     activity_volume_coverage: number | null;
 };
-/** One sports or esports game: both sides, its schedule, its provider status and the Polymarket markets linked to it. Assembled from the same provider-first live and upcoming projections the site's boards use, with no request-time provider fan-out. */
+export type FreshnessFailure = {
+    /** The caller's requested whole-response freshness ceiling in seconds. */
+    max_age_s: number;
+    /** Age in seconds of the oldest stored data_quality.as_of clock, when one is available. */
+    actual_age_s?: number;
+    /** The oldest stored data-quality clock used to calculate actual_age_s, when one is available. */
+    as_of?: string;
+    /** The trader body's whole-response data-quality status. Only fresh can satisfy max_age_s. */
+    data_quality_status: "fresh" | "partial" | "unknown" | "untracked" | "unavailable";
+};
+/** 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. */
 export type Game = {
     object: "game";
     /** 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. */
@@ -589,7 +602,64 @@ export type GameMarket = {
     outcome_no?: string;
     /** Polymarket CLOB token ids in the provider's own outcome-index order. Omitted when the provider has published none for this market. */
     outcome_token_ids?: string[];
+    /** Default provider moneyline state. Omitted when this market has no classified moneyline projection; incomplete and invalid projections remain explicit. */
+    prices?: GameMarketPrices;
+};
+/** How the existing sports-board writer bound prices to competitors. */
+export type GameMarketPriceBindingProvenance = "provider_ids" | "exact_labels" | "containment_labels" | "elimination";
+/** One competitor-bound provider moneyline price. No YES/NO inference is required. */
+export type GameMarketPriceCompetitor = {
+    /** The provider competitor id when identity is available. */
+    provider_id?: number;
+    /** The provider competitor label. */
+    label: string;
+    /** Unrounded provider price in [0, 1]. */
+    price: number;
+    /** Which provider price observation supplies this leg. */
+    price_provenance: "gamma_outcome_prices" | "clob_display";
+};
+/** The provider moneyline pair is incomplete; no numeric pair is invented. */
+export type GameMarketPriceIncomplete = {
+    state: "incomplete";
+    reason: "outcome_prices_missing" | "outcome_price_leg_missing" | "zero_price_sentinel" | "display_price_pair_unavailable" | "outcome_identity_unavailable" | "final_score_unavailable";
+    /** Whether competitor A is the provider YES leg. */
+    competitor_a_is_yes?: boolean;
+    /** The provider competitor id when identity is available. */
+    competitor_a_provider_id?: number;
+    /** The provider competitor id when identity is available. */
+    competitor_b_provider_id?: number;
+    binding_provenance?: GameMarketPriceBindingProvenance;
+};
+/** The provider moneyline pair is invalid; no numeric pair is invented. */
+export type GameMarketPriceInvalid = {
+    state: "invalid";
+    reason: "team_cardinality" | "outcome_cardinality" | "price_cardinality" | "non_finite_price" | "out_of_range_price" | "non_complementary_prices" | "ambiguous_identity" | "final_identity_mismatch";
+    /** Whether competitor A is the provider YES leg. */
+    competitor_a_is_yes?: boolean;
+    /** The provider competitor id when identity is available. */
+    competitor_a_provider_id?: number;
+    /** The provider competitor id when identity is available. */
+    competitor_b_provider_id?: number;
+    binding_provenance?: GameMarketPriceBindingProvenance;
+};
+/** A validated provider moneyline pair bound to the two competitors. */
+export type GameMarketPricePaired = {
+    state: "paired";
+    competitor_a: GameMarketPriceCompetitor;
+    competitor_b: GameMarketPriceCompetitor;
+    /** Whether competitor A is the provider YES leg. */
+    competitor_a_is_yes: boolean;
+    binding_provenance: GameMarketPriceBindingProvenance;
+};
+/** Provider-owned moneyline state with the observation clock that can be compared with game freshness. */
+export type GameMarketPrices = {
+    provider: GameMarketProviderPrices;
+    /** Board cache vintage for Gamma or the older CLOB leg clock. Null when no reliable clock is available; never a Gamma-authored timestamp. */
+    observed_at: string | null;
+    /** The clock used for observed_at. board_snapshot is this service’s cache observation, not a provider source timestamp. */
+    observation_source: "board_snapshot" | "clob_display";
 };
+export type GameMarketProviderPrices = GameMarketPricePaired | GameMarketPriceIncomplete | GameMarketPriceInvalid;
 /** 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. */
 export type GamesCoverage = {
     /** Canonical sport buckets served, sorted. */
@@ -788,6 +858,17 @@ export type LargeTradeHistoryMeta = {
         reason: string;
     };
 };
+/** 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. */
+export type LargeTradeSubscriptionFilters = {
+    /** Raw provider condition ID or mkt_-prefixed market ID. */
+    condition_id?: string;
+    /** Polymarket wallet address; matching is case-insensitive. */
+    wallet?: string;
+    /** S is best; ungraded trades do not match. */
+    min_grade?: "S" | "A" | "B" | "C" | "D" | "F";
+    /** Positive USD notional as an exact decimal string. */
+    min_size_usd?: string;
+};
 export type LeaderboardEntry = {
     id: string;
     address: string;
@@ -818,6 +899,68 @@ export type MarketCandles = {
     /** One entry per present provider token (YES first, then NO); empty when no tokens have been fetched yet. */
     outcomes: OutcomeCandles[];
 };
+export type MarketFlow = {
+    market: {
+        id: string;
+        condition_id: string;
+        title: string;
+        slug: string | null;
+        category: string | null;
+        platform: string | null;
+    };
+    /** 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. */
+    sharp_money: {
+        net_flow_usd: number;
+        direction: "YES" | "NO";
+        /** The Polymarket CLOB token id (ERC1155 asset id, decimal string) for the net-flow direction outcome; null when unavailable (e.g. unsynced markets). */
+        token_id: string | null;
+        /** Canonical key since #16304 (Polymarket's noun is large trade); whale_trade_count is its deprecated spelling, emitted beside it with the same value. */
+        large_trade_count?: number;
+        whale_trade_count: number;
+        buy_volume_usd: number;
+        sell_volume_usd: number;
+        top_positions: ({
+            id: string;
+            address: string;
+            username: string | null;
+            grade: string | null;
+            side: "YES" | "NO";
+            /** The Polymarket CLOB token id (ERC1155 asset id, decimal string) for this outcome; null when unavailable (e.g. unsynced markets). */
+            token_id: string | null;
+            size_usd: number;
+        })[];
+        /** Age of the oldest stored position snapshot behind top_positions: the minimum wallet sync clock over the positions this body publishes. The roster is a stored read rather than a live one, and graded wallets sit on different sync tiers, so this names how current the whole roster is; the response is no fresher than this timestamp. Null when the roster is empty or no published position carries a sync clock. It does not date net_flow_usd, the volumes or the trade counts, which come from large-trade event times. */
+        oldest_snapshot_as_of: string | null;
+    };
+    /**
+     * Deprecated alias of sharp_money; byte-identical and retained for backward compatibility.
+     * @deprecated
+     */
+    smart_money: {
+        net_flow_usd: number;
+        direction: "YES" | "NO";
+        /** The Polymarket CLOB token id (ERC1155 asset id, decimal string) for the net-flow direction outcome; null when unavailable (e.g. unsynced markets). */
+        token_id: string | null;
+        /** Canonical key since #16304 (Polymarket's noun is large trade); whale_trade_count is its deprecated spelling, emitted beside it with the same value. */
+        large_trade_count?: number;
+        whale_trade_count: number;
+        buy_volume_usd: number;
+        sell_volume_usd: number;
+        top_positions: ({
+            id: string;
+            address: string;
+            username: string | null;
+            grade: string | null;
+            side: "YES" | "NO";
+            /** The Polymarket CLOB token id (ERC1155 asset id, decimal string) for this outcome; null when unavailable (e.g. unsynced markets). */
+            token_id: string | null;
+            size_usd: number;
+        })[];
+        /** Age of the oldest stored position snapshot behind top_positions: the minimum wallet sync clock over the positions this body publishes. The roster is a stored read rather than a live one, and graded wallets sit on different sync tiers, so this names how current the whole roster is; the response is no fresher than this timestamp. Null when the roster is empty or no published position carries a sync clock. It does not date net_flow_usd, the volumes or the trade counts, which come from large-trade event times. */
+        oldest_snapshot_as_of: string | null;
+    };
+    timeframe: string;
+};
 export type MarketHolder = {
     /** Composite `pos_<wallet>:<condition_id>:<outcome_index>`, the same id `GET /api/v1/positions` gives this leg. */
     id: string;
@@ -913,68 +1056,6 @@ export type MarketHoldersTotals = {
     yes_grades: MarketHoldersSideGrades;
     no_grades: MarketHoldersSideGrades;
 };
-export type MarketIntel = {
-    market: {
-        id: string;
-        condition_id: string;
-        title: string;
-        slug: string | null;
-        category: string | null;
-        platform: string | null;
-    };
-    /** 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. */
-    sharp_money: {
-        net_flow_usd: number;
-        direction: "YES" | "NO";
-        /** The Polymarket CLOB token id (ERC1155 asset id, decimal string) for the net-flow direction outcome; null when unavailable (e.g. unsynced markets). */
-        token_id: string | null;
-        /** Canonical key since #16304 (Polymarket's noun is large trade); whale_trade_count is its deprecated spelling, emitted beside it with the same value. */
-        large_trade_count?: number;
-        whale_trade_count: number;
-        buy_volume_usd: number;
-        sell_volume_usd: number;
-        top_positions: ({
-            id: string;
-            address: string;
-            username: string | null;
-            grade: string | null;
-            side: "YES" | "NO";
-            /** The Polymarket CLOB token id (ERC1155 asset id, decimal string) for this outcome; null when unavailable (e.g. unsynced markets). */
-            token_id: string | null;
-            size_usd: number;
-        })[];
-        /** Age of the oldest stored position snapshot behind top_positions: the minimum wallet sync clock over the positions this body publishes. The roster is a stored read rather than a live one, and graded wallets sit on different sync tiers, so this names how current the whole roster is; the response is no fresher than this timestamp. Null when the roster is empty or no published position carries a sync clock. It does not date net_flow_usd, the volumes or the trade counts, which come from large-trade event times. */
-        oldest_snapshot_as_of: string | null;
-    };
-    /**
-     * Deprecated alias of sharp_money; byte-identical and retained for backward compatibility.
-     * @deprecated
-     */
-    smart_money: {
-        net_flow_usd: number;
-        direction: "YES" | "NO";
-        /** The Polymarket CLOB token id (ERC1155 asset id, decimal string) for the net-flow direction outcome; null when unavailable (e.g. unsynced markets). */
-        token_id: string | null;
-        /** Canonical key since #16304 (Polymarket's noun is large trade); whale_trade_count is its deprecated spelling, emitted beside it with the same value. */
-        large_trade_count?: number;
-        whale_trade_count: number;
-        buy_volume_usd: number;
-        sell_volume_usd: number;
-        top_positions: ({
-            id: string;
-            address: string;
-            username: string | null;
-            grade: string | null;
-            side: "YES" | "NO";
-            /** The Polymarket CLOB token id (ERC1155 asset id, decimal string) for this outcome; null when unavailable (e.g. unsynced markets). */
-            token_id: string | null;
-            size_usd: number;
-        })[];
-        /** Age of the oldest stored position snapshot behind top_positions: the minimum wallet sync clock over the positions this body publishes. The roster is a stored read rather than a live one, and graded wallets sit on different sync tiers, so this names how current the whole roster is; the response is no fresher than this timestamp. Null when the roster is empty or no published position carries a sync clock. It does not date net_flow_usd, the volumes or the trade counts, which come from large-trade event times. */
-        oldest_snapshot_as_of: string | null;
-    };
-    timeframe: string;
-};
 export type MarketSearchResult = {
     id: string;
     condition_id: string;
@@ -2273,7 +2354,7 @@ export type Trader = {
     synced_at?: string;
     /** synced, unknown, or pending. */
     sync_status?: string;
-    /** 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 (traders.leaderboard_rank, which stores no write timestamp, so its status is unknown rather than dated by another clock), volume (trader_usd_volume.observed_at, covering stats.total_volume) and positions (trader_markets, covering pnl.unrealized, whose own write times this read does not carry). For an unknown wallet every group is unavailable. */
+    /** 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. */
     data_quality: DataQuality;
     /** Field-level trust metadata. Present only when expand=trust or expand[]=trust is requested. */
     trust?: TraderTrust;
@@ -2479,6 +2560,37 @@ export type TraderExportTradeWatermark = {
     rows: number;
     first_activity_date: string | null;
 };
+export type TraderGradeAt = {
+    /** Prefixed trader id (trd_<wallet>). */
+    id: string;
+    /** Resolved wallet address, lowercased. */
+    address: string;
+    /** Requested event or decision time. */
+    as_of: string;
+    /** graded has a proven grade; ungraded is a proven null grade; unknown has no valid historical observation. */
+    status: "graded" | "ungraded" | "unknown";
+    /** Grade only when status is graded; null otherwise. */
+    grade: "S" | "A" | "B" | "C" | "D" | "F" | null;
+    /** First proven visibility instant for this trader. Null when no observation exists. Earlier times remain unknown. */
+    available_from: string | null;
+    /** Proof row when status is graded or ungraded. Null when history is unknown. */
+    observation: {
+        /** Immutable grade_forward_history observation id. */
+        id: number;
+        /** Previous immutable observation id when retained. A later grade change supersedes that observation but never erases it; this link does not assert why the grade changed. */
+        previous_observation_id: number | null;
+        /** Lower bound: the grade writer had started the transition at this instant. */
+        observed_at: string;
+        /** Upper bound: a later snapshot confirmed the observation was committed. This is not an exact commit timestamp. */
+        published_by: string;
+        /** Writer-proven model family, such as grading-v4. Null when unknown. */
+        model_version: string | null;
+        /** Exact writer build SHA when recorded. Null on old and non-model observations. */
+        model_build_sha: string | null;
+        /** Database-clock upper bound on when the grading pass read its cohort inputs. Not the event time or source freshness of every input; null when unknown. */
+        source_observed_by: string | null;
+    } | null;
+};
 /** 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. */
 export type TraderPnl = {
     /** Prefixed trader ID (`trd_...`). */
@@ -2694,6 +2806,7 @@ export type UpdateWebhookRequest = {
     /** 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. */
     url?: string;
     event_types?: WebhookEventType[];
+    trade_filters?: LargeTradeSubscriptionFilters;
     enabled?: boolean;
 };
 export type Usage = {
@@ -2768,6 +2881,7 @@ export type WebhookEndpoint = {
     name: string;
     url: string;
     event_types: WebhookEventType[];
+    trade_filters: LargeTradeSubscriptionFilters;
     status: WebhookStatus;
     verified_at: string | null;
     verification_token_expires_at: string;
@@ -2790,7 +2904,7 @@ export type WebhookEventDescriptor = {
     /** active: the event has a firing producer callsite. dormant: advertised and subscribable, but does not yet enqueue any delivery. */
     status: "active" | "dormant";
 };
-export type WebhookEventType = "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";
+export type WebhookEventType = "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";
 export type WebhookRetryPolicy = {
     max_attempts: 8;
     terminal_status: "dead_letter";
@@ -2818,7 +2932,8 @@ export type WebhookVerification = {
  */
 export interface OperationData {
     activateWebhookSecret: WebhookEndpoint;
-    batchGetMarketIntel: BatchMarketIntelItem[];
+    batchGetMarketFlow: BatchMarketFlowItem[];
+    batchGetMarketIntel: BatchMarketFlowItem[];
     batchGetTraders: BatchTraderItem[];
     cancelTraderExport: {
         job_id: number;
@@ -2896,6 +3011,7 @@ export interface OperationData {
         scopes: string[] | null;
     };
     getApiDiscovery: ApiDiscovery;
+    getCoverage: Platforms;
     getDailyReportSnapshot: ReportSnapshot;
     getEventReplaySince: EventReplayEvent[];
     getGame: Game;
@@ -2925,8 +3041,9 @@ export interface OperationData {
     getLargeTrade: LargeTradeDetail;
     getMarketCandles: MarketCandles;
     getMarketContextMarkdown: string;
+    getMarketFlow: MarketFlow;
     getMarketHolders: MarketHolder[];
-    getMarketIntel: MarketIntel;
+    getMarketIntel: MarketFlow;
     getMarketSnapshot: MarketSnapshot;
     getMonthlyReportSnapshot: ReportSnapshot;
     getPickOfTheDay: PickOfTheDay;
@@ -2992,6 +3109,7 @@ export interface OperationData {
             manifest: TraderExportArtifactManifest | null;
         };
     };
+    getTraderGradeAt: TraderGradeAt;
     getTraderPnl: TraderPnl;
     getUsage: {
         rate_limit: {
@@ -3117,6 +3235,7 @@ export interface OperationData {
 /** Each operation's documented query parameters. */
 export interface OperationQuery {
     activateWebhookSecret: Record<string, never>;
+    batchGetMarketFlow: Record<string, never>;
     batchGetMarketIntel: Record<string, never>;
     batchGetTraders: Record<string, never>;
     cancelTraderExport: {
@@ -3144,6 +3263,7 @@ export interface OperationQuery {
     };
     getAccountIdentity: Record<string, never>;
     getApiDiscovery: Record<string, never>;
+    getCoverage: Record<string, never>;
     getDailyReportSnapshot: {
         /** UTC report date in YYYY-MM-DD format. */
         date: string;
@@ -3177,6 +3297,10 @@ export interface OperationQuery {
         to?: number;
     };
     getMarketContextMarkdown: Record<string, never>;
+    getMarketFlow: {
+        /** Lookback window for whale flow aggregation. */
+        timeframe?: "1h" | "4h" | "24h" | "7d";
+    };
     getMarketHolders: {
         /** Keep holders netting one side. `all` (default) lists both. */
         outcome?: "yes" | "no" | "all";
@@ -3236,8 +3360,12 @@ export interface OperationQuery {
         event?: string;
         /** Optional per-connection subscribe-time filter. Raw provider condition_id or mkt_-prefixed market id (normalized the same way the other v1 market endpoints normalize). A frame passes only when it carries a matching condition_id field; frames that carry no condition_id (e.g. whale-pulse events) are EXCLUDED while this is set. An empty value after normalization returns HTTP 400. Combines with event and min_grade as a logical AND; an absent param adds no constraint. */
         condition_id?: string;
-        /** Optional per-connection subscribe-time filter. A frame passes only when it carries a grade field whose grade is better-or-equal to this minimum (S is best). Frames that carry no grade field (every frame except wallet_grade_changed) are EXCLUDED while this is set. An invalid grade returns HTTP 400. Combines with event and condition_id as a logical AND; an absent param adds no constraint. */
+        /** Optional per-connection subscribe-time filter. A frame passes only when it carries a grade field whose grade is better-or-equal to this minimum (S is best). Frames without a grade (every frame except wallet_grade_changed and LargeTradeInsertedV2) are excluded. An invalid grade returns HTTP 400. Combines with the other filters as a logical AND. */
         min_grade?: "S" | "A" | "B" | "C" | "D" | "F";
+        /** Filter LargeTradeInsertedV2 frames to this Polymarket wallet. Other event types have no wallet and are excluded when set. Applied to live and retained Redis frames after privacy checks. */
+        wallet?: string;
+        /** Filter LargeTradeInsertedV2 frames to trades at or above this USD notional. Positive decimal with at most six places; other event types are excluded when set. */
+        min_size?: string;
     };
     getSuspiciousTrade: Record<string, never>;
     getTrader: {
@@ -3245,6 +3373,8 @@ export interface OperationQuery {
         "expand[]"?: ("strategy" | "categories" | "quant_metrics" | "trust")[];
         /** Include heavy fields and trust metadata. Repeatable: strategy, categories, quant_metrics, trust. */
         expand?: ("strategy" | "categories" | "quant_metrics" | "trust")[];
+        /** Opt into a whole-response freshness ceiling in seconds. The server returns 200 only when data_quality.status is fresh and data_quality.as_of is no older than this value; otherwise it returns 409 with error.reason=freshness_ceiling_unsatisfied. No refresh or alternate read is attempted. */
+        max_age_s?: number;
     };
     getTraderCategoryRecords: {
         /** Filter to one canonical category, matched through the same rollup every other category surface uses: soccer, EPL and champions league all reach Soccer, every esports label folds into Esports, and football is AMERICAN football and reaches Football. A filter that reaches Esports returns the Esports record with all of its games; a game is not a filter of its own, so ask for esports and read games. A value that matches no record answers 200 with an empty records array, never 404. */
@@ -3257,6 +3387,10 @@ export interface OperationQuery {
         /** Export job id returned by the submit route. */
         job_id: number;
     };
+    getTraderGradeAt: {
+        /** RFC3339 instant whose historically visible grade is requested. Future instants are refused. Send the trade or decision time, not the ranking date. */
+        as_of: string;
+    };
     getTraderPnl: {
         /** Inclusive UTC calendar-date lower bound in YYYY-MM-DD form for the daily series (entries and drawdown). Omit for the whole stored history. A value that is not a calendar date, or a from later than to, returns 400 bad_request with error.param from. Does not change stats, monthly or year_totals, which stay defined over the full history. */
         from?: string;
@@ -3397,6 +3531,8 @@ export interface OperationQuery {
         limit?: number;
         /** Pagination cursor from previous response's next_cursor. */
         cursor?: string;
+        /** live (default) reads the current value-ordered board. snapshot requires wallet and freezes up to 500 matching rows and 2 MB for up to five minutes. Keep consistency=snapshot and the same effective filters on every page; changing filters returns 400. A new first page from the same API key replaces its prior snapshot; replacement or expiry returns cursor_expired. */
+        consistency?: "live" | "snapshot";
         /** Minimum current position value in USD. Defaults to 100 when omitted, or to 0 when wallet is present; send 0 to include every reconciled position. */
         min_size?: number;
         /** Exact match against provider-backed market_canonical.category. */
@@ -3616,6 +3752,7 @@ export interface OperationPath {
         /** Webhook endpoint id owned by the authenticated API key user. */
         id: number;
     };
+    batchGetMarketFlow: Record<string, never>;
     batchGetMarketIntel: Record<string, never>;
     batchGetTraders: Record<string, never>;
     cancelTraderExport: {
@@ -3631,6 +3768,7 @@ export interface OperationPath {
     exploreMarkets: Record<string, never>;
     getAccountIdentity: Record<string, never>;
     getApiDiscovery: Record<string, never>;
+    getCoverage: Record<string, never>;
     getDailyReportSnapshot: Record<string, never>;
     getEventReplaySince: Record<string, never>;
     getGame: {
@@ -3654,6 +3792,10 @@ export interface OperationPath {
         /** Market condition ID. Accepts the raw provider-backed condition_id returned by /api/v1/markets/search or /api/v1/markets/explore, or the mkt_-prefixed market.id emitted by V1 responses. */
         condition_id: string;
     };
+    getMarketFlow: {
+        /** Market condition ID. Accepts the raw provider-backed condition_id returned by /api/v1/markets/search or the mkt_-prefixed market.id emitted by V1 responses. */
+        condition_id: string;
+    };
     getMarketHolders: {
         /** Market condition ID. Accepts the raw provider-backed condition_id returned by /api/v1/markets/search or the mkt_-prefixed market.id emitted by V1 responses. */
         condition_id: string;
@@ -3709,6 +3851,10 @@ export interface OperationPath {
         /** Trader wallet address (0x...), known trader username-style lookup, or trd_-prefixed trader ID emitted by this API. */
         address: string;
     };
+    getTraderGradeAt: {
+        /** Wallet address (0x...), username, or trd_-prefixed trader id. */
+        address: string;
+    };
     getTraderPnl: {
         /** Wallet address (0x...), username, or trd_-prefixed trader id. */
         address: string;
@@ -3803,6 +3949,12 @@ export interface OperationPath {
 /** Each operation's JSON request body; `never` when it takes none. */
 export interface OperationBody {
     activateWebhookSecret: never;
+    batchGetMarketFlow: {
+        /** Market condition IDs to resolve in input order. */
+        condition_ids: string[];
+        /** Lookback window used for flow and trade-count context. */
+        timeframe?: "1h" | "4h" | "24h" | "7d";
+    };
     batchGetMarketIntel: {
         /** Market condition IDs to resolve in input order. */
         condition_ids: string[];
@@ -3831,6 +3983,7 @@ export interface OperationBody {
     exploreMarkets: never;
     getAccountIdentity: never;
     getApiDiscovery: never;
+    getCoverage: never;
     getDailyReportSnapshot: never;
     getEventReplaySince: never;
     getGame: never;
@@ -3839,6 +3992,7 @@ export interface OperationBody {
     getLargeTrade: never;
     getMarketCandles: never;
     getMarketContextMarkdown: never;
+    getMarketFlow: never;
     getMarketHolders: never;
     getMarketIntel: never;
     getMarketSnapshot: never;
@@ -3858,6 +4012,7 @@ export interface OperationBody {
     getTraderContextMarkdown: never;
     getTraderExportSnapshot: never;
     getTraderExportStatus: never;
+    getTraderGradeAt: never;
     getTraderPnl: never;
     getUsage: never;
     getWebhook: never;
@@ -3909,6 +4064,11 @@ export interface OperationResponse {
         data: OperationData["activateWebhookSecret"];
         meta: ResponseMeta;
     };
+    batchGetMarketFlow: {
+        object: "market_flow_batch";
+        data: OperationData["batchGetMarketFlow"];
+        meta: BatchResponseMeta;
+    };
     batchGetMarketIntel: {
         object: "market_intel_batch";
         data: OperationData["batchGetMarketIntel"];
@@ -3959,6 +4119,11 @@ export interface OperationResponse {
         data: OperationData["getApiDiscovery"];
         meta: ResponseMeta;
     };
+    getCoverage: {
+        object: "platforms";
+        data: OperationData["getCoverage"];
+        meta: ResponseMeta;
+    };
     getDailyReportSnapshot: {
         object: "report_snapshot";
         data: OperationData["getDailyReportSnapshot"];
@@ -3999,6 +4164,11 @@ export interface OperationResponse {
         meta: ResponseMeta;
     };
     getMarketContextMarkdown: string;
+    getMarketFlow: {
+        object: "market_flow";
+        data: OperationData["getMarketFlow"];
+        meta: ResponseMeta;
+    };
     getMarketHolders: {
         object: "list";
         data: OperationData["getMarketHolders"];
@@ -4098,6 +4268,11 @@ export interface OperationResponse {
         meta: ResponseMeta;
     };
     getTraderExportStatus: TraderExportJob;
+    getTraderGradeAt: {
+        object: "trader_grade_at";
+        data: OperationData["getTraderGradeAt"];
+        meta: ResponseMeta;
+    };
     getTraderPnl: {
         object: "trader_pnl";
         data: OperationData["getTraderPnl"];
@@ -4162,6 +4337,8 @@ export interface OperationResponse {
     listLargeTradeHistory: {
         object: "list";
         data: OperationData["listLargeTradeHistory"];
+        /** Writer-backed age and coverage for this page; it is part of the representation and the ETag, while transport cache facts remain in meta. */
+        data_quality: DataQuality;
         has_more: boolean;
         next_cursor?: string;
         /** Total matching rows when the read model exposes a count; the key is absent when it does not. */
@@ -4171,6 +4348,8 @@ export interface OperationResponse {
     listLargeTrades: {
         object: "list";
         data: OperationData["listLargeTrades"];
+        /** Writer-backed age and coverage for this page; it is part of the representation and the ETag, while transport cache facts remain in meta. */
+        data_quality: DataQuality;
         has_more: boolean;
         next_cursor?: string;
         /** Total matching rows when the read model exposes a count; absent (or null) when it does not. */
@@ -4189,10 +4368,18 @@ export interface OperationResponse {
     listPositions: {
         object: "list";
         data: OperationData["listPositions"];
+        /** Writer-backed age and coverage for this page; it is part of the representation and the ETag, while transport cache facts remain in meta. */
+        data_quality: DataQuality;
         has_more: boolean;
         next_cursor?: string;
         /** Total matching rows when the read model exposes a count; the key is absent when it does not. */
         total?: number;
+        /** Present only with consistency=snapshot. Dates the frozen response rows, not the provider's underlying observations. */
+        snapshot?: {
+            as_of: string;
+            expires_at: string;
+            row_count: number;
+        };
         meta: ResponseMeta;
     };
     listPreGameSideObservations: {
@@ -4307,6 +4494,8 @@ export interface OperationResponse {
     listWhaleTradeHistory: {
         object: "list";
         data: OperationData["listWhaleTradeHistory"];
+        /** Writer-backed age and coverage for this page; it is part of the representation and the ETag, while transport cache facts remain in meta. */
+        data_quality: DataQuality;
         has_more: boolean;
         next_cursor?: string;
         /** Total matching rows when the read model exposes a count; absent (or null) when it does not. */
@@ -4316,6 +4505,8 @@ export interface OperationResponse {
     listWhaleTrades: {
         object: "list";
         data: OperationData["listWhaleTrades"];
+        /** Writer-backed age and coverage for this page; it is part of the representation and the ETag, while transport cache facts remain in meta. */
+        data_quality: DataQuality;
         has_more: boolean;
         next_cursor?: string;
         /** Total matching rows when the read model exposes a count; the key is absent when it does not. */