@0xinsider/sdk 0.15.0 → 0.16.0

package/dist/schema.d.ts

@@ -802,10 +802,10 @@ 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 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. */
+    /** Current trade review score on a 0..1 scale; higher values indicate a stronger review signal. This is the current response value and can differ from the recorded score. Missing measurements remain unavailable. */
     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 alias of review_score with the same current value and 0..1 scale.
      * @deprecated
      */
     signal_score: number;
@@ -1205,7 +1205,6 @@ export type PickHolder = {
     is_bot?: boolean;
     /** The wallet's X handle from its Polymarket profile, normalized to 1-15 characters of [A-Za-z0-9_] with no `@`. Link it as `https://x.com/<handle>`. Stamped at serve time from the wallet's current trader record, never frozen with the pick. The five badge fields are present together, and only for a wallet that carries at least one badge; all absent means no badge, or a body cached before the fields shipped. */
     x_username?: string | null;
-    category_evidence?: HolderCategoryEvidence;
 };
 export type PickOfTheDay = {
     /** Always 'full' for an authenticated Pro key. */
@@ -1217,7 +1216,7 @@ export type PickOfTheDay = {
      * @deprecated
      */
     pick_rank?: number;
-    /** The complete ranked picks for this product day, ordered by pick_rank. Thin days contain fewer items; the selector never fabricates rows. */
+    /** Published picks for this product day in the returned display order. Use pick_id for identity. */
     picks?: PickOfTheDay[];
     /** Number of items in `picks`: the proof-readable picks. Picks held in `proof_pending_picks` are not counted. */
     pick_count?: number;
@@ -1225,7 +1224,7 @@ export type PickOfTheDay = {
     scheduled_picks?: ScheduledPickSlot[];
     /** Human-readable matchup (e.g. "Portugal vs. Uzbekistan"). */
     matchup?: string;
-    /** Frozen canonical calibration/report bucket (e.g. "Basketball", "MMA", or "Soccer"). Existing semantics are unchanged; presentation consumers should prefer display_category when present. */
+    /** Recorded canonical sport category. Prefer display_category for the public competition label. */
     category?: string;
     /** Frozen public presentation category: the competition the Polymarket event belongs to. A curated label comes first -- an official league (e.g. "WNBA" or "UFC"), the esports title (e.g. "CS2", "LoL", "Dota 2" or "Valorant"), or a soccer competition (e.g. "LaLiga", "Premier League", "Serie A" or "UEFA Champions League"); any other competition carries the provider's own competition name without its season year (e.g. "UEFA Nations League", "ATP" or "Wimbledon"). It equals category only when the provider names no competition. An esports pick keeps the pooled "Esports" bucket in category, so a per-title label never implies a per-title measured cohort. Additive and optional for mixed-version client compatibility. */
     display_category?: string;
@@ -1251,23 +1250,19 @@ 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 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. */
+    /** S/A wallet count on the backed side in the public V1 compatibility projection. */
     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 spelling of sharp_wallet_count with the same value.
      * @deprecated
      */
     smart_wallet_count?: number;
-    /** 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. */
+    /** Best recorded S/A grade in the public V1 compatibility projection. */
     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. Canonical key since #16308; smart_usd is its deprecated spelling, emitted beside it with the same value. */
+    /** Recorded sharp-money magnitude in USD when available. */
     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 spelling of sharp_usd with the same value.
      * @deprecated
      */
     smart_usd?: number;
@@ -1301,67 +1296,40 @@ export type PickOfTheDay = {
     unit_score?: number;
     /** Backend-formatted signed unit score, present exactly when unit_score is present. */
     unit_score_display?: string;
-    /** First-party/internal backed-side sharp-money dollar consensus as a fraction 0..1: the share of current-policy sharp dollars on the backed side. Omitted on current public V1 rows when the B-inclusive value has no reconstructible S/A equivalent. A conviction signal, NOT a probability or expected-value claim. Frozen at generation. */
+    /** Recorded sharp-money share as a 0..1 fraction when available. This is not a winning probability. */
     sharp_pct?: number;
-    /** Market-implied probability of the backed side as a fraction 0..1 (equals backed_price), re-exposed alongside sharp_pct for the WHY breakdown. */
+    /** Recorded market-implied probability as a 0..1 fraction when available. */
     market_pct?: number;
-    /** First-party/internal consensus edge = sharp_pct - market_pct, the conviction-vs-price gap (how much more of the current-policy sharp money sits on this side than the price implies). Omitted on current public V1 rows when the B-inclusive value has no reconstructible S/A equivalent. This is NOT an expected-value or guaranteed edge. Omitted when either input is unavailable. */
-    consensus_edge_pct?: number;
-    /** First-party/internal team-directional commitment read at selection time: the fraction (0..1) of the backed side's current-policy graded sharp-money DOLLARS held by wallets read one-way rather than hedged: no opposite leg on this market worth at least 10% of the backed leg (Polymarket's own currentValue pair), and no opposing team across the game's markets where the wallet's synced legs are fresh. Current public V1 rows omit this B-inclusive read because its historical S/A equivalent is not reconstructed. A high value means the graded pile is really committed to this side; a low one means much of it is hedged or unreadable. Omitted when the read was not computed (a pick selected before the field existed, an ungroupable game, an empty graded pile, or a pile where no holder carried usable evidence) -- which is NOT the same as 0.0, a computed reading that classified holders and found none one-way. */
-    directional_confidence?: number;
-    /** Graded backed-side holders read as one-way-committed on this game. */
-    one_way_holder_count?: number;
-    /** Graded backed-side holders read as HEDGED across the game's markets. */
-    hedged_holder_count?: number;
-    /** The one-way holders' share of the backed-side graded dollars (the confidence's numerator). */
-    one_way_graded_usd?: number;
-    /** Backed-side graded dollars the confidence is measured against (its denominator). */
-    total_graded_usd?: number;
-    /** The qualifying category expert whose sport-specific record and real position earned this pick its top selection tier. The first-party/internal current policy admits S/A/B; public V1 exposes a compatible S/A expert and omits a current-policy B-grade expert: a candidate backed by one outranks every candidate without one. Present only on the full payload. Omitted when no wallet qualified on the backed side, on picks generated before the field existed, and on the first-party web teaser, which withholds all backed-side evidence. Frozen at SELECTION time — the wallet's position can move before the pick renders. */
+    /** Optional recorded specialist facts. These describe the trader and do not disclose selection decisions. Present only on a full response when available. */
     qualifying_expert?: {
-        /** Wallet address of the qualifying expert. */
+        /** Trader wallet address. */
         address: string;
         /** Provider display name, or null for an unnamed wallet. */
         name: string | null;
-        /** 0xinsider grade letter. The first-party/internal current Pick of the Day policy counts S, A, and B; public V1 exposes only the compatible S/A expert. */
+        /** Recorded trader grade. Public V1 preserves its S/A compatibility projection. */
         grade: string | null;
         /** The canonical sport bucket the win rate was measured over (for example Basketball). Can be BROADER than the pick's display_category, which names an exact league such as NBA — label the rate with this field, never with display_category. */
         canonical_category: string;
-        /** Share of this wallet's resolved markets in canonical_category whose realized P&L came out positive, as a 0..1 fraction. Above 0.60 by construction for a source=v1 expert; null for an expert who qualified on the category-skill v2 definition only. Deliberately NOT phrased as "closed profitable": the metric counts realized P&L above zero, so a resolved winner the wallet never redeemed sits at zero and counts against it. */
+        /** Share of the trader’s resolved markets in canonical_category with positive realized P&L, as a 0..1 fraction. Null when not measured. This is a trader statistic, not the pick’s probability of winning. */
         win_rate: number | null;
-        /** Resolved markets in canonical_category behind win_rate. At least 10 by construction for a source=v1 expert; null with win_rate. */
+        /** Number of resolved markets behind win_rate; null when not measured. */
         n_resolved: number | null;
-        /** Current expert policy 10 does not require a category-skill v2 specialist in any sport; in every sport a specialist raises the candidate's rank tier rather than gating it. Standard specialists need a positive edge_lower_95 over enough independent events and enough net backing on the backed side; the floors are not published. Fresh healthy records below the shared model's live sample floor can qualify; stale, unknown and degraded records cannot. Historical records preserve which definition qualified the wallet: v1, the profitability rate (win_rate over n_resolved), or v2, the forward-only category-skill calibration edge (edge_lower_95 over independent_event_count). Absent on picks frozen before the v2 definition existed; read absence as v1. A Tennis pick frozen under gate policy v4 or later carries v2 only: a v1 rate stopped qualifying a tennis expert at v4. A Tennis pick frozen under an earlier policy can still carry v1 with a win rate. */
-        source?: "v1" | "v2";
-        /** 95% lower bound of the wallet's mean calibration edge over the market price in canonical_category, in probability units (0.08 is 8 points). Positive by construction for a v2 expert; present on a v1 expert only when the wallet also holds a live v2 row. */
-        edge_lower_95?: number;
-        /** Point estimate behind edge_lower_95. */
-        edge_mean?: number;
-        /** Independent canonical events behind the edge. At least 10 by construction for a v2 expert. */
-        independent_event_count?: number;
-        /** Polymarket's own currentValue for this wallet on the backed outcome, in USD, as of selection. At least 1000 by construction through gate policy v7; the standard floor is 500 from v8. From gate policy v5 the floor is read on the net: position_usd minus opposite_position_usd is at least that floor, and the pick re-verifies that net against the live holder snapshot when it is released. */
+        /** Recorded Polymarket position value on the backed outcome, in USD. It can change after this snapshot. */
         position_usd: number;
-        /** The same wallet's currentValue on the OTHER outcome of this market, in USD, as of selection. Present from gate policy v5, when the floor moved to net exposure; a wallet long both sides does not qualify. Absent on picks frozen before v5, which never read the leg. 0 is a measured one-way position, not an absence. */
+        /** Recorded position value on the other outcome of this market, in USD. Omitted when not recorded; zero is a measured value. */
         opposite_position_usd?: number;
-        /** When the skill read model behind the evidence was last rebuilt: trader_category_stats.computed_at for a source=v1 expert, category_skill_v2_current.as_of for a source=v2 expert. */
+        /** Timestamp of the recorded trader statistics. */
         stats_computed_at: string;
-        /** Present from expert policy 6. Current expert policy 10 retains the longshot requirement of live v2 only, with a positive lower bound over a large sample, large net backed value and no meaningful opposite value. Historical policy 6: a specialist required large net backed value, no meaningful opposite value, and either a live v2 positive lower bound over a large sample or a high v1 rate over enough resolved markets. Tennis requires v2. The floors are not published. */
-        lane?: "standard" | "longshot_specialist";
-        /** Answered, spread-gated, index-scoped backed probability frozen only on a specialist exception. */
-        lane_probability?: number;
-        /** Canonical provider probability pair branch; absent on standard experts. */
-        lane_probability_source?: "p";
-    };
-    trust?: PickTrust;
-    /** 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. */
+    };
+    /** Public V1 S/A wallet count on the backed side, equal to sharp_wallet_count. */
     traders?: number;
-    /** 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. */
+    /** Recorded backed-side sharp-money value in USD when available. */
     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. */
+    /** Bounded S/A holder display projection. Historical rows retain their recorded display 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. */
+    /** Optional complete holder display roster. Each entry carries ordinary trader and recorded position facts. */
     display_holders?: PickHolder[];
-    /** 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. */
+    /** S/A holder count for the public V1 compatibility projection. display_holders can include additional grades. */
     holder_count?: number;
     /** Optional editorial note attached to the pick. */
     editorial_note?: string;
@@ -1373,17 +1341,15 @@ export type PickOfTheDay = {
     polymarket_url?: string;
     /** The canonical /event game-page slug (one neutral page per game); omitted when the game has no neutral event page. */
     event_slug?: string;
-    /** Backend-resolved /event destination slug for this pick's source market; its absence is an authoritative no-link decision. */
-    event_link_slug?: string;
+    /** Backend-resolved /event destination slug for the source market. Omitted outside full responses; null is an authoritative no-link decision. */
+    event_link_slug?: string | null;
     /** Provider-first sports context for the pick's market (team logos, league branding, live score). Full-state only; omitted when the pick is not a team-sports market. */
     sports_context?: PickSportsContext;
     /** Risk disclaimer shown with every pick. */
     disclaimer?: string;
     /** Published same-day picks whose holder proof is not readable yet, ordered by pick_rank. Additive and optional: present only while at least one such pick exists. While present, `picks` carries only the proof-readable picks and `pick_count` counts them. Schedule the next read from the earliest retry_at instead of polling. The route returns 503 read_model_warming only when no published pick has readable proof. */
     proof_pending_picks?: ProofPendingPickSlot[];
-    /** Frozen admission classification, full payload only. The specialist lane exempts two probability rejects and adds no rank bonus. Historical rows remain standard. */
-    selection_lane?: "standard" | "longshot_specialist";
-    /** Optional full-only authorization for newly issued policy-7 picks; omitted for legacy or unissued picks and teasers. It remains historical after expiry. */
+    /** Optional full-response entry authorization. Missing or expired authorization cannot authorize an automated entry. */
     entry_authorization?: PotdEntryAuthorization;
     /** Stable pick row identity as decimal text. Never use a quality rank as identity. */
     pick_id?: string;
@@ -1795,11 +1761,6 @@ export type PickSportsTeam = {
     /** Completed sets won by this side. Present only when both sides expose the same set columns, so a partially parsed scoreline reports no tally rather than a misleading one. */
     sets_won?: number;
 };
-/** Field-level trust metadata for the full Pick of the Day payload. Present on the full shape only (omitted on the teaser and the no-pick state, because whether a specialist backs the pick is itself backed-side evidence). Unlike TraderTrust it is not gated behind expand=trust: it carries one member on an endpoint that returns a single object per day. */
-export type PickTrust = {
-    /** Provenance of the frozen qualifying category expert. source.kind=database with reconciliation.status=db_mirror means the evidence deserialized, still satisfies every frozen selection gate, and is being served. On that arm freshness.status is always not_live and never fresh, because this evidence is frozen at selection and never refreshed, so on an archived pick the as_of (the expert's own stats_computed_at) can be days or months old by design. source.kind=computed with reconciliation.status=not_applicable means the selector evaluated the backed side and nobody qualified -- a real negative. source.kind=computed with freshness.status=unknown and completeness.status=not_computed means the selector never evaluated this field, as on a pre-feature pick. source.kind=unavailable means the payload is malformed, violates a selection gate, or conflicts with its persisted status, or the public V1 adapter intentionally omitted a current-policy B-grade expert; read the reason before treating it as a negative. Do not read an omitted qualifying_expert as 'no specialist' without checking this field. */
-    qualifying_expert: TrustMetadata;
-};
 export type PlatformCapabilities = {
     grade: PlatformCapabilityStatus;
     pnl: PlatformCapabilityStatus;
@@ -1909,7 +1870,7 @@ export type PositionTimelineEvent = {
     /** Cumulative buy-weighted average of stored fills for this outcome, including older pages; not provider current-position avgPrice. Sells do not change this value. 0 when no stored buys have occurred yet. */
     running_avg_price: number;
 };
-/** Policy-7 issuance binds one condition, selected token, outcome, canonical event and sport. Reuse the same authorization across public/private discovery and retries. Require a new account-size executable book and current market eligibility; this frozen reference does not prove current liquidity or positive expected value. Absence or expiry cannot authorize a new automated entry. */
+/** Returned entry permission bound to the named market, token and outcome. Honor max_entry_price and expires_at, and check a current executable order book for the actual stake. This snapshot does not guarantee current liquidity, execution or positive expected value. */
 export type PotdEntryAuthorization = {
     version: 1;
     authorization_id: string;
@@ -1921,13 +1882,13 @@ export type PotdEntryAuthorization = {
     category: string;
     /** Exact provider parent event ID, or provider event ID when no parent exists. */
     canonical_event_id: string;
-    /** Immutable decimal limit: first fresh selected-token ask plus 0.02, floored to the provider tick below 1. Fees excluded. Never a calibrated fair probability. */
+    /** Returned maximum entry price as an exact decimal string. Honor this bound; fees are excluded. This is not a fair probability. */
     max_entry_price: string;
     reference_best_ask: string;
     reference_book_hash: string;
     reference_book_at: string;
     issued_at: string;
-    /** Original provider kickoff ceiling. Never extended on retry. */
+    /** Authorization expiry. An expired authorization cannot authorize a new automated entry. */
     expires_at: string;
 };
 /** One ranked pre-game sports market where graded sharp money is piled on one side, with required-status shadow category evidence from partial forward-observed Polymarket fills. */
@@ -1936,7 +1897,7 @@ export type PreGameSide = {
     side: string | null;
     /** UTC time at which the snapshot that ranked this row was computed. Canonical spelling of signal_created_at (#16310), same value. */
     ranked_at: string;
-    /** Grade-weighted holders times the share of their money on the side: (5*s + 4*a + 3*b) * sharp_pct. Canonical spelling of conviction_score (#16310), same value. */
+    /** Recorded side backing score; higher values indicate stronger backing. */
     backing_score: number;
     /** Signed share of graded money on the side, (yes_usd - no_usd)/(yes_usd + no_usd) in [-1, 1] (side-yes positive, side-no negative). Canonical spelling of smart_score (#16309, #16310), same value. */
     side_share: number | null;
@@ -1979,7 +1940,7 @@ export type PreGameSide = {
     /** 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). Deprecated (#16310): `side_share` is the canonical spelling and carries the same value; this key stays on the wire.
      * @deprecated
      */
     smart_score: number | null;
@@ -1988,7 +1949,7 @@ export type PreGameSide = {
     /** 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.
+     * Recorded conviction score; higher values indicate stronger conviction.
      * @deprecated
      */
     conviction_score: number;
@@ -2000,7 +1961,7 @@ export type PreGameSide = {
     one_way_graded_usd: number | null;
     /** One-way fraction of the piled graded dollars, in [0, 1] -- the metric orthogonal to sharp_pct. Stale, unknown, hedged, and two-sided dollars dilute it toward zero (conservative). Null when the directional read was not computed or classified nobody. */
     directional_confidence: number | null;
-    /** The ranking key, descending: conviction_score * (1 + 0.25 * directional_confidence). Equals conviction_score when the directional read is null/zero, so signals without the read rank exactly as before. */
+    /** Recorded side ordering score; higher values sort first. */
     directional_rank_score: number;
     category_skill: PreGameSideCategorySkill;
     /** 1-based rank within the (min_grade-filtered) ranked result. */
@@ -2037,7 +1998,7 @@ export type PreGameSideFunnelReport = {
 export type PreGameSideObservation = {
     /** The side profitable wallets hold, as a provider-backed display label. Canonical spelling of piled_side (#16310), same value: when provider group context is unavailable it may remain a bare Yes/No/Over/Under, so do not use it alone as participant identity. */
     side: string | null;
-    /** Grade-weighted holder-pile score before directional enrichment. Canonical spelling of conviction_score (#16310), same value. */
+    /** Recorded side backing score; higher values indicate stronger backing. */
     backing_score: number;
     /** Signed share of graded money on the side, in [-1, 1]. Canonical spelling of smart_score (#16309, #16310), same value. */
     side_share: number;
@@ -2091,7 +2052,7 @@ export type PreGameSideObservation = {
     /** 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.
+     * Recorded conviction score; higher values indicate stronger conviction.
      * @deprecated
      */
     conviction_score: number;
@@ -2107,7 +2068,7 @@ export type PreGameSideObservation = {
     hedged_holder_count: number | null;
     one_way_graded_usd: number | null;
     directional_confidence: number | null;
-    /** Default cohort ordering key: conviction_score * (1 + 0.25 * directional_confidence), or conviction_score when confidence is null. */
+    /** Recorded side ordering score; higher values sort first. */
     directional_rank_score: number;
     /** 1-based rank within this observation cohort and snapshot. */
     rank: number;
@@ -2424,9 +2385,9 @@ 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. */
+    /** Optional forecast score on the documented display scale. Null when unavailable. */
     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. */
+    /** Optional measured forecast context. Missing values remain unavailable rather than being inferred. */
     forecast_evidence?: number;
     rank?: number;
     pnl: {
@@ -2455,11 +2416,11 @@ export type Trader = {
         description?: string;
         confidence?: number;
     };
-    /** Per-category performance breakdown (expand=categories or expand[]=categories). Omitted unless expanded. Object keyed by category name; each value is the precomputed trader_rankings.category_ranks payload (rank, total_in_category, total_pnl, scaled_total_pnl, n_markets, wins, losses, win_rate; scaled_total_pnl is a legacy alias that currently equals total_pnl). RANK BASIS: rank and total_in_category use the same hourly breakpoint publication; categories absent from that publication are omitted until a later publication includes them. Current trader performance values update separately, so this is not a frozen historical record. BASIS: the calibration sample, which admits a position only above a 20 USD notional floor and with a chosen-side entry price strictly inside (0,1), because the ranks and the calibration edge derived from it depend on both rules. That is a different sample from GET /api/v1/trader/{address}/categories, which counts every settled market at any size, and the two differ in both directions. Measured on production 2026-09-22 over the 122,497 wallet-category pairs with at least 20 decided markets on both bases: the floored rate was higher in 56.5% of pairs, lower in 34.5% and equal in 9.0%, median +0.6 points, p10 -4.6, p90 +9.8, and 14.0% of pairs differ by 10 points or more. The difference is not only small positions: on a 1-in-250 wallet sample the same day, admitted markets won 56.6% while markets dropped by the notional floor alone won 45.2% and markets dropped by the entry-price rule alone won 48.7%. n_markets counts every admitted market including the ones that resolved at exactly zero P&L, so it is not the denominator of win_rate: it differed from wins + losses in 15.8% of pairs with at least 5 decided markets. The two tables also run on different clocks, this one updated incrementally and that route rebuilt daily, so a same-day read can differ on timing alone. Use this for rank context and that route for the wallet's plain record. Pass-through DB JSON: keys and value shape are DB-owned, so the inner shape is intentionally unconstrained and may carry additional compatibility fields. */
+    /** Per-category rank context when expand=categories is requested. Values include available rank, category totals, performance and record counts; scaled_total_pnl is a legacy alias of total_pnl. Its measurement basis and update timing differ from the plain record returned by GET /api/v1/trader/{address}/categories, so the two need not agree. Use this for rank context and that route for the plain record. The inner key-set is intentionally unconstrained and may contain additional compatibility fields. */
     category_strengths?: Record<string, unknown>;
     /** Curated advanced risk/performance metrics (expand=quant_metrics or expand[]=quant_metrics). Omitted unless expanded and backed by a computed row strictly under six hours old; a missing row, NULL computed_at, or age of exactly six hours or more is stale and omitted. Provider-input changes may intentionally lag inside the bounded six-hour window. When present, all listed fields are present (each is a number or null); null means insufficient trade history and must not be treated as 0. The fixed field shape is unchanged. */
     quant_metrics?: {
-        /** Composite skill score, 0-100. smart_score = clamp(0, 100, 30*sharpe_percentile_fraction + 20*profit_factor_percentile_fraction + 20*edge_consistency_percentile_fraction + 10*min(1, return_on_capital/2) + 10*equity_smoothness + 10*(1 - min(1, asset_concentration))). Higher is better. null when insufficient history. */
+        /** Trader smart score on a 0..100 display scale; higher is stronger. Null when unavailable. */
         smart_score: number | null;
         /** Copyability score, 0-100. Same base as smart_score minus penalties for traits that make a strategy hard to replicate: -20 if fewer than 50 markets traded, -15 if positions are highly concentrated, -15 if position sizing exceeds about 2x Kelly, -10 if the worst single-trade loss exceeds 30%, -10 if edge is inconsistent; result clamped to 0-100. Higher means easier to follow. null when insufficient history. */
         copy_score: number | null;