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

# Prediction Markets

> Read-only analytics for Polymarket prediction markets — markets, events, 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** behind one read-only API: consistent shapes, one auth scheme, and deep per-trader analytics.

<Note>**Base path:** `https://api.polystats.ai/api/*` · `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](/docs/openapi/list-markets).</Note>

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; events group related markets (e.g. every candidate in an election).
* **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](/docs/authentication) for OAuth Bearer usage.

```bash theme={null}
# Trending markets
curl "https://api.polystats.ai/api/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

<CardGroup cols={2}>
  <Card title="Markets & Events" icon="chart-line" href="/docs/prediction/markets-and-events">
    List, filter, and price markets and events.
  </Card>

  <Card title="Traders & Analytics" icon="users" href="/docs/prediction/traders-and-analytics">
    Leaderboards, per-trader PnL, and platform signals.
  </Card>

  <Card title="API Reference" icon="code" href="/docs/openapi/list-markets">
    Full request/response schema and try-it console for every endpoint.
  </Card>

  <Card title="Search" icon="magnifying-glass" href="/docs/openapi/search">
    Search events, markets, and traders.
  </Card>
</CardGroup>