---
title: "List prediction markets"
method: GET
path: "/v4/data/prediction/markets"
tags: ["Prediction API"]
---

# List prediction markets

`GET /v4/data/prediction/markets`

/v4/data/prediction/markets

**100 credits per API call**

List prediction markets across supported platforms. A market is a single binary or multi-outcome question (e.g. "Will candidate X win?"); it belongs to a parent event when one is defined upstream. Each row carries pricing-friendly roll-ups (volume, liquidity), the current outcome set, and on-chain references on platforms where they exist.

Supported platforms (filter via `platform` or omit for a cross-platform feed):

*   Polymarket — `polymarket`
*   Kalshi — `kalshi`

**Filtering, sorting and pagination**

*   The `status`, `category`, `tag`, `search` and `minVolume` filters are only honoured by Polymarket. To use any of them you must also pin `platform=polymarket` — calling them without that pin returns `400`.
*   `eventId` accepts either a Polymarket numeric event id or a Kalshi event ticker. When omitted, results span all events on the targeted platform(s).
*   `endingBefore` is an ISO-8601 timestamp; markets closing on or after that timestamp are excluded.
*   `sort` accepts `volume_desc`, `liquidity_desc`, `endingSoon`, `newest`. When omitted on a cross-platform feed, results are interleaved between the two platforms.
*   Pagination is cursor-based. The first call returns a `pagination.cursor`; pass it back verbatim as `?cursor=…` on the next call. Cursors are opaque, fingerprint-bound, and expire when filters change — never construct or modify them by hand.

**Other notes**

*   `volumeUnit` is `usd` on Polymarket (dollar-denominated notional) and `contracts` on Kalshi (contract count — not USD).
*   `liquidity` is `null` on Kalshi — quoted liquidity is not exposed by the upstream markets feed; aggregate orderbook depth client-side if you need it.
*   `chain` is populated for Polymarket markets (Polygon CTF) and `null` on Kalshi which has no on-chain footprint.
*   `status` in the response is the verbatim upstream status string (richer than the `?status=` filter enum) — values can include `paused`, `archived`, `settled`, etc.

## Query parameters

- `platform` 'polymarket' | 'kalshi' — Prediction-market platform identifier.
- `status` 'active' | 'closed' | 'resolved' — Coarse lifecycle filter used by the `?status=` query parameter. The response field `status` carries a richer, platform-native string (e.g. `paused`, `archived`, `settled`); this enum is used only for filtering.
- `category` string
- `tag` string
- `eventId` string
- `search` string
- `endingBefore` string, date-time
- `minVolume` number
- `sort` 'volume_desc' | 'liquidity_desc' | 'endingSoon' | 'newest' — Sort order for event and market listings. When omitted on a cross-platform feed, results are interleaved between platforms instead.
- `cursor` string — Opaque base64-encoded pagination token. Returned in `pagination.cursor` on responses that have more pages. Pass back verbatim as `?cursor=…` to fetch the next page. Cursors are fingerprint-bound to the filter set — modifying any filter between calls invalidates the cursor and returns `400`. The field is omitted from `pagination` on the last page.
- `limit` integer

## Response `200`

OK

- PredictionMarketsListResponse — Paginated list of prediction markets.
  - `data` PredictionMarket[], required
    - `id` string, required — Platform-native market identifier (Polymarket condition id or Kalshi market ticker).
    - `platform` 'polymarket' | 'kalshi', required — Prediction-market platform identifier.
    - `eventId` string, nullable, required — Parent event id. Polymarket numeric event id, or Kalshi event ticker. `null` when the upstream does not group this market under an event.
    - `question` string, required — Human-readable market question.
    - `description` string, nullable, required — Long-form description or resolution rules.
    - `category` string, nullable, required — Category label, when available.
    - `tags` string[], required — Free-form tag slugs. May be empty on Kalshi.
    - `imageUrl` string, nullable, required — Image / icon URL for the market, when available.
    - `status` string, required — Verbatim upstream status string. Richer than the `?status=` filter enum — values can include `paused`, `archived`, `settled`, `determined`, etc.
    - `openTime` string, date-time, nullable, required — ISO-8601 timestamp the market opened for trading.
    - `closeTime` string, date-time, nullable, required — ISO-8601 timestamp the market closes / closed for trading.
    - `settleTime` string, date-time, nullable, required — ISO-8601 timestamp the market is expected to settle.
    - `outcomes` PredictionMarketOutcome[], required — All outcomes of the market.
      - `name` string, required — Outcome label.
      - `price` number, required — Current probability in [0, 1].
      - `tokenId` string, nullable, required — Polymarket CTF token id for this outcome (numeric string). `null` on Kalshi — Kalshi outcomes are not tokenised.
    - `volume` number, required — Total volume in `volumeUnit` units.
    - `volumeUnit` 'usd' | 'contracts', required — Unit for `volume` and `totalVolume` fields. `usd` on Polymarket (dollar-denominated notional); `contracts` on Kalshi (contract count — not USD).
    - `liquidity` number, nullable, required — Quoted-resting-orders depth. `null` on Kalshi — the upstream markets feed does not populate this; aggregate orderbook depth client-side if you need it.
    - `resolution` PredictionMarketResolution, required — Resolution payload populated only after a market has settled. `null` on every active or paused market.
      - `outcome` string, required — Winning outcome name (matches one of the market's `outcomes[].name`).
      - `resolvedAt` string, date-time, required — ISO-8601 timestamp the market was resolved at.
      - `txHash` string, nullable, required — On-chain resolution transaction hash when available. `null` on Kalshi (the resolution is recorded off-chain on Kalshi's side).
      - `source` string, nullable, required — Resolution source attribution (e.g. `uma`, `kalshi`). `null` when the upstream does not expose it.
    - `createdAt` string, date-time, nullable, required — ISO-8601 timestamp the market was created upstream.
    - `source` PredictionMarketSource, required — Upstream platform attribution for a market or event row.
      - `platform` 'polymarket' | 'kalshi', required — Prediction-market platform identifier.
      - `platformId` string, required — Platform-native identifier. Polymarket condition id (0x + 64 hex) or numeric event id; Kalshi market or event ticker.
      - `url` string, required — Canonical public URL on the source platform.
    - `chain` PredictionMarketChain, required — On-chain references for a market. Populated for Polymarket (Polygon CTF); `null` on Kalshi which has no on-chain footprint.
      - `chainId` integer, required — EVM chain id (Polymarket runs on Polygon — chainId 137).
      - `conditionId` string, nullable, required — CTF condition id (0x + 64 hex).
      - `tokenIds` object, nullable, required — Outcome token ids keyed by outcome name.
        - `yes` string, nullable
        - `no` string, nullable
      - `resolutionSource` string, nullable, required — Resolution-source URL or identifier (UMA on Polymarket).
  - `pagination` PredictionCursorPagination, required — Cursor-based pagination wrapper. The `cursor` field is omitted on the last page; `pageSize` reflects the page size of the call that produced this response.
    - `cursor` string — Opaque base64-encoded pagination token. Returned in `pagination.cursor` on responses that have more pages. Pass back verbatim as `?cursor=…` to fetch the next page. Cursors are fingerprint-bound to the filter set — modifying any filter between calls invalidates the cursor and returns `400`. The field is omitted from `pagination` on the last page.
    - `pageSize` integer, required — Page size of the page that produced this response.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized. Not valid or inactive subscription key present in the HTTP Header.
- `403` — Forbidden. The request is authenticated, but it is not possible to perform the operation due to logical error or invalid permissions.
- `500` — Internal server error. There was an error on the server during the processing of the request.

---

[API](https://skmtc.net/tatum/apis/blockchain-data.md) · [All operations](https://skmtc.net/tatum/apis/blockchain-data/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tatum/blockchain-data/versions/8622ee4b8fae/schema)