---
title: "Search events across all prediction-market venues"
method: GET
path: "/api/prediction-markets/events"
tags: ["public-pm-data"]
---

# Search events across all prediction-market venues

`GET /api/prediction-markets/events`

## Request

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

Keyless event search across Polymarket, Kalshi, Rothera, Limitless,
Smarkets, Manifold, Metaculus, PredictIt, Futuur, Myriad, ForecastEx
and Gemini. Results remain visible when quality-blocked; inspect
`quality` and `decisionSupport` before using a row for a decision. This
research endpoint is broader than the authenticated paper-trading
discovery API.

Open events of a venue CoinRithm has paused (no longer collecting) are
left out of this list, the overview, expiring and matches surfaces;
their closed and resolved history stays available. `pagination` reports
`limit`, `offset` and `hasMore`.

Opt-ins (absent means the default shape): `view=compact` keeps each
event's top 3 outcomes by probability, adds `outcomesTotal` and drops
`description`; `lead=representative` (with `view=compact` only) adds
`representativeOutcome` on open events; `dedupe=matched` keeps only the
highest-ranked member of each approved cross-venue match group on the
page (a page can then hold fewer than `limit` rows); `minVolume24h`
keeps events with at least that 24h USD volume;
`includeQuoteEvidence=1` adds `quoteEvidence` to every outcome.

An unknown query parameter returns `400` with a message naming the
supported parameters.

## Query parameters

- `limit` integer
- `offset` integer
- `q` string
- `tag` string
- `status` string
- `source` 'polymarket' | 'kalshi' | 'rothera' | 'limitless' | 'smarkets' | 'manifold' | 'metaculus' | 'predictit' | 'futuur' | 'myriad' | 'forecastex' | 'gemini'
- `sort` 'best' | 'volume24h_desc' | 'priceChange24h_desc' | 'priceChange24h_asc' | 'endDate_desc' | 'trending'
- `tradeable` boolean
- `fiat` string
- `view` 'compact'
- `lead` 'representative'
- `dedupe` 'matched'
- `minVolume24h` number
- `includeQuoteEvidence` '1'

## Response `200`

Paginated provider-rich event records

- PublicPmEventsResponse
  - `data` 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
  - `pagination` object, required
    - `total` integer: Never sent by the server; use `hasMore`.
    - `limit` integer
    - `offset` integer
    - `hasMore` boolean
  - `meta` object

## 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)