Docs
    Guide

    Prediction Markets

    A unified, queryable view of every Polymarket market and trader — markets, OHLCV candles per outcome, open interest, real-time activity, positions, and platform-wide aggregates. No subgraph deploys, no custom indexers.

    What you get

    The Polymarket endpoints expose market metadata, outcome tokens, OHLCV candles, open interest, on-chain activity (trades, positions), per-user positions with cost basis and PnL, and platform-wide aggregates (volume, OI, fees). All data is derived from finalized chain state.

    Use cases

    Portfolio review

    Self-analysis for traders — pull a user's positions with cost basis and realized/unrealized PnL via /users/positions, then break down win rate, exposure by category, and average hold time.

    Leaderboard research

    Rank traders by PnL or volume with /users, then mirror or counter-trade the top performers by watching their /markets/positions flow.

    Market conviction

    Combine /markets/open-interest with /markets/ohlcv to spot conviction moves — rising OI alongside a price drift signals smart-money positioning before implied probabilities catch up.

    Platform health

    The /platform endpoint exposes aggregate volume, OI, and fee data — useful for trend monitoring, weekly reports, or dashboards that compare prediction-market activity against macro events.

    AI-assisted research

    Wire the endpoints into an MCP-compatible client (Claude Desktop, Cursor) or a Custom GPT — see the Custom GPT guide — and ask the model to surface unusual market moves, summarize a trader's recent activity, or extract candidates that match a thesis.

    Endpoint catalog at a glance

    • /v1/polymarket/markets — metadata, outcomes, token IDs, volume, status
    • /v1/polymarket/markets/ohlcv — OHLCV candles per outcome token
    • /v1/polymarket/markets/open-interest — OI time-series
    • /v1/polymarket/markets/activity — on-chain trade/position feed
    • /v1/polymarket/markets/positions — positions by outcome token
    • /v1/polymarket/platform — volume, OI, fees, aggregates
    • /v1/polymarket/users — user stats / leaderboard
    • /v1/polymarket/users/positions — per-user positions with cost basis + PnL

    Full request/response shapes and a live Try-it for each: Prediction Markets endpoint catalog.

    Frequently asked

    What chain is Polymarket data sourced from?
    Polymarket settles on Polygon. The Token API indexes the canonical contracts there and exposes them through the Prediction Markets endpoints.
    What is a token_id?
    Each outcome of each market is its own ERC-1155 token; the token_id is its identifier. Use /markets to discover token IDs for a market, then query OHLCV, OI, or positions for a specific outcome.
    How do I follow a trader in real time?
    Poll /users/positions at a sensible cadence (or use /markets/activity filtered by user) — both update as trades settle on Polygon.
    Is closed/resolved market data available?
    Yes. Resolved markets stay queryable with their full history (OHLCV, activity, positions) so you can backtest strategies or attribute PnL after the fact.
    Are there rate limits specific to Polymarket?
    No — Polymarket endpoints share the standard Token API quota. See your current spend on /usage.

    Related