Polymarket API Overview
Understanding the Polymarket ecosystem APIs that polygolem wraps.
What is Polymarket?
Polymarket is a prediction-market exchange. Users trade outcome shares for questions like “Will BTC be above $X at 12:00?” or “Will candidate Y win?” A YES or NO share usually trades between $0 and $1; a $0.62 YES price is roughly a 62% market-implied probability before fees, spread, and liquidity caveats.
A complete Polymarket integration needs more than one API:
| Layer | What it answers | Typical auth |
|---|---|---|
| Gamma | What markets/events exist? | None |
| CLOB | What are the live books/prices, and how do I place/cancel orders? | None for reads, L2 auth for trading |
| Data API | What positions, holders, activity, leaderboards, and analytics exist? | Mostly none |
| WebSocket | What changed in real time? | None for market streams, L2 auth for user streams |
| Relayer | How do deposit-wallet deploy/approval batches get submitted? | Relayer auth |
| Polygon contracts | What settles funds, positions, approvals, and signatures on-chain? | Wallet signatures / chain calls |
Polygolem gives these layers one Go-shaped interface while keeping read-only paths credential-free and mutating paths explicit.
The short version
- Use Gamma to find markets and metadata.
- Use CLOB public reads for order books, prices, tick sizes, and fee rates.
- Use Data API for wallet/portfolio/holder analytics.
- Use WebSocket for live market and user-event streams.
- Use Relayer + contracts for deposit-wallet lifecycle operations.
- Use CLOB authenticated endpoints for live order placement and cancels.
Gamma API (gamma-api.polymarket.com)
Read-only. No authentication.
Market metadata, events, search, tags, series, sports, comments, profiles.
| Category | Endpoints |
|---|---|
| Markets | List, by ID, by slug, by token |
| Events | List, by ID, by slug, keyset pagination |
| Search | Cross-entity (markets, events, profiles, tags) |
| Tags | List, by ID, by slug, related |
| Series | List, by ID |
| Sports | Teams, sports metadata, market types |
| Comments | List, by ID, by user |
| Profiles | Public profile by wallet |
See Gamma API for the exact polygolem method to REST-path mapping.
CLOB API (clob.polymarket.com)
Public endpoints (L0): no auth. Authenticated endpoints (L1/L2): require wallet + API key.
Order book, pricing, market data, orders, trades, rewards.
| Category | Auth | Endpoints |
|---|---|---|
| Market Data | L0 | Order book, price, midpoint, spread, tick size, fee rate, neg risk, last trade |
| Markets | L0 | List, by condition ID, simplified, sampling |
| Orders | L2 | Place, cancel, query, heartbeat |
| Trades | L2 | Get trades, builder trades |
| Rewards | L0 | Config, earnings, percentages, rebates |
| Scoring | L0 | Order scoring status |
Important auth split: CLOB L2 credentials authenticate trading endpoints;
relayer credentials only submit gas-sponsored smart-wallet transactions.
Builder fee keys minted through CLOB are used as the V2 order builder
attribution field, not as relayer headers.
See CLOB V2 API for the full table.
Data API (data-api.polymarket.com)
Read-only analytics. No auth for most endpoints.
Positions, volume, leaderboards, open interest, top holders.
| Category | Endpoints |
|---|---|
| Positions | Current and closed positions |
| Trades/activity | Public trades and public activity for a wallet |
| Portfolio | Total value and markets traded |
| Market analytics | Holders, open interest, live volume |
| Rankings | Trader leaderboard |
See Data API.
Bridge API (bridge.polymarket.com)
Read-only. No auth.
Supported assets, deposit addresses, quotes, transaction status.
| Endpoint | Wrapped by |
|---|---|
GET /supported-assets | SDK and CLI |
POST /deposit | SDK and CLI |
GET /status/{address} | SDK only |
POST /quote | SDK only |
See Bridge API.
Relayer API (relayer-v2.polymarket.com)
Authenticated. Requires a V2 Relayer API Key or legacy builder-relayer HMAC credentials.
Gas-sponsored transaction submission for deposit-wallet lifecycle operations. This is separate from CLOB L2 auth.
| Category | Endpoints |
|---|---|
| Transactions | Submit (WALLET-CREATE, WALLET batch), poll, list |
| Nonce | Get current WALLET nonce for EOA |
| Deployment | Check if wallet deployed |
| API Keys | Relayer key management where upstream account auth allows it |
Polygolem’s deposit-wallet relayer flow uses POST /submit,
GET /nonce, GET /transaction, GET /deployed, and
POST /relayer/api/auth. Upstream also exposes GET /transactions,
GET /relay-payload, and relayer key listing endpoints that are not stable
polygolem SDK methods yet.
The relayer sponsors deposit-wallet deploy and WALLET batch transactions such as approvals. CLOB order placement is an authenticated API request, not a user gas transaction. Users still pay gas for direct EOA actions such as the initial pUSD transfer into the deposit wallet.
See Relayer API.
WebSocket (ws-subscriptions-clob.polymarket.com)
Market channel: no auth. User channel: L2 auth.
Real-time stream for order books, prices, trades, order events.
See Stream API.
Smart Contracts
All Polymarket contracts used by these APIs are on Polygon mainnet
(chainId=137). The important V2 groups are:
| Group | Contracts |
|---|---|
| Trading | CTF Exchange, Neg Risk CTF Exchange, Neg Risk Adapter |
| Collateral | pUSD, CTF, CollateralOnramp, CollateralOfframp, collateral adapters |
| Wallets | Deposit Wallet Factory, Proxy Factory, Gnosis Safe Factory |
| Resolution | UMA Adapter, UMA Optimistic Oracle |
See Contracts Registry.