Polymarket Market Data API & MCP Server

Authentication

Create a key at /dashboard/settings (shown once, prefix udc_). Send it as a Bearer token on every request. The key resolves to a user, the user resolves to a tier, and the tier must be Premium — keys held by Free or Pro accounts authenticate but are rejected with 403.

curl -H "Authorization: Bearer udc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  https://www.updowncharts.com/api/v1/markets

Revoking a key at any time invalidates it immediately. Every authenticated request updates the key's last_used_at.

Rate limits & errors

Premium keys are limited to 100 requests per minute and 50,000 requests per day, counted per key. Successful responses carry X-RateLimit-Remaining-Minute and X-RateLimit-Remaining-Day.

GET /api/v1/markets

Returns the full catalog of 28 markets plus the tier your key resolves to. The catalog is static configuration, so this endpoint is the cheapest way to discover valid asset and timeframe values before calling anything else. The same catalog is browsable at /markets.

{
  "markets": [
    {
      "key": "btc-5m",
      "asset": "btc",
      "symbol": "BTC",
      "displayName": "Bitcoin",
      "timeframe": "5m",
      "durationSeconds": 300,
      "label": "5M"
    },
    {
      "key": "btc-15m",
      "asset": "btc",
      "symbol": "BTC",
      "displayName": "Bitcoin",
      "timeframe": "15m",
      "durationSeconds": 900,
      "label": "15M"
    }
  ],
  "tier": "premium"
}

Takes no parameters. Errors: 401, 403, 429.

GET /api/v1/epochs

Paginated epoch history for one market, newest first. Each row is one settled or open window with its price to beat, close, outcome and final volume. Pagination is keyset based on the epoch number: pass the returned nextCursor back as cursor to get the next page. nextCursor is null on the last page.

curl -H "Authorization: Bearer udc_..." \
  "https://www.updowncharts.com/api/v1/epochs?asset=btc&timeframe=15m&limit=50"

{
  "epochs": [
    {
      "slug": "btc-updown-15m-1751000400",
      "date": "2026-06-27",
      "outcome": "UP",
      "ptb": 107412.5,
      "close": 107480.1,
      "volume": 18422.36,
      "hasTickPrices": true,
      "polymarketSlug": "btc-updown-15m-1751000400"
    },
    {
      "slug": "btc-updown-15m-1750999500",
      "date": "2026-06-27",
      "outcome": "DOWN",
      "ptb": 107455.0,
      "close": 107412.5,
      "volume": 20117.02,
      "hasTickPrices": true,
      "polymarketSlug": null
    }
  ],
  "nextCursor": "1750999500"
}

Errors: 400 invalid_market, 401, 403, 429.

GET /api/v1/ticks/{slug}

Full tick series for one epoch, returned column-wise: every array is the same length and index i across all arrays describes the same tick. Timestamps in ts are offsets in milliseconds from baseTs. Missing values are null rather than interpolated. If the epoch is the current live one and no recorded rows exist yet, the live buffer is returned instead.

curl -H "Authorization: Bearer udc_..." \
  https://www.updowncharts.com/api/v1/ticks/btc-updown-15m-1751000400

{
  "slug": "btc-updown-15m-1751000400",
  "date": "2026-06-27",
  "outcome": "UP",
  "ptb": 107412.5,
  "close": 107480.1,
  "baseTs": 1751000400000,
  "ticks": {
    "ts":          [0, 412, 907],
    "upBid":       [0.49, 0.51, 0.53],
    "upAsk":       [0.51, 0.53, 0.55],
    "downBid":     [0.47, 0.45, 0.43],
    "downAsk":     [0.51, 0.49, 0.47],
    "binance":     [107412.5, 107419.8, 107433.1],
    "chainlink":   [107410.0, null, 107431.7],
    "pyth":        [107413.2, 107420.4, 107434.0],
    "ptbCaptured": [107412.5, 107412.5, 107412.5],
    "ptbApi":      [null, 107412.5, 107412.5]
  }
}

Errors: 400 invalid_slug, 404 not_found (no data, including epochs older than the 90-day retention window), 401, 403, 429.

GET /api/v1/live/{asset}/{timeframe}

Latest single snapshot for the market's current epoch: most recent underlying prices, most recent top-of-book quotes, and the price to beat. ts is the newer of the two source timestamps in Unix milliseconds. The slug is derived server-side from the current wall clock, so no epoch argument is needed.

curl -H "Authorization: Bearer udc_..." \
  https://www.updowncharts.com/api/v1/live/btc/15m

{
  "slug": "btc-updown-15m-1751000400",
  "ts": 1751000812345,
  "binance": 107419.8,
  "chainlink": 107418.0,
  "pyth": 107420.4,
  "upBid": 0.51,
  "upAsk": 0.53,
  "downBid": 0.45,
  "downAsk": 0.49,
  "ptb": 107412.5
}

Errors: 400 invalid_market, 404 not_found (no tick or quote rows yet for the current epoch), 401, 403, 429.

MCP server

A hosted Model Context Protocol server at https://www.updowncharts.com/api/mcp. Transport is Streamable HTTP and the server is stateless — every request carries the same udc_ Bearer key and is authorized before it reaches the tool layer, so the 401 / 403 / 429 responses above apply identically. GET, POST and DELETE are handled.

claude mcp add --transport http updown https://www.updowncharts.com/api/mcp --header "Authorization: Bearer udc_..."

Tool results are JSON encoded as text content, matching the REST response shapes above. An unknown market or missing slug comes back as an error result (isError), not an HTTP error.

Field glossary

Retention & data access by tier

Tick and quote tables are monthly partitions with a 90-day retention window; partitions older than 90 days are dropped daily. Epoch summaries and tick series outside that window return 404. Export what you need to keep.

Compare plans →