---
title: "Biggest resolved-market surprises (\"flips\")"
method: GET
path: "/api/prediction-markets/surprises"
tags: ["public-pm-data"]
---

# Biggest resolved-market surprises ("flips")

`GET /api/prediction-markets/surprises`

## Request

- Base URL: `https://api.coinrithm.com`
- URL: `https://api.coinrithm.com/api/prediction-markets/surprises`
- Auth: none required

Keyless "surprise index": resolved BINARY (exactly two outcomes)
markets whose eventual winner was priced under 50 (of 100) roughly 24
hours before settlement, ordered by the lowest T-24h winner
probability first. Only provider-resolution-basis events qualify;
multi-strike ladder markets are excluded because their non-leading
strikes are structurally near zero and are not a real surprise
signal. Same resolvedAt/closedAt honesty rule as `/resolved`:
`resolvedAt` is populated only when provider-verified.

`surprise.t24hProbability` and `surprise.t7dProbability` are the
WINNING outcome's probability, 0-100 points, at T-24h and T-7d before
resolution. `t7dProbability` is frequently null — not every market
has 7 days of pre-resolution history.

## Query parameters

- `limit` integer
- `offset` integer
- `fiat` string
- `source` 'polymarket' | 'kalshi' | 'rothera' | 'limitless' | 'smarkets' | 'manifold' | 'metaculus' | 'predictit' | 'futuur' | 'myriad' | 'forecastex' | 'gemini'
- `window` '7d' | '30d' | '90d' | 'all'

## Response `200`

Paginated surprise-index rows

- PublicPmSurprisesResponse
  - `data` PublicPmSurpriseEntry[], required
    - `event` PublicPmEvent, required
      - `id` string, required
      - `slug` string, required
      - `title` string, required
      - `marketSubtitle` string: Kalshi single-market (Yes/No) events only: the contract's subject as the venue labels it, e.g. "Over 2.5 maps" under the title "... : Total Maps". Yes and No resolve against this line. Absent when the venue gives none, when it is just "Yes", and on every other event; the Yes/No outcome names and the title are unchanged.
      - `description` string, nullable
      - `status` string, required
      - `startDate` string, date-time, nullable
      - `endDate` string, date-time, nullable
      - `resolvedAt` string, date-time, nullable
      - `resolvedOutcomeExternalMarketId` string, nullable
      - `resolutionOutcomeBasis` string, nullable
      - `freshness` object: Observation time, age and source-aware freshness state.
      - `volume` number, nullable
      - `volume24h` number, nullable
      - `liquidity` number, nullable
      - `openInterestUsd` number: Event detail only (full and `view=core`): open interest in USD, whatever `fiat` was requested. Omitted when the venue publishes none; never a fabricated 0. On Kalshi it is the same amount the venue's `liquidity` carries.
      - `openInterestBasis` 'venue_reported_usd' | 'contracts_x_notional_usd': How `openInterestUsd` was measured. `venue_reported_usd`: the venue's own event figure (Polymarket, Rothera). `contracts_x_notional_usd`: open contracts times each contract's USD notional, summed over the event's markets (Kalshi).
      - `openInterestBasisNote` string: Short human-readable description of `openInterestBasis`.
      - `bestBid` number, nullable
      - `bestAsk` number, nullable
      - `spread` number, nullable
      - `source` PublicPmSource, required
        - `id` 'polymarket' | 'kalshi' | 'rothera' | 'limitless' | 'smarkets' | 'manifold' | 'metaculus' | 'predictit' | 'futuur' | 'myriad' | 'forecastex' | 'gemini', required
        - `name` string, required
        - `kind` string
        - `supportsTrading` boolean
      - `priceChange24h` number, nullable: Signed event-level probability change in percentage points (-100 to +100; probabilities are 0 to 100), not a fraction or relative percent change. The representative contract or outcome and nominal 24h lookback basis vary by venue; this need not be the displayed leader or largest outcome move. The lookback may be a previous-session close or an observed-window span rather than exactly 24 hours. Use outcome.priceChange24h for a named outcome's change. Null means unavailable.
      - `priceChange7d` number, nullable: Signed event-level probability change over the venue's available seven-day lookback, in percentage points (-100 to +100; probabilities are 0 to 100), not a fraction or relative percent change. The representative contract or outcome varies by venue; this need not be the displayed leader or largest outcome move. Null means unavailable.
      - `probabilityBook` object, nullable: Book-level probability basis: `basis` is `normalized_complete_book` when outcomes carry normalizedProbability (with `rawSum` and `overroundPoints`), else `raw_quotes`.
      - `outcomes` PublicPmOutcome[], required
        - `externalMarketId` string
        - `name` string, required
        - `openInterestUsd` number: Event detail, Kalshi multi-market events only (also on `representativeOutcome`). This contract's open interest in USD (open contracts times USD notional). Omitted elsewhere.
        - `probability` number, nullable: Provider-implied probability on a 0–100 scale (raw venue input; may include vig, so a book's outcomes can sum above 100). Execution eligibility and a usable quote are reported by the quote endpoint, not inferred from this field alone.
        - `normalizedProbability` number, nullable: Vig-removed display probability on a 0–100 scale, proportionally normalized so a complete exclusive book sums to ~100. Null when the book is not a complete exclusive book (threshold ladders, partial catalogs, non-market sources). This is display context, not an execution quote.
        - `hasObservedPrice` boolean: Optional source-data truth flag. `true` means a supported source observation validated a usable observed price, including numeric 0; `false` is emitted only for the Rothera explicit writer-null marker and means no usable observed price input. Omitted means unknown, legacy, or unsupported source data. This flag does not claim live pricing, liquidity, or tradability.
        - `priceBasis` string: Polymarket and Kalshi open outcomes only: what `probability` is. `unquoted` means never traded and no usable book, so `probability` is not a price (a Polymarket wide-book midpoint such as 48 on a 3/93 book, or a stored 0 on Kalshi). `book_mid` is the order-book midpoint (Polymarket: a spread of 10 points or less; Kalshi: the venue's quote midpoint). `last_trade` is the last traded price (Polymarket uses it when the book is wider than 10 points). Absent on other venues, on settled outcomes and on responses served before 2026-09-29. Like `hasObservedPrice`, it is not an execution quote; use the quote endpoint for tradability. A plain string, so a basis added later cannot break older clients: treat an unknown value as unknown.
        - `sourceObservation` object, nullable: Optional bounded provenance for the stored outcome price. Null means the supported source marker was unavailable or explicitly null; it does not prove that the outcome has no price. Timestamps describe source evidence, not current freshness or executable liquidity.
          - `version` integer, required: Source-observation schema version; currently 1.
          - `basis` 'provider_quote' | 'provider_trade' | 'daily_clearing_mark' | 'clearing_settlement' | 'last_price_untimed', required
          - `provider` 'robinhood' | 'forecastex' | 'rothera', required
          - `observedAt` string, date-time, nullable
          - `tradeDate` string, date, nullable
        - `priceChange24h` number, nullable: Signed outcome probability change in percentage points (-100 to +100; probabilities are 0 to 100), not a fraction or relative percent change. For example, 20% to 25.5% is +5.5 points. The nominal 24h field follows the venue's available lookback basis, which may be a previous-session close or an observed-window span rather than exactly 24 hours. Null means unavailable.
        - `lifecycle` object, nullable: Per-outcome provider lifecycle evidence. Terminal states are results, not live quotes; an open state with providerAcceptingOrders=false is a paused quote.
          - `state` 'open' | 'closed' | 'resolved' | 'voided' | 'unknown'
          - `providerAcceptingOrders` boolean, nullable
          - `entryBlockedByLifecycle` boolean
          - `isResult` boolean
          - `result` 'won' | 'lost' | 'voided' | 'null', nullable
          - `basis` 'provider' | 'stored_winner' | 'unknown'
          - `closedAt` string, date-time, nullable
          - `resolvedAt` string, date-time, nullable
          - `observedAt` string, date-time, nullable
        - `priorProbability` object, nullable: Last stored provider quote before the outcome closed, when available.
          - `value` number
          - `asOf` string, date-time
          - `cutoff` string, date-time
        - `venueTerms` object: Venue-published order and settlement terms; null values mean unavailable, unreported, or invalid.
          - `orderMinSize` number, nullable, required: Polymarket minimum order size in shares.
          - `tickSize` number, nullable, required: Polymarket minimum probability increment as a ratio.
          - `feesEnabled` boolean, nullable, required: Polymarket market fee flag.
          - `canCloseEarly` boolean, nullable, required: Kalshi early-close capability.
          - `settlementTimerSeconds` integer, nullable, required: Kalshi venue-published settlement timer in seconds; not a guaranteed deadline after close.
        - `quoteEvidence` object, nullable: Present only when the request sent `includeQuoteEvidence=1`. The stored venue book observation for Polymarket and Kalshi outcomes on a 0-100 scale (values outside 0-100 are served as null); null for other venues or when none is stored. Not an executable quote.
          - `version` integer
          - `bid` number, nullable
          - `ask` number, nullable
          - `last` number, nullable
      - `representativeOutcome` PublicPmOutcome
        - `externalMarketId` string
        - `name` string, required
        - `openInterestUsd` number: Event detail, Kalshi multi-market events only (also on `representativeOutcome`). This contract's open interest in USD (open contracts times USD notional). Omitted elsewhere.
        - `probability` number, nullable: Provider-implied probability on a 0–100 scale (raw venue input; may include vig, so a book's outcomes can sum above 100). Execution eligibility and a usable quote are reported by the quote endpoint, not inferred from this field alone.
        - `normalizedProbability` number, nullable: Vig-removed display probability on a 0–100 scale, proportionally normalized so a complete exclusive book sums to ~100. Null when the book is not a complete exclusive book (threshold ladders, partial catalogs, non-market sources). This is display context, not an execution quote.
        - `hasObservedPrice` boolean: Optional source-data truth flag. `true` means a supported source observation validated a usable observed price, including numeric 0; `false` is emitted only for the Rothera explicit writer-null marker and means no usable observed price input. Omitted means unknown, legacy, or unsupported source data. This flag does not claim live pricing, liquidity, or tradability.
        - `priceBasis` string: Polymarket and Kalshi open outcomes only: what `probability` is. `unquoted` means never traded and no usable book, so `probability` is not a price (a Polymarket wide-book midpoint such as 48 on a 3/93 book, or a stored 0 on Kalshi). `book_mid` is the order-book midpoint (Polymarket: a spread of 10 points or less; Kalshi: the venue's quote midpoint). `last_trade` is the last traded price (Polymarket uses it when the book is wider than 10 points). Absent on other venues, on settled outcomes and on responses served before 2026-09-29. Like `hasObservedPrice`, it is not an execution quote; use the quote endpoint for tradability. A plain string, so a basis added later cannot break older clients: treat an unknown value as unknown.
        - `sourceObservation` object, nullable: Optional bounded provenance for the stored outcome price. Null means the supported source marker was unavailable or explicitly null; it does not prove that the outcome has no price. Timestamps describe source evidence, not current freshness or executable liquidity.
          - `version` integer, required: Source-observation schema version; currently 1.
          - `basis` 'provider_quote' | 'provider_trade' | 'daily_clearing_mark' | 'clearing_settlement' | 'last_price_untimed', required
          - `provider` 'robinhood' | 'forecastex' | 'rothera', required
          - `observedAt` string, date-time, nullable
          - `tradeDate` string, date, nullable
        - `priceChange24h` number, nullable: Signed outcome probability change in percentage points (-100 to +100; probabilities are 0 to 100), not a fraction or relative percent change. For example, 20% to 25.5% is +5.5 points. The nominal 24h field follows the venue's available lookback basis, which may be a previous-session close or an observed-window span rather than exactly 24 hours. Null means unavailable.
        - `lifecycle` object, nullable: Per-outcome provider lifecycle evidence. Terminal states are results, not live quotes; an open state with providerAcceptingOrders=false is a paused quote.
          - `state` 'open' | 'closed' | 'resolved' | 'voided' | 'unknown'
          - `providerAcceptingOrders` boolean, nullable
          - `entryBlockedByLifecycle` boolean
          - `isResult` boolean
          - `result` 'won' | 'lost' | 'voided' | 'null', nullable
          - `basis` 'provider' | 'stored_winner' | 'unknown'
          - `closedAt` string, date-time, nullable
          - `resolvedAt` string, date-time, nullable
          - `observedAt` string, date-time, nullable
        - `priorProbability` object, nullable: Last stored provider quote before the outcome closed, when available.
          - `value` number
          - `asOf` string, date-time
          - `cutoff` string, date-time
        - `venueTerms` object: Venue-published order and settlement terms; null values mean unavailable, unreported, or invalid.
          - `orderMinSize` number, nullable, required: Polymarket minimum order size in shares.
          - `tickSize` number, nullable, required: Polymarket minimum probability increment as a ratio.
          - `feesEnabled` boolean, nullable, required: Polymarket market fee flag.
          - `canCloseEarly` boolean, nullable, required: Kalshi early-close capability.
          - `settlementTimerSeconds` integer, nullable, required: Kalshi venue-published settlement timer in seconds; not a guaranteed deadline after close.
        - `quoteEvidence` object, nullable: Present only when the request sent `includeQuoteEvidence=1`. The stored venue book observation for Polymarket and Kalshi outcomes on a 0-100 scale (values outside 0-100 are served as null); null for other venues or when none is stored. Not an executable quote.
          - `version` integer
          - `bid` number, nullable
          - `ask` number, nullable
          - `last` number, nullable
      - `representativeOutcomeBasis` 'threshold_ladder_line' | 'informative_leader': Event detail only, open events only: the rule that chose representativeOutcome. `threshold_ladder_line` is a threshold ladder's line nearest 50% (a Kalshi strike ladder). `informative_leader` is the highest current outcome strictly inside 5-95, else the highest; it is not necessarily the leading outcome.
      - `referenceProbability` object, nullable: Canonical matched-venue reference with venue count and spread. Also carries `methodologyVersion` (the row's own writer version: `consensus_probability_v2` or `consensus_probability_v3`) and `weightBasis` (`open_interest` | `liquidity`, null for a v3 row without a recognised basis); see the consensus-methodology endpoint.
      - `decisionSupport` object, nullable
      - `quality` object, nullable: Persisted truth-engine decision eligibility and reason codes.
      - `crossPlatform` object[]
      - `outcomesTotal` integer: Full outcome count when the outcome list was trimmed (`view=compact`, or matched/related events without `full=1`).
      - `availability` object: Event detail only, and only for an open event whose venue CoinRithm has paused: its prices stopped updating at `lastCollectedAt`. Absent otherwise.
        - `status` 'paused', required
        - `lastCollectedAt` string, date-time, nullable, required
    - `resolvedAt` string, date-time, nullable: Provider-verified resolution time. Null when not provider-verified; see resolvedAtVerified.
    - `resolvedAtVerified` boolean, required
    - `closedAt` string, date-time, nullable
    - `resolutionOutcome` PublicPmResolutionOutcome, required: The winning outcome as recorded at resolution.
      - `externalMarketId` string, required
      - `name` string, required
      - `probability` number, required: The winning outcome's provider-implied probability on a 0-100 scale, as last recorded.
      - `basis` string, required: How the winner was determined. Currently `source` (the venue's own resolved-outcome marker matched a stored outcome) or `final_probability` (no venue marker, but exactly one outcome closed at >=99.5). A plain string: treat an unknown value as unknown.
    - `surprise` object, required
      - `t24hProbability` number, required: Winning outcome's probability (0-100) roughly 24h before resolution.
      - `t7dProbability` number, nullable, required: Winning outcome's probability (0-100) roughly 7 days before resolution; frequently null.
  - `window` string, required: The window applied, echoed from the request (`7d`, `30d`, `90d` or `all`; unknown requests are served as `all`).
  - `pagination` PublicPmPagination, required
    - `limit` integer, required
    - `offset` integer, required
    - `hasMore` boolean, required

## Other responses

- `400`: Invalid or missing parameters. On a route with a query allowlist, an undocumented query parameter returns `{"error": "unsupported_query_parameter", "message": "Unsupported query parameter: <key>. Supported: <keys>."}`.
- `500`: Server error

---

[API](https://skmtc.dev/coinrithm/apis/coinrithm-agent-trading-api.md) · [All operations](https://skmtc.dev/coinrithm/apis/coinrithm-agent-trading-api/llms.txt) · [OpenAPI document](https://skmtc.dev/coinrithm/apis/coinrithm-agent-trading-api/revisions/28fb59f285fe?raw)