> ## Documentation Index
> Fetch the complete documentation index at: https://coinstats.app/api-docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Markets & Events

> List, filter, price, and cross-match Polymarket, Kalshi and Polymarket US markets and events.

A **market** is a single tradable question with outcomes (usually `Yes`/`No`) and a price per outcome in `0..1`. An **event** groups related markets — for example a presidential election event holds one market per candidate.

## Markets

> **[List markets](/api-docs/api-docs/openapi/list-markets)**
>
> Paginate and filter by `active`, `eventId`, `source`; sort by volume, liquidity, or end date.

> **[Trending markets](/api-docs/api-docs/openapi/trending-markets)**
>
> Top markets by 24h volume.

> **[Get a market](/api-docs/api-docs/openapi/get-market)**
>
> Full market detail by `slug`.

> **[Current prices](/api-docs/api-docs/openapi/market-prices)**
>
> Best bid/ask, midpoint, and spread per outcome.

> **[Order book](/api-docs/api-docs/openapi/market-orderbook)**
>
> Full CLOB depth for both outcomes, best-first, live from the venue.

> **[Price history](/api-docs/api-docs/openapi/market-price-history)**
>
> Yes-price time series over `1h`…`max` intervals.

> **[OHLC candles](/api-docs/api-docs/openapi/market-bars)**
>
> OHLC bars for the Yes outcome at your chosen interval/fidelity.

> **[Price at time](/api-docs/api-docs/openapi/market-price-at)**
>
> The last Yes price at or before a given timestamp (no interpolation).

> **[Cross-venue match](/api-docs/api-docs/openapi/market-cross-venue)**
>
> The matching market on the other venue (Kalshi ↔ Polymarket), with a confidence score and price delta.

```bash theme={null}
# Active markets, richest first
curl "https://api.coinstats.app/v1/prediction/markets?active=true&sort=volume24hr&limit=20" \
  -H "X-API-KEY: YOUR_API_KEY"
```

## Events

> **[List events](/api-docs/api-docs/openapi/list-events)**
>
> Filter by `active`, `closed`, `source`; sort by volume or end date.

> **[Trending events](/api-docs/api-docs/openapi/trending-events)**
>
> Top events by 24h volume.

> **[Get an event](/api-docs/api-docs/openapi/get-event)**
>
> Event detail including its child markets.

> **[Cross-venue matches](/api-docs/api-docs/openapi/event-cross-venue)**
>
> Every child market's counterpart on the other venue (Kalshi ↔ Polymarket) in one call.

```bash theme={null}
# Top events right now
curl "https://api.coinstats.app/v1/prediction/events/trending?limit=10" \
  -H "X-API-KEY: YOUR_API_KEY"
```

## Venues and views

Three venues, told apart by the `source` field every item carries:

| `source` | Venue | Slugs |
| - | - | - |
| `polymarket` | Polymarket (international exchange, polymarket.com) | as on Polymarket |
| `kalshi` | Kalshi | `kalshi-…` |
| `polymarket-us` | Polymarket US (the CFTC-regulated exchange for US residents, polymarket.us) | `polymarket-us-…` |

Polymarket's two exchanges list mostly the same questions. The market and event lists, trending and search take `view` to pick the venues:

* `intl` (default) — Polymarket and Kalshi, exactly as before Polymarket US was added.
* `us` — Polymarket US and Kalshi, for a reader in the US.
* `all` — every venue.

In `all`, **events** are listed once each (event lists, trending events and the events of a search): a Polymarket US event linked to its Polymarket twin is listed as the twin's row. On event lists and trending events that row names it in `linkedEvent`; a search's row does not. **Markets** are not deduplicated: a market list, trending markets and the markets of a search can return the same question from both of Polymarket's exchanges, told apart by `source`.

`source` picks one venue instead. On market lists `view` is then ignored; on event lists it no longer picks the rows but still picks which venues' pairs annotate them (`pairedEvents`, `venueCount`). An event's detail (`/events/{slug}`) takes `view` for the same annotations of the event and its child markets; omitted, it is the event's own (`us` for a Polymarket US event, `intl` otherwise). Any other `view` is a `400`.

```bash theme={null}
# Polymarket US markets, by lifetime volume
curl "https://api.coinstats.app/v1/prediction/markets?source=polymarket-us&sort=volume&limit=20" \
  -H "X-API-KEY: YOUR_API_KEY"

# Events on every venue
curl "https://api.coinstats.app/v1/prediction/events?view=all&limit=20" \
  -H "X-API-KEY: YOUR_API_KEY"
```

> [!NOTE]
>
> **Polymarket US specifics:** it publishes no 24-hour volume, so its rows carry `volume24hr: 0` and a lifetime `volume` — sort a US list by `volume`. Its rows carry no link: a Polymarket US event's page is `https://polymarket.us/event/{slug without the polymarket-us- prefix}`, and a market's is its event's (`eventSlug`). Order book and trader data are Polymarket (international) only; prices, price history and candles work for every venue. The platform overview (`/analytics/overview`) counts Polymarket and Kalshi only and takes `source=polymarket|kalshi`.

> [!NOTE]
>
> **Cross-venue match:** use the cross-venue endpoints to compare the same question across both books. The response returns the counterpart market(s), a `confidence` score (`0..1`), and `delta` (current Yes minus the matched venue's Yes) — the basis for spotting arbitrage/pricing gaps. `match` is `null` (with a `reason`) when the market is not in a curated group or no confident counterpart exists.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.