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

# Prediction Markets

> Read-only analytics for Polymarket, Kalshi and Polymarket US prediction markets — markets, events, cross-venue matching, traders, per-trader PnL, search, and platform analytics. One API key, one integration.

Prediction markets let people trade on the outcome of real-world events — elections, sports, macro prints, crypto price levels — where each market's price *is* the crowd's probability of "Yes". CoinStats puts **Polymarket**, **Kalshi** and **Polymarket US** behind one read-only API: consistent shapes, one auth scheme, cross-venue matching, and deep per-trader analytics.

> [!NOTE]
>
> **Base path:**`https://api.coinstats.app/v1/prediction/*` · `X-API-KEY` auth on every endpoint. Browse the full schema and try-it console under the **Prediction ·** groups (Markets, Events, Traders, Analytics, Search) in the [API reference](/api-docs/api-docs/openapi/list-markets).

The deepest coverage is on **traders** — leaderboards plus full per-trader analytics (PnL, positions, category stats, score). Markets, events, and platform analytics give you the surrounding context.

## What you get

* **Markets & events** — list, filter, and sort live and resolved markets across the venues (`source=polymarket|kalshi|polymarket-us`, or `view=intl|us|all`; see [Venues and views](/api-docs/api-docs/prediction/markets-and-events#venues-and-views)); events group related markets (e.g. every candidate in an election).
* **Cross-venue matching** — the counterpart market on the other venue with a confidence score and price delta, for a single market or a whole event.
* **Prices & history** — current order-book prices and Yes-price time series.
* **Traders** — a leaderboard plus deep per-trader analytics: positions, trade history, daily PnL history, category stats, and a composite score.
* **Platform analytics** — overview stats and composite market signals (whale + smart-money) with a buy/sell recommendation.
* **Search** — search across events, markets, and traders.

## Conventions

Every endpoint shares one response envelope, so you can write one client and reuse it across all the operations.

* **Success:** `{ "success": true, ...payload, "timestamp": "<ISO 8601>" }`. List endpoints add a `meta` object for pagination (`total`, `limit`, `offset`, `hasMore`).
* **Error:** `{ "success": false, "error": { "message": "...", "status": <code> } }`.
* **Prices** are probabilities in `0..1`. **Money** is USD. **Dates** are ISO 8601 strings.
* **Identifiers:** use the domain keys — `slug` (markets/events), `conditionId` (markets), `walletAddress` (traders), `tagId` (tags). Mongo internals (`_id`, `__v`) are stripped.

## Authentication

Pass your CoinStats key in the `X-API-KEY` header on every request. Generate keys at [openapi.coinstats.app](https://openapi.coinstats.app). See [Authentication](/api-docs/api-docs/authentication) for OAuth Bearer usage.

```bash theme={null}
# Trending markets
curl "https://api.coinstats.app/v1/prediction/markets/trending?limit=5" \
  -H "X-API-KEY: YOUR_API_KEY"
```

```json theme={null}
{
  "success": true,
  "data": [
    {
      "source": "polymarket",
      "slug": "will-btc-hit-100k-2025",
      "question": "Will BTC hit $100k in 2025?",
      "outcomes": ["Yes", "No"],
      "outcomePrices": [0.62, 0.38],
      "volume24hr": 45000,
      "liquidity": 230000,
      "endDate": "2025-12-31T23:59:59.000Z"
    }
  ],
  "timestamp": "2025-06-19T12:00:00.000Z"
}
```

## Credits

Pricing is low and scales with how heavy each call is — every endpoint costs **1–3 credits**:

| Weight | Credits | Endpoints |
| - | - | - |
| **Read** — single object / point-in-time | 1 | `/markets/{slug}`, `…/prices`, `…/price-at`, `/events/{slug}` |
| **List** — paginated lists, trending, time-series, trader sub-resources | 2 | `/markets`, `/events`, `/traders`, `…/orderbook`, `…/bars`, `…/price-history`, `/traders/{address}`, `…/positions`, `…/trades`, `…/activity`, `…/pnl-history`, `…/trade-stats` |
| **Compute** — aggregation, scoring & search | 3 | `/analytics/*`, trader `…/category-stats`, `…/score`, `/search` |

## Explore the endpoints

> **[Markets & Events](/api-docs/api-docs/prediction/markets-and-events)**
>
> List, filter, and price markets and events.

> **[Traders & Analytics](/api-docs/api-docs/prediction/traders-and-analytics)**
>
> Leaderboards, per-trader PnL, and platform signals.

> **[API Reference](/api-docs/api-docs/openapi/list-markets)**
>
> Full request/response schema and try-it console for every endpoint.

> **[Search](/api-docs/api-docs/openapi/search)**
>
> Search events, markets, and traders.


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