Key Concepts
Before diving into the API, it helps to understand how Polymarket data is structured on-chain.Markets
A market is a prediction question — “Will Bitcoin hit $100K by June 2025?” Each market has:- A condition ID — the unique on-chain identifier
- Two or more outcome tokens — the tradeable positions (e.g., Yes / No)
- A resolution — the final outcome, determined by an oracle
Outcome Tokens
Outcome tokens are ERC1155 tokens on Polygon. Each outcome in a market has a unique token ID (a large uint256 number). For a binary market (Yes/No), there are exactly two token IDs. They’re complementary — if you hold one Yes token and one No token, you can always redeem them for $1 USDC. This means:- If Yes is trading at 0.30
- Prices always sum to ~$1.00 (minus fees)
Trades
A trade happens when the CTF Exchange matches a maker and taker order. Each trade records:| Field | Description |
|---|---|
token_id | Which outcome token was traded |
side | BUY or SELL (from the maker’s perspective) |
price | Execution price in USDC (0.00 – 1.00) |
size | Number of outcome tokens traded |
maker / taker | Wallet addresses of both parties |
tx_hash | Polygon transaction hash |
block_number | When it was settled on-chain |
Neg Risk Markets
Some markets have many outcomes (e.g., “Who will win the election?” with 10+ candidates). These use the Neg Risk CTF Exchange — a capital-efficient system where holding “No” on one candidate is equivalent to holding “Yes” on all other candidates. The Neg Risk Adapter handles conversions between these token types.Orderbook
Polymarket uses a hybrid model: orders are matched off-chain for speed, then settled on-chain for finality. Gimme Fast polls the off-chain orderbook and caches snapshots, giving you the current bid/ask for any token.OHLCV Candles
Standard candlestick data computed from trade history:- Open — first trade price in the interval
- High — highest price
- Low — lowest price
- Close — last trade price
- Volume — total USDC volume
1m, 5m, 15m, 1h, 4h, 1d.
Key IDs and Formats
| Identifier | Format | Example |
|---|---|---|
| Market ID | UUID | f47ac10b-58cc-4372-a567-0e02b2c3d479 |
| Condition ID | hex string | 0x1234abcd... |
| Token ID | uint256 string | 21742633143463906290569... |
| API Key | gf_ + 32 hex | gf_a1b2c3d4e5f67890abcdef1234567890 |
| Transaction Hash | 0x + 64 hex | 0xabc123... |