@0xinsider/mcp 2.4.0 → 2.8.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,29 @@ 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 = {
+    /** fresh when every group is fresh, unavailable when every group is unavailable, and partial in every other case. */
+    status: "fresh" | "partial" | "unknown" | "untracked" | "unavailable";
+    /** 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. */
+    as_of?: string;
+    /** One entry per field group. Entries may be added in later releases, so match on group rather than on position or length. */
+    field_groups: DataQualityGroup[];
+};
+/** One group of response fields that share a writer and therefore share a clock. */
+export type DataQualityGroup = {
+    /** Stable snake_case group name. Names are additive across releases, so match on the ones you know and ignore the rest. */
+    group: string;
+    /** The table and column that write this group, named so the verdict can be audited (for example trader_rankings.computed_at). */
+    owner: string;
+    /** 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. */
+    status: "fresh" | "partial" | "unknown" | "untracked" | "unavailable";
+    /** 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. */
+    as_of?: string;
+    /** Why the status is not fresh. Omitted when it is. */
+    reason?: string;
 };
 export type EventReplayEvent = {
     /** Opaque event identity: the ef_-encoded whale_alerts.id, stable across cursor formats. Deduplicate on this, never on cursor or sequence. */
@@ -331,6 +356,17 @@ export type EventReplaySource = {
     owner: "whale_alerts";
     provider_fetch_at_request_time: false;
 };
+/** 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. */
+export type ExactDecimal = {
+    /** 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. */
+    value: string;
+    /** Unit of the value, such as `USD`, `USD/share`, or `shares`. */
+    unit: string;
+    /** Number of digits after the decimal point in `value`'s source atom. */
+    scale: number;
+    /** Backend-owned source or derivation basis. Treat it as provenance, not as a display label. */
+    basis: string;
+};
 export type ExploreEntry = ExploreGroup | ExploreStandalone;
 export type ExploreFacets = {
     categories: ExploreFacetValue[];
@@ -420,6 +456,12 @@ export type ExploreMarket = {
         whale_signal: number | null;
         liquidity_signal: number | null;
         recency_signal: number | null;
+        /** Canonical key since #16308; smart_money_signal is its deprecated spelling, emitted beside it with the same value. */
+        sharp_money_signal: number | null;
+        /**
+         * Deprecated spelling of sharp_money_signal; emitted beside it with the same value and never removed.
+         * @deprecated
+         */
         smart_money_signal: number | null;
         price_move_signal: number | null;
         missing_price_penalty: number;
@@ -458,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. */
@@ -550,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. */
@@ -586,7 +695,7 @@ export type HolderCategoryEvidence = {
 export type LargeExportPolicy = {
     mode: "v1_async_export";
     current_internal_route: string;
-    /** Programmatic API-key-gated export routes (submit/status/download) and supported formats (json, ndjson, csv). */
+    /** Programmatic API-key-gated export routes (submit/status/download/cancel) and supported formats (json, ndjson, csv). */
     v1_async: {
         /** POST route template to submit an export job. fresh=true asks for a snapshot read after the submit instead of reusing a finished one. */
         submit_route?: string;
@@ -594,10 +703,12 @@ export type LargeExportPolicy = {
         status_route?: string;
         /** GET route template that 302-redirects to the file. */
         download_route?: string;
+        /** POST route template to cancel a queued or running job. */
+        cancel_route?: string;
         /** Supported ?format= values. */
         formats?: ("json" | "ndjson" | "csv")[];
         /** Possible job status values. */
-        status_values?: ("queued" | "running" | "ready" | "failed" | "reconcile_required" | "expired")[];
+        status_values?: ("queued" | "running" | "ready" | "failed" | "reconcile_required" | "expired" | "cancel_requested" | "cancelled")[];
         /** How long a finished export is retained before expiry. */
         retention?: string;
     };
@@ -687,9 +798,19 @@ export type LargeTrade = {
     /** 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. */
     token_id: string | null;
     price: number;
-    /** Current 0.0–1.0 normalized signal score, computed at request time from the trader's win rate today and the trade's age now. On a historical row it is today's view of the trade, not what a reader saw then; use recorded_signal_score for that. */
+    /** 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. */
+    review_score: number;
+    /**
+     * 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.
+     * @deprecated
+     */
     signal_score: number;
-    /** 0.0–1.0 signal 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. */
+    /** 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_review_score: number | null;
+    /**
+     * 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.
+     * @deprecated
+     */
     recorded_signal_score: number | null;
     /** Persisted live suspicion score from the scorer. Null when the row has no persisted score. */
     suspicion_score: number | null;
@@ -737,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;
@@ -767,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;
@@ -862,65 +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. */
-    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;
@@ -1098,15 +1233,25 @@ export type PickOfTheDay = {
     position?: string;
     /** 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. */
     side_summary?: string;
-    /** Public V1 compatibility count of S/A smart-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. */
+    /** 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. */
+    sharp_wallet_count?: number;
+    /**
+     * 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.
+     * @deprecated
+     */
     smart_wallet_count?: number;
-    /** Best public V1-compatible S/A smart-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. */
+    /** 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. */
     top_grade?: string;
     /** 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_pct?: number;
     /** 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). */
     category_edge_sample?: number;
-    /** Recency-weighted graded-flow magnitude in USD; omitted when <= 0. */
+    /** 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. */
+    sharp_usd?: number;
+    /**
+     * 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.
+     * @deprecated
+     */
     smart_usd?: number;
     /** 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. */
     backed_price?: number;
@@ -1190,15 +1335,15 @@ export type PickOfTheDay = {
         lane_probability_source?: "p";
     };
     trust?: PickTrust;
-    /** Public V1 S/A compatibility count on the backed side (equals the adapted smart_wallet_count). The first-party/internal current policy counts S/A/B. Historical rows retain their frozen policy's count. */
+    /** 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. */
     traders?: number;
-    /** Raw backed-side sharp-money USD frozen at generation. This is the Sharp USD value, not the recency-weighted smart_usd which decays. Omitted on current public V1 rows when the B-inclusive value has no reconstructible S/A equivalent. */
+    /** 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. */
     backed_sharp_usd?: number;
     /** 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. */
     holders?: PickHolder[];
     /** 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. */
     display_holders?: PickHolder[];
-    /** Exact S/A smart-money proof count on the backed side. The current display_holders roster can be longer because it also carries B-grade smart-money holders. */
+    /** 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. */
     holder_count?: number;
     /** Optional editorial note attached to the pick. */
     editorial_note?: string;
@@ -1263,7 +1408,7 @@ export type PickOfTheDayArchiveEntry = {
     image_url?: string;
     /** The backed side's outcome label. Omitted for a still-pending pick when the request is not from an authenticated Pro key. */
     pick_outcome_label?: string;
-    /** Best public V1-compatible S/A smart-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 smart-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. */
+    /** 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. */
     top_grade?: string;
     /** Settlement outcome of the backed side; 'pending' until the market resolves. */
     outcome: "pending" | "win" | "loss" | "void";
@@ -1591,6 +1736,8 @@ export type Position = {
     cash_pnl?: number;
     /** Closed-leg P&L rolled up (Polymarket `realizedPnl`). */
     realized_pnl?: number;
+    /** 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. */
+    exact?: PositionExact;
     /** Max updated_at across mirror legs for this pair. */
     last_reconciled_at?: string;
     /** Backend-computed staleness bucket derived from last_reconciled_at. */
@@ -1623,6 +1770,17 @@ export type Position = {
         end_date?: string;
     };
 };
+/** 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. */
+export type PositionExact = {
+    shares: ExactDecimal;
+    cost_basis_usd?: ExactDecimal;
+    /** Exact derived price: `wallet_positions.cost_basis_usd / wallet_positions.shares`. */
+    avg_price?: ExactDecimal;
+    current_value_usd: ExactDecimal;
+    initial_value_usd?: ExactDecimal;
+    cash_pnl?: ExactDecimal;
+    realized_pnl?: ExactDecimal;
+};
 export type PositionTimelineEvent = {
     /** Prefixed ID (pe_...). */
     id: string;
@@ -1679,7 +1837,10 @@ export type PreGameSide = {
     side_share: number | null;
     /** Polymarket condition id. */
     condition_id: string;
-    /** 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. */
+    /**
+     * 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.
+     * @deprecated
+     */
     signal_created_at: string;
     /** Polymarket CLOB token id (ERC1155 asset id, decimal string) for the PILED outcome; null when unavailable. */
     token_id: string | null;
@@ -1691,7 +1852,10 @@ export type PreGameSide = {
     event_slug: string | null;
     /** 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. */
     game_start_time: string | null;
-    /** 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. */
+    /**
+     * 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.
+     * @deprecated
+     */
     piled_side: string | null;
     /** 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. */
     piled_outcome_index: number;
@@ -1709,13 +1873,19 @@ export type PreGameSide = {
     graded_holders: number;
     /** Best grade present on the piled side; null when none. */
     top_grade: "S" | "A" | "B" | null;
-    /** 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. */
+    /**
+     * 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.
+     * @deprecated
+     */
     smart_score: number | null;
     /** Market volume (USD). */
     volume: number | null;
     /** Aggregate recent flow direction on the market; null when unavailable. */
     net_side: "BUY" | "SELL" | null;
-    /** Grade-weighted pile score (5*s + 4*a + 3*b) * 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. */
+    /**
+     * Grade-weighted pile score (5*s + 4*a + 3*b) * 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.
+     * @deprecated
+     */
     conviction_score: number;
     /** 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. */
     one_way_holder_count: number | null;
@@ -1789,7 +1959,10 @@ export type PreGameSideObservation = {
     cohort: "wider_holder" | "in_play" | "emerging_pile";
     /** Always true. This row must not be routed to an order executor. */
     observation_only: true;
-    /** 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. */
+    /**
+     * 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.
+     * @deprecated
+     */
     piled_side: string | null;
     /** 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. */
     piled_outcome_index: 0 | 1;
@@ -1805,11 +1978,17 @@ export type PreGameSideObservation = {
     /** Piled-side S/A/B holder count. */
     graded_holders: number;
     top_grade: "S" | "A" | "B";
-    /** Canonical signed holder-pile score. Deprecated (#16310): `side_share` is the canonical spelling and carries the same value; this key stays on the wire. */
+    /**
+     * Canonical signed holder-pile score. Deprecated (#16310): `side_share` is the canonical spelling and carries the same value; this key stays on the wire.
+     * @deprecated
+     */
     smart_score: number;
     /** Strictly positive stored market volume in USD. Missing, zero, or non-finite volume terminates as invalid_market and is never emitted as an observation. */
     volume: number;
-    /** 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. */
+    /**
+     * 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.
+     * @deprecated
+     */
     conviction_score: number;
     /** Whether the provider holder page came from the shared cache or a live provider read. */
     provider_read_source: "cached" | "live";
@@ -1967,9 +2146,9 @@ export type ResponseMeta = {
     ranking_generation?: number;
     /** 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. */
     ranking_as_of?: string;
-    /** 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 smart-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. */
+    /** 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. */
     directional_source?: "live" | "degraded";
-    /** 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 smart-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. */
+    /** 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. */
     ranking_source?: "live" | "db_only";
     /** Whole filtered snapshot category-evidence status before pagination. Operational live always remains partial source coverage. */
     category_skill_source?: "live" | "partial" | "degraded" | "unavailable";
@@ -2032,7 +2211,10 @@ export type SmartMoneyFlowMarket = {
         buy_volume_usd: number;
         sell_volume_usd: number;
     };
-    /** Deprecated alias of sharp_money; byte-identical and retained for backward compatibility. */
+    /**
+     * Deprecated alias of sharp_money; byte-identical and retained for backward compatibility.
+     * @deprecated
+     */
     smart_money: {
         net_flow_usd: number;
         direction: "YES" | "NO";
@@ -2114,6 +2296,10 @@ export type Trader = {
     /** Hot-streak tier (trailing-7d cross-sectional percentile); a separate axis from the all-time grade. Omitted when there is no recent activity. */
     streak_tier?: "hot" | "rising" | "neutral" | "cooling" | "cold";
     score?: number;
+    /** 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_score?: number;
+    /** 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. */
+    forecast_evidence?: number;
     rank?: number;
     pnl: {
         total?: number;
@@ -2124,13 +2310,17 @@ export type Trader = {
         last_7d?: number;
         /** DEPRECATED, never sent. The local pnl_30d rollup over-counted P&L (#5416 class) and is no longer emitted. Read the provider-native monthly window from GET /api/trader/{address}/profile-summary instead. */
         last_30d?: number;
+        /** Additive lossless counterpart. Omitted when the trusted native realized-P&L source is unavailable; existing numeric fields keep their display-safe v1 semantics. */
+        exact?: TraderPnlExact;
     };
     stats: {
         markets_traded?: number;
         win_rate?: number;
         daily_win_rate?: number;
-        /** Full-history both-sides USD cash volume from Polymarket user-volume. Omitted without a verified observation; never leaderboard shares. Volume freshness is unknown in this DTO and does not use synced_at. */
+        /** Full-history both-sides USD cash volume from Polymarket user-volume. Omitted without a verified observation; never leaderboard shares. Its observation time is published as the volume group in data_quality and as trust.total_volume.freshness.as_of, both trader_usd_volume.observed_at; synced_at is a different clock and is never a substitute for it. */
         total_volume?: number;
+        /** Additive lossless counterpart to `total_volume`. Omitted when the verified provider observation is unavailable. */
+        exact?: TraderStatsExact;
     };
     strategy?: {
         strategy_type?: string;
@@ -2164,6 +2354,8 @@ 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 (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;
     /** 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. */
@@ -2248,22 +2440,56 @@ export type TraderEsportsGameRecord = {
     /** 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. */
     status: "measured" | "not_enough_data";
 };
+export type TraderExportArtifactManifest = {
+    /** Version of the artifact manifest contract. */
+    manifest_version: string;
+    /** Serialization used for the decompressed content. */
+    format: "json" | "ndjson" | "csv";
+    /** Stable schema identifier for the selected serialization. */
+    schema_version: "trader-export-json-v1" | "trader-export-ndjson-v1" | "trader-export-csv-v1";
+    /** Sections represented by the artifact. JSON and NDJSON carry the full envelope and trades; CSV carries trade rows only. */
+    coverage: "full_envelope_and_trades" | "trades_only";
+    generation: TraderExportGeneration;
+    /** Number of trade rows written. */
+    row_count: number;
+    /** Exact byte count of the decompressed content stream clients receive. */
+    content_size_bytes: number;
+    /** Lowercase SHA-256 of the decompressed content bytes. */
+    content_sha256: string;
+    /** Exact byte count of the gzip-compressed bytes stored by the object provider. */
+    compressed_size_bytes: number;
+    /** Lowercase SHA-256 of the stored gzip bytes; the multipart ETag is not used as this checksum. */
+    compressed_sha256: string;
+};
+export type TraderExportCategoryWatermark = {
+    source: string;
+    coverage: string;
+    publication_fence: string | null;
+    data_as_of: string | null;
+};
+export type TraderExportGeneration = {
+    /** Opaque generation identity selected for the coherent read snapshot. */
+    id: string;
+    selected_at: string;
+    consistency: "repeatable_read";
+    source_watermarks: TraderExportSourceWatermarks;
+};
 export type TraderExportJob = {
     object: "trader_export_job";
     data: {
         job_id: number;
-        /** queued: accepted, not started. running: the worker is streaming rows. reconcile_required: the upload finished but the storage completion answer was lost; the hourly reconciler reads the object back and moves the job to ready or failed, and expires_at bounds the wait. ready: downloadable until expires_at. failed: terminal; error says why; submit a new export. expired: the retention window passed; the file is retired, the download route answers 410, submit a new export. A job that has not reached ready by expires_at reads failed with error 'export expired before completion'. failed and expired rows stay readable for 48 hours, then the job answers 404. */
-        status: "queued" | "running" | "ready" | "failed" | "reconcile_required" | "expired";
+        /** queued: accepted, not started. running: the worker is streaming rows. reconcile_required: the upload finished but the storage completion answer was lost; the hourly reconciler reads the object back and moves the job to ready or failed, and expires_at bounds the wait. ready: downloadable until expires_at. failed: terminal; error says why; submit a new export. expired: the retention window passed; the file is retired, the download route answers 410, submit a new export. cancel_requested: the owner cancelled a running job (POST /api/v1/trader/{address}/export/cancel); the worker stops at its next safe point and the job reads cancelled. cancelled: terminal; the owner cancelled the job and no file was published; submit a new export. A job that has not reached ready by expires_at reads failed with error 'export expired before completion'. failed, cancelled and expired rows stay readable for 48 hours, then the job answers 404. */
+        status: "queued" | "running" | "ready" | "failed" | "reconcile_required" | "expired" | "cancel_requested" | "cancelled";
         format: "json" | "ndjson" | "csv";
         total_trades: number | null;
         processed_trades: number | null;
         file_size: number | null;
         error: string | null;
-        /** True when status never changes again (ready, failed, expired). Stop polling. */
+        /** True when status never changes again (ready, failed, expired, cancelled). Stop polling. */
         terminal: boolean;
         /** What to do next: poll the status route after poll_after_s, follow the download route, or submit a new export. Published beside status so a status value added later does not strand a client. */
         next_action: "poll" | "download" | "resubmit";
-        /** Seconds to wait before polling again. Absent when terminal. 5 while queued or running; 300 while reconcile_required, the cadence that state can change at. */
+        /** Seconds to wait before polling again. Absent when terminal. 5 while queued, running or cancel_requested; 300 while reconcile_required, the cadence that state can change at. */
         poll_after_s?: number;
         created_at: string;
         /** When the worker last claimed the job; null while queued. */
@@ -2277,22 +2503,42 @@ export type TraderExportJob = {
         expired_at: string | null;
         /** What the file is a snapshot of: the trader's served-data clock (the latest position refresh, else the last completed sync) when the file was written; the same value as export_metadata.data_as_of inside the file. null until the file is written, or when the trader had neither. Read this, not ready_at, to decide whether a reused job is fresh enough; submit with fresh=true for a newer snapshot. */
         data_as_of: string | null;
+        /** When the owner asked to cancel the job; null otherwise. Set on every cancelled job, including one cancelled while queued. While status is cancel_requested this is the instant the worker was asked to stop. */
+        cancel_requested_at: string | null;
+        /** When the job reached cancelled; null until then. */
+        cancelled_at: string | null;
         /** Worker claims so far. */
         attempt: number;
         /** The job fails when attempt reaches this. */
         max_attempts: number;
         /** Present only while status is ready: the stored object's identity, so a client can check the download it receives. */
         artifact?: {
+            /** Stable identity for this completed export artifact; unchanged when a temporary download URL is renewed. */
+            artifact_id: string;
             /** The storage ETag of the object. */
             etag: string | null;
             /** Bytes on the wire (gzip); file_size is the decompressed size. */
             compressed_size_bytes: number | null;
             content_type: "application/json" | "application/x-ndjson" | "text/csv";
             content_encoding: "gzip";
+            /** Immutable manifest for artifacts generated with manifest support; null on historical artifacts written before this contract. */
+            manifest: TraderExportArtifactManifest | null;
         };
     };
     meta: ResponseMeta;
 };
+export type TraderExportPnlWatermark = {
+    source: string;
+    coverage: string;
+    revision: number | null;
+    observed_at: string | null;
+};
+export type TraderExportPositionWatermark = {
+    source: string;
+    coverage: string;
+    generation: number | null;
+    data_as_of: string | null;
+};
 export type TraderExportSnapshot = {
     address: string;
     generated_at: string;
@@ -2302,6 +2548,49 @@ export type TraderExportSnapshot = {
     counts: ExportCounts;
     large_export_policy: LargeExportPolicy;
 };
+export type TraderExportSourceWatermarks = {
+    positions: TraderExportPositionWatermark;
+    pnl: TraderExportPnlWatermark;
+    categories: TraderExportCategoryWatermark;
+    trades: TraderExportTradeWatermark;
+};
+export type TraderExportTradeWatermark = {
+    source: string;
+    coverage: string;
+    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_...`). */
@@ -2414,6 +2703,16 @@ export type TraderPnl = {
         drawdown: number;
     }[];
 };
+/** Lossless counterparts for trader P&L values. The object is omitted when no trusted native realized-P&L snapshot is available. */
+export type TraderPnlExact = {
+    /** 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. */
+    realized: ExactDecimal;
+};
+/** Lossless counterparts for trader statistics. The object is omitted when the verified provider observation is unavailable. */
+export type TraderStatsExact = {
+    /** Full-history both-sides Polymarket user-volume atom from the verified `trader_usd_volume` observation. */
+    total_volume: ExactDecimal;
+};
 /** Field-level trust metadata returned only when GET /api/v1/trader/{address} includes expand=trust. */
 export type TraderTrust = {
     total_pnl: TrustMetadata;
@@ -2425,6 +2724,8 @@ export type TraderTrust = {
     total_volume: TrustMetadata;
     grade: TrustMetadata;
     score: TrustMetadata;
+    forecast_score: TrustMetadata;
+    forecast_evidence: TrustMetadata;
     rank: TrustMetadata;
     streak_tier: TrustMetadata;
     strategy: TrustMetadata;
@@ -2505,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 = {
@@ -2579,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;
@@ -2591,7 +2894,7 @@ export type WebhookEndpoint = {
     signing_secret?: string;
     verification?: WebhookVerification;
 };
-/** 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 (whale_trades_inserted, wallet_grade_changed, suspicious_trade_flagged, insider_radar_flag_raised, smart_money_flow_detected) only deliver to API keys on an active Pro subscription. suspicious_trade_flagged and insider_radar_flag_raised are two spellings of one event: either one subscribes, and an endpoint receives deliveries under the spelling it registered. */
+/** 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. */
 export type WebhookEventDescriptor = {
     id: WebhookEventType;
     /** One-line description of when the event fires. */
@@ -2601,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 = "whale_trades_inserted" | "live_sports_updated" | "whale_trader_synced" | "large_positions_updated" | "wallet_grade_changed" | "suspicious_trade_flagged" | "insider_radar_flag_raised" | "smart_money_flow_detected";
+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";
@@ -2629,8 +2932,58 @@ export type WebhookVerification = {
  */
 export interface OperationData {
     activateWebhookSecret: WebhookEndpoint;
-    batchGetMarketIntel: BatchMarketIntelItem[];
+    batchGetMarketFlow: BatchMarketFlowItem[];
+    batchGetMarketIntel: BatchMarketFlowItem[];
     batchGetTraders: BatchTraderItem[];
+    cancelTraderExport: {
+        job_id: number;
+        /** queued: accepted, not started. running: the worker is streaming rows. reconcile_required: the upload finished but the storage completion answer was lost; the hourly reconciler reads the object back and moves the job to ready or failed, and expires_at bounds the wait. ready: downloadable until expires_at. failed: terminal; error says why; submit a new export. expired: the retention window passed; the file is retired, the download route answers 410, submit a new export. cancel_requested: the owner cancelled a running job (POST /api/v1/trader/{address}/export/cancel); the worker stops at its next safe point and the job reads cancelled. cancelled: terminal; the owner cancelled the job and no file was published; submit a new export. A job that has not reached ready by expires_at reads failed with error 'export expired before completion'. failed, cancelled and expired rows stay readable for 48 hours, then the job answers 404. */
+        status: "queued" | "running" | "ready" | "failed" | "reconcile_required" | "expired" | "cancel_requested" | "cancelled";
+        format: "json" | "ndjson" | "csv";
+        total_trades: number | null;
+        processed_trades: number | null;
+        file_size: number | null;
+        error: string | null;
+        /** True when status never changes again (ready, failed, expired, cancelled). Stop polling. */
+        terminal: boolean;
+        /** What to do next: poll the status route after poll_after_s, follow the download route, or submit a new export. Published beside status so a status value added later does not strand a client. */
+        next_action: "poll" | "download" | "resubmit";
+        /** Seconds to wait before polling again. Absent when terminal. 5 while queued, running or cancel_requested; 300 while reconcile_required, the cadence that state can change at. */
+        poll_after_s?: number;
+        created_at: string;
+        /** When the worker last claimed the job; null while queued. */
+        started_at: string | null;
+        /** When the file became downloadable. null before ready, and on jobs finalized before this field existed. */
+        ready_at: string | null;
+        failed_at: string | null;
+        /** The retention window: 24 hours from submit. A ready file downloads until this instant; a job that has not reached ready by it fails. A reused job (200 on submit) keeps its original window. */
+        expires_at: string;
+        /** When the job became expired; null until then. */
+        expired_at: string | null;
+        /** What the file is a snapshot of: the trader's served-data clock (the latest position refresh, else the last completed sync) when the file was written; the same value as export_metadata.data_as_of inside the file. null until the file is written, or when the trader had neither. Read this, not ready_at, to decide whether a reused job is fresh enough; submit with fresh=true for a newer snapshot. */
+        data_as_of: string | null;
+        /** When the owner asked to cancel the job; null otherwise. Set on every cancelled job, including one cancelled while queued. While status is cancel_requested this is the instant the worker was asked to stop. */
+        cancel_requested_at: string | null;
+        /** When the job reached cancelled; null until then. */
+        cancelled_at: string | null;
+        /** Worker claims so far. */
+        attempt: number;
+        /** The job fails when attempt reaches this. */
+        max_attempts: number;
+        /** Present only while status is ready: the stored object's identity, so a client can check the download it receives. */
+        artifact?: {
+            /** Stable identity for this completed export artifact; unchanged when a temporary download URL is renewed. */
+            artifact_id: string;
+            /** The storage ETag of the object. */
+            etag: string | null;
+            /** Bytes on the wire (gzip); file_size is the decompressed size. */
+            compressed_size_bytes: number | null;
+            content_type: "application/json" | "application/x-ndjson" | "text/csv";
+            content_encoding: "gzip";
+            /** Immutable manifest for artifacts generated with manifest support; null on historical artifacts written before this contract. */
+            manifest: TraderExportArtifactManifest | null;
+        };
+    };
     createMcpJsonRpcResponse: {
         jsonrpc: "2.0";
         id: string | number | null;
@@ -2658,6 +3011,7 @@ export interface OperationData {
         scopes: string[] | null;
     };
     getApiDiscovery: ApiDiscovery;
+    getCoverage: Platforms;
     getDailyReportSnapshot: ReportSnapshot;
     getEventReplaySince: EventReplayEvent[];
     getGame: Game;
@@ -2687,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;
@@ -2707,18 +3062,18 @@ export interface OperationData {
     getTraderExportSnapshot: TraderExportSnapshot;
     getTraderExportStatus: {
         job_id: number;
-        /** queued: accepted, not started. running: the worker is streaming rows. reconcile_required: the upload finished but the storage completion answer was lost; the hourly reconciler reads the object back and moves the job to ready or failed, and expires_at bounds the wait. ready: downloadable until expires_at. failed: terminal; error says why; submit a new export. expired: the retention window passed; the file is retired, the download route answers 410, submit a new export. A job that has not reached ready by expires_at reads failed with error 'export expired before completion'. failed and expired rows stay readable for 48 hours, then the job answers 404. */
-        status: "queued" | "running" | "ready" | "failed" | "reconcile_required" | "expired";
+        /** queued: accepted, not started. running: the worker is streaming rows. reconcile_required: the upload finished but the storage completion answer was lost; the hourly reconciler reads the object back and moves the job to ready or failed, and expires_at bounds the wait. ready: downloadable until expires_at. failed: terminal; error says why; submit a new export. expired: the retention window passed; the file is retired, the download route answers 410, submit a new export. cancel_requested: the owner cancelled a running job (POST /api/v1/trader/{address}/export/cancel); the worker stops at its next safe point and the job reads cancelled. cancelled: terminal; the owner cancelled the job and no file was published; submit a new export. A job that has not reached ready by expires_at reads failed with error 'export expired before completion'. failed, cancelled and expired rows stay readable for 48 hours, then the job answers 404. */
+        status: "queued" | "running" | "ready" | "failed" | "reconcile_required" | "expired" | "cancel_requested" | "cancelled";
         format: "json" | "ndjson" | "csv";
         total_trades: number | null;
         processed_trades: number | null;
         file_size: number | null;
         error: string | null;
-        /** True when status never changes again (ready, failed, expired). Stop polling. */
+        /** True when status never changes again (ready, failed, expired, cancelled). Stop polling. */
         terminal: boolean;
         /** What to do next: poll the status route after poll_after_s, follow the download route, or submit a new export. Published beside status so a status value added later does not strand a client. */
         next_action: "poll" | "download" | "resubmit";
-        /** Seconds to wait before polling again. Absent when terminal. 5 while queued or running; 300 while reconcile_required, the cadence that state can change at. */
+        /** Seconds to wait before polling again. Absent when terminal. 5 while queued, running or cancel_requested; 300 while reconcile_required, the cadence that state can change at. */
         poll_after_s?: number;
         created_at: string;
         /** When the worker last claimed the job; null while queued. */
@@ -2732,20 +3087,29 @@ export interface OperationData {
         expired_at: string | null;
         /** What the file is a snapshot of: the trader's served-data clock (the latest position refresh, else the last completed sync) when the file was written; the same value as export_metadata.data_as_of inside the file. null until the file is written, or when the trader had neither. Read this, not ready_at, to decide whether a reused job is fresh enough; submit with fresh=true for a newer snapshot. */
         data_as_of: string | null;
+        /** When the owner asked to cancel the job; null otherwise. Set on every cancelled job, including one cancelled while queued. While status is cancel_requested this is the instant the worker was asked to stop. */
+        cancel_requested_at: string | null;
+        /** When the job reached cancelled; null until then. */
+        cancelled_at: string | null;
         /** Worker claims so far. */
         attempt: number;
         /** The job fails when attempt reaches this. */
         max_attempts: number;
         /** Present only while status is ready: the stored object's identity, so a client can check the download it receives. */
         artifact?: {
+            /** Stable identity for this completed export artifact; unchanged when a temporary download URL is renewed. */
+            artifact_id: string;
             /** The storage ETag of the object. */
             etag: string | null;
             /** Bytes on the wire (gzip); file_size is the decompressed size. */
             compressed_size_bytes: number | null;
             content_type: "application/json" | "application/x-ndjson" | "text/csv";
             content_encoding: "gzip";
+            /** Immutable manifest for artifacts generated with manifest support; null on historical artifacts written before this contract. */
+            manifest: TraderExportArtifactManifest | null;
         };
     };
+    getTraderGradeAt: TraderGradeAt;
     getTraderPnl: TraderPnl;
     getUsage: {
         rate_limit: {
@@ -2818,18 +3182,18 @@ export interface OperationData {
     searchMarkets: MarketSearchResult[];
     submitTraderExport: {
         job_id: number;
-        /** queued: accepted, not started. running: the worker is streaming rows. reconcile_required: the upload finished but the storage completion answer was lost; the hourly reconciler reads the object back and moves the job to ready or failed, and expires_at bounds the wait. ready: downloadable until expires_at. failed: terminal; error says why; submit a new export. expired: the retention window passed; the file is retired, the download route answers 410, submit a new export. A job that has not reached ready by expires_at reads failed with error 'export expired before completion'. failed and expired rows stay readable for 48 hours, then the job answers 404. */
-        status: "queued" | "running" | "ready" | "failed" | "reconcile_required" | "expired";
+        /** queued: accepted, not started. running: the worker is streaming rows. reconcile_required: the upload finished but the storage completion answer was lost; the hourly reconciler reads the object back and moves the job to ready or failed, and expires_at bounds the wait. ready: downloadable until expires_at. failed: terminal; error says why; submit a new export. expired: the retention window passed; the file is retired, the download route answers 410, submit a new export. cancel_requested: the owner cancelled a running job (POST /api/v1/trader/{address}/export/cancel); the worker stops at its next safe point and the job reads cancelled. cancelled: terminal; the owner cancelled the job and no file was published; submit a new export. A job that has not reached ready by expires_at reads failed with error 'export expired before completion'. failed, cancelled and expired rows stay readable for 48 hours, then the job answers 404. */
+        status: "queued" | "running" | "ready" | "failed" | "reconcile_required" | "expired" | "cancel_requested" | "cancelled";
         format: "json" | "ndjson" | "csv";
         total_trades: number | null;
         processed_trades: number | null;
         file_size: number | null;
         error: string | null;
-        /** True when status never changes again (ready, failed, expired). Stop polling. */
+        /** True when status never changes again (ready, failed, expired, cancelled). Stop polling. */
         terminal: boolean;
         /** What to do next: poll the status route after poll_after_s, follow the download route, or submit a new export. Published beside status so a status value added later does not strand a client. */
         next_action: "poll" | "download" | "resubmit";
-        /** Seconds to wait before polling again. Absent when terminal. 5 while queued or running; 300 while reconcile_required, the cadence that state can change at. */
+        /** Seconds to wait before polling again. Absent when terminal. 5 while queued, running or cancel_requested; 300 while reconcile_required, the cadence that state can change at. */
         poll_after_s?: number;
         created_at: string;
         /** When the worker last claimed the job; null while queued. */
@@ -2843,18 +3207,26 @@ export interface OperationData {
         expired_at: string | null;
         /** What the file is a snapshot of: the trader's served-data clock (the latest position refresh, else the last completed sync) when the file was written; the same value as export_metadata.data_as_of inside the file. null until the file is written, or when the trader had neither. Read this, not ready_at, to decide whether a reused job is fresh enough; submit with fresh=true for a newer snapshot. */
         data_as_of: string | null;
+        /** When the owner asked to cancel the job; null otherwise. Set on every cancelled job, including one cancelled while queued. While status is cancel_requested this is the instant the worker was asked to stop. */
+        cancel_requested_at: string | null;
+        /** When the job reached cancelled; null until then. */
+        cancelled_at: string | null;
         /** Worker claims so far. */
         attempt: number;
         /** The job fails when attempt reaches this. */
         max_attempts: number;
         /** Present only while status is ready: the stored object's identity, so a client can check the download it receives. */
         artifact?: {
+            /** Stable identity for this completed export artifact; unchanged when a temporary download URL is renewed. */
+            artifact_id: string;
             /** The storage ETag of the object. */
             etag: string | null;
             /** Bytes on the wire (gzip); file_size is the decompressed size. */
             compressed_size_bytes: number | null;
             content_type: "application/json" | "application/x-ndjson" | "text/csv";
             content_encoding: "gzip";
+            /** Immutable manifest for artifacts generated with manifest support; null on historical artifacts written before this contract. */
+            manifest: TraderExportArtifactManifest | null;
         };
     };
     updateWebhook: WebhookEndpoint;
@@ -2863,8 +3235,13 @@ 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: {
+        /** Export job id returned by the submit route. */
+        job_id: number;
+    };
     createMcpJsonRpcResponse: Record<string, never>;
     createWebhook: Record<string, never>;
     deleteWebhook: Record<string, never>;
@@ -2886,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;
@@ -2919,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";
@@ -2978,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: {
@@ -2987,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. */
@@ -2999,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;
@@ -3083,7 +3475,7 @@ export interface OperationQuery {
         limit?: number;
         /** Pagination cursor from previous response's next_cursor. Prefix: wth_. URL-encode when replaying as a query parameter. */
         cursor?: string;
-        /** Minimum trade size in USD. The capture floor was 3,000 USD before 2026-07-06 and 10,000 USD from then (1,000 USD in earnings markets), so 10000 gives one size rule across the whole archive. */
+        /** Minimum trade size in USD. The capture floor was 3,000 USD before 2026-07-06 and 10,000 USD from then (1,000 USD in earnings markets), so 10000 gives one size rule across the whole archive. From 2026-09-23 a fill must also be at least 0.1% of its market's recorded traded volume (Polymarket's own share count); rows written before that date were not re-filtered. */
         min_size?: number;
         /** Exact raw provider condition_id. Unknown markets return an empty list. */
         condition_id?: string;
@@ -3101,6 +3493,10 @@ export interface OperationQuery {
         from?: string;
         /** Exclusive RFC3339 upper bound on whale_alerts.traded_at. Must be after from when both are present. */
         to?: string;
+        /** Keep only trades whose market_volume_share is known and at least this. A fraction, not a percent: 0.01 is one percent of the market's traded volume. A trade whose share is unavailable is never returned by a non-zero value, because an unavailable share cannot be said to clear a floor. */
+        min_market_volume_share?: number;
+        /** Order of the returned page. recent is newest first and is the default. market_volume_share ranks by each trade's share of its market's traded volume, biggest first, with a trade whose share is unavailable last. That ranking reads from, or the last 30 days when from is omitted, for the same reason. A cursor is bound to the order it was minted in, so a continuation cannot cross from one order into the other. */
+        sort?: "recent" | "market_volume_share";
     };
     listLargeTrades: {
         /** Maximum number of recent large trades to return. */
@@ -3115,6 +3511,10 @@ export interface OperationQuery {
         min_grade?: "S" | "A" | "B" | "C" | "D" | "F";
         /** When true, return only rows with persisted suspicion_score >= 60. The filter is applied before SQL-backed limit + 1 pagination. */
         suspicious_only?: boolean;
+        /** Keep only trades whose market_volume_share is known and at least this. A fraction, not a percent: 0.01 is one percent of the market's traded volume. A trade whose share is unavailable is never returned by a non-zero value, because an unavailable share cannot be said to clear a floor. */
+        min_market_volume_share?: number;
+        /** Order of the returned page. recent is newest first and is the default. market_volume_share ranks by each trade's share of its market's traded volume, biggest first, with a trade whose share is unavailable last. That ranking reads the last 30 days, because the share is computed for each request and an unbounded ranking cannot be served inside the documented latency budget. A cursor is bound to the order it was minted in, so a continuation cannot cross from one order into the other. */
+        sort?: "recent" | "market_volume_share";
     };
     listLeaderboard: {
         /** Maximum number of ranked traders to return. */
@@ -3131,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. */
@@ -3289,6 +3691,10 @@ export interface OperationQuery {
         from?: string;
         /** Exclusive RFC3339 upper bound on whale_alerts.traded_at. Must be after from when both are present. */
         to?: string;
+        /** Keep only trades whose market_volume_share is known and at least this. A fraction, not a percent: 0.01 is one percent of the market's traded volume. A trade whose share is unavailable is never returned by a non-zero value, because an unavailable share cannot be said to clear a floor. */
+        min_market_volume_share?: number;
+        /** Order of the returned page. recent is newest first and is the default. market_volume_share ranks by each trade's share of its market's traded volume, biggest first, with a trade whose share is unavailable last. That ranking reads from, or the last 30 days when from is omitted, for the same reason. A cursor is bound to the order it was minted in, so a continuation cannot cross from one order into the other. */
+        sort?: "recent" | "market_volume_share";
     };
     listWhaleTrades: {
         /** Maximum number of recent large trades to return. */
@@ -3303,6 +3709,10 @@ export interface OperationQuery {
         min_grade?: "S" | "A" | "B" | "C" | "D" | "F";
         /** When true, return only rows with persisted suspicion_score >= 60. The filter is applied before SQL-backed limit + 1 pagination. */
         suspicious_only?: boolean;
+        /** Keep only trades whose market_volume_share is known and at least this. A fraction, not a percent: 0.01 is one percent of the market's traded volume. A trade whose share is unavailable is never returned by a non-zero value, because an unavailable share cannot be said to clear a floor. */
+        min_market_volume_share?: number;
+        /** Order of the returned page. recent is newest first and is the default. market_volume_share ranks by each trade's share of its market's traded volume, biggest first, with a trade whose share is unavailable last. That ranking reads the last 30 days, because the share is computed for each request and an unbounded ranking cannot be served inside the documented latency budget. A cursor is bound to the order it was minted in, so a continuation cannot cross from one order into the other. */
+        sort?: "recent" | "market_volume_share";
     };
     prepareWebhookSecret: Record<string, never>;
     redeliverWebhookDelivery: Record<string, never>;
@@ -3342,8 +3752,13 @@ 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: {
+        /** Trader wallet address (0x...), known trader username-style lookup, or trd_-prefixed trader ID emitted by this API. */
+        address: string;
+    };
     createMcpJsonRpcResponse: Record<string, never>;
     createWebhook: Record<string, never>;
     deleteWebhook: {
@@ -3353,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: {
@@ -3376,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;
@@ -3431,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;
@@ -3525,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[];
@@ -3537,6 +3967,7 @@ export interface OperationBody {
         /** Shared expand flags applied to every trader item. */
         expand?: ("strategy" | "categories" | "quant_metrics" | "trust")[];
     };
+    cancelTraderExport: never;
     createMcpJsonRpcResponse: {
         /** JSON-RPC protocol version; this server accepts 2.0. */
         jsonrpc: "2.0";
@@ -3552,6 +3983,7 @@ export interface OperationBody {
     exploreMarkets: never;
     getAccountIdentity: never;
     getApiDiscovery: never;
+    getCoverage: never;
     getDailyReportSnapshot: never;
     getEventReplaySince: never;
     getGame: never;
@@ -3560,6 +3992,7 @@ export interface OperationBody {
     getLargeTrade: never;
     getMarketCandles: never;
     getMarketContextMarkdown: never;
+    getMarketFlow: never;
     getMarketHolders: never;
     getMarketIntel: never;
     getMarketSnapshot: never;
@@ -3579,6 +4012,7 @@ export interface OperationBody {
     getTraderContextMarkdown: never;
     getTraderExportSnapshot: never;
     getTraderExportStatus: never;
+    getTraderGradeAt: never;
     getTraderPnl: never;
     getUsage: never;
     getWebhook: never;
@@ -3630,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"];
@@ -3640,6 +4079,7 @@ export interface OperationResponse {
         data: OperationData["batchGetTraders"];
         meta: BatchResponseMeta;
     };
+    cancelTraderExport: TraderExportJob;
     createMcpJsonRpcResponse: {
         jsonrpc: "2.0";
         id: string | number | null;
@@ -3679,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"];
@@ -3719,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"];
@@ -3818,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"];
@@ -3882,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. */
@@ -3891,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. */
@@ -3909,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: {
@@ -4027,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. */
@@ -4036,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. */