Polymarket API
Polymarket is a decentralized prediction market where users trade on the outcomes of real-world events. It uses a hybrid-decentralized Central Limit Order Book (CLOB) with off-chain matching and on-chain settlement on Polygon.
Check this skill and the
official documentation FREQUENTLY. The canonical machine-readable index of all docs lives at:
Always consult
to discover every available page before building. It is the single source of truth for endpoint references, SDK docs, WebSocket channels, builder program details, and getting-started guides.
Key Concepts (Glossary)
| Term | Definition |
|---|
| Event | A collection of related markets grouped under a common topic (e.g., "2024 US Presidential Election"). |
| Market | A single tradeable binary outcome within an event. Each market has Yes and No sides, a condition ID, question ID, and pair of token IDs. |
| Token | Represents a position in a specific outcome (Yes or No). Prices range from 0.00 to 1.00. Winning tokens redeem for $1 USDCe. Also called outcome token. |
| Token ID | The unique identifier for a specific outcome token. Required when placing orders or querying prices. |
| Condition ID | On-chain identifier for a market's resolution condition. Used in CTF operations and as the market identifier in the CLOB. |
| Question ID | Identifier linking a market to its resolution oracle (UMA). |
| Slug | Human-readable URL identifier for a market or event (e.g., polymarket.com/event/[slug]
|
| CLOB | Central Limit Order Book — Polymarket's off-chain order matching system. Orders are matched here before on-chain settlement. |
| Tick Size | Minimum price increment for a market. Usually (1 cent) or (0.1 cent). |
| Fill | When an order is matched and executed. Orders can be partially or fully filled. |
| Negative Risk (NegRisk) | A multi-outcome event where only one outcome can resolve Yes. Requires in order parameters. |
| CTF | Conditional Token Framework — the on-chain smart contracts that manage outcome tokens. |
| Split | Convert USDCe into a complete set of outcome tokens (one Yes + one No). |
| Merge | Convert a complete set of outcome tokens back into USDCe. |
| Redeem | After resolution, exchange winning tokens for $1 USDCe each. |
| USDCe | Bridged USDC on Polygon — the stablecoin used as collateral on Polymarket. |
| Funder Address | The wallet address that holds funds and tokens for trading. |
| Signature Type | Identifies wallet type: = EOA, = Magic Link proxy (POLY_PROXY), = Gnosis Safe proxy. |
Order Types
| Type | Name | Description |
|---|
| GTC | Good-Til-Cancelled | Remains open until filled or manually cancelled. |
| GTD | Good-Til-Date | Expires at a specified time if not filled. |
| FOK | Fill-Or-Kill | Must be filled entirely and immediately, or cancelled. No partial fills. |
| FAK | Fill-And-Kill | Fills as much as possible immediately, then cancels any remaining unfilled portion. |
Base URLs
| API | Base URL | Description |
|---|
| CLOB API | https://clob.polymarket.com
| Order management, prices, orderbooks, trading |
| Gamma API | https://gamma-api.polymarket.com
| Market discovery, metadata, events, tags |
| Data API | https://data-api.polymarket.com
| User positions, activity, trade history |
| CLOB WebSocket | wss://ws-subscriptions-clob.polymarket.com/ws/
| Orderbook updates, order status |
| RTDS WebSocket | wss://ws-live-data.polymarket.com
| Low-latency crypto prices, comments |
Documentation & References
All detailed examples, request/response schemas, and walkthroughs live in the official docs. Always consult these before building:
Authentication
Polymarket uses a two-level authentication system. Public endpoints (market data, prices, orderbooks) require no authentication.
L1 Authentication (Private Key)
L1 uses the wallet's private key to sign an EIP-712 message. It proves ownership of the wallet and is used to create or derive L2 API credentials.
L1 Headers (for direct REST calls):
| Header | Description |
|---|
| Polygon signer address |
| EIP-712 signature |
| Current UNIX timestamp |
| Nonce (default 0) |
The
is generated by signing an EIP-712 struct with domain
(version
, chainId
).
TypeScript example:
typescript
import { ClobClient } from "@polymarket/clob-client";
import { Wallet } from "ethers"; // v5.8.0
const HOST = "https://clob.polymarket.com";
const CHAIN_ID = 137; // Polygon mainnet
const signer = new Wallet(process.env.PRIVATE_KEY);
const client = new ClobClient(HOST, CHAIN_ID, signer);
const apiCreds = await client.createOrDeriveApiKey();
// Returns: { apiKey, secret, passphrase }
Python example:
python
from py_clob_client.client import ClobClient
import os
client = ClobClient(
host="https://clob.polymarket.com",
chain_id=137,
key=os.getenv("PRIVATE_KEY"),
)
api_creds = client.create_or_derive_api_creds()
# Returns: { "apiKey": "...", "secret": "...", "passphrase": "..." }
L2 Authentication (API Credentials)
L2 uses the API credentials (apiKey, secret, passphrase) derived from L1. Requests are signed with
HMAC-SHA256 using the
.
L2 Headers (for direct REST calls):
| Header | Description |
|---|
| Polygon signer address |
| HMAC-SHA256 signature |
| Current UNIX timestamp |
| User's API value |
| User's API value |
TypeScript example (full L2 client):
typescript
import { ClobClient } from "@polymarket/clob-client";
import { Wallet } from "ethers"; // v5.8.0
const signer = new Wallet(process.env.PRIVATE_KEY);
const apiCreds = {
apiKey: process.env.API_KEY,
secret: process.env.SECRET,
passphrase: process.env.PASSPHRASE,
};
const client = new ClobClient(
"https://clob.polymarket.com",
137,
signer,
apiCreds,
2, // Signature type: 0=EOA, 1=POLY_PROXY, 2=GNOSIS_SAFE
process.env.FUNDER_ADDRESS, // proxy wallet address
);
Python example (full L2 client):
python
from py_clob_client.client import ClobClient
from py_clob_client.clob_types import ApiCreds
import os
api_creds = ApiCreds(
api_key=os.getenv("API_KEY"),
api_secret=os.getenv("SECRET"),
api_passphrase=os.getenv("PASSPHRASE"),
)
client = ClobClient(
host="https://clob.polymarket.com",
chain_id=137,
key=os.getenv("PRIVATE_KEY"),
creds=api_creds,
signature_type=2, # 0=EOA, 1=POLY_PROXY, 2=GNOSIS_SAFE
funder=os.getenv("FUNDER_ADDRESS"),
)
Signature Types
| Type | Value | Description |
|---|
| EOA | 0 | Standard Ethereum wallet. Funder is the EOA address. Needs POL for gas. |
| POLY_PROXY | 1 | Magic Link email/Google login proxy wallet. User must export PK from Polymarket.com. |
| GNOSIS_SAFE | 2 | Gnosis Safe multisig proxy wallet. Most common for Polymarket.com users. |
SDKs
Polymarket provides official SDKs. Prefer these for production integrations:
| SDK | Install | Source |
|---|
| TypeScript | npm install @polymarket/clob-client
| GitHub |
| Python | pip install py-clob-client
| GitHub |
| Rust | cargo add polymarket-client-sdk
| — |
For builders routing orders for users, also install:
| Package | Install | Purpose |
|---|
| Builder Signing SDK | npm install @polymarket/builder-signing-sdk
| Builder order attribution |
Rate Limits
Polymarket uses Cloudflare-based throttling (requests are delayed, not immediately rejected). Key limits:
General
| Endpoint | Limit |
|---|
| General Rate Limiting | 15,000 requests / 10s |
Gamma API
| Endpoint | Limit |
|---|
| Gamma (General) | 4,000 / 10s |
| 500 / 10s |
| 300 / 10s |
| & listing | 900 / 10s |
| Search | 350 / 10s |
| Tags | 200 / 10s |
| Comments | 200 / 10s |
CLOB API
| Endpoint | Limit |
|---|
| CLOB (General) | 9,000 / 10s |
| 1,500 / 10s |
| 1,500 / 10s |
| 1,500 / 10s |
| , , | 500 / 10s |
| Price History | 1,000 / 10s |
CLOB Trading
| Endpoint | Burst Limit | Sustained Limit |
|---|
| POST | 3,500 / 10s (500/s) | 36,000 / 10min (60/s) |
| DELETE | 3,000 / 10s (300/s) | 30,000 / 10min (50/s) |
| POST (batch) | 1,000 / 10s (100/s) | 15,000 / 10min (25/s) |
| DELETE (batch) | 1,000 / 10s (100/s) | 15,000 / 10min (25/s) |
| DELETE | 250 / 10s (25/s) | 6,000 / 10min (10/s) |
Data API
| Endpoint | Limit |
|---|
| Data API (General) | 1,000 / 10s |
| 200 / 10s |
| 150 / 10s |
| 150 / 10s |
REST API Endpoints Overview
Below is a summary organized by API. For full request/response schemas, see the linked docs or browse
https://docs.polymarket.com/llms.txt.
Gamma API — Market Discovery & Metadata
Base:
https://gamma-api.polymarket.com
CLOB API — Pricing & Orderbooks (Public)
Base:
https://clob.polymarket.com
CLOB API — Trading (Authenticated)
Base:
https://clob.polymarket.com
CLOB API — Orders & Trades (Authenticated)
CLOB API — Auth Endpoints
| Endpoint | Method | Auth | Description |
|---|
| POST | L1 | Create new API credentials |
| GET | L1 | Derive existing API credentials |
| GET | L2 | List API keys |
| DELETE | L2 | Delete/revoke an API key |
Data API — Positions & Activity
Base:
https://data-api.polymarket.com
Bridge API — Deposits & Withdrawals
Builder Program Endpoints
Fees
Current fee schedule (subject to change):
| Volume Level | Maker Fee (bps) | Taker Fee (bps) |
|---|
| >0 USDC | 0 | 0 |
Fee calculation depends on buying vs. selling:
- Selling outcome tokens:
feeQuote = baseRate × min(price, 1 - price) × size
- Buying outcome tokens:
feeBase = baseRate × min(price, 1 - price) × (size / price)
WebSocket API
Polymarket provides two WebSocket services for real-time data.
CLOB WebSocket
wss://ws-subscriptions-clob.polymarket.com/ws/
Two channels are available:
| Channel | Auth Required | Description | Docs |
|---|
| No | Orderbook and price updates (public) | Market Channel |
| Yes | Order status and trade updates | User Channel |
Market Channel Events
| Event Type | Trigger | Description |
|---|
| First subscribe / trade | Full orderbook snapshot with bids and asks |
| New order / cancellation | Incremental price level changes with best bid/ask |
| Price > 0.96 or < 0.04 | Minimum tick size update |
| Trade match | Last trade price, side, and size |
| Best price change | Best bid, ask, and spread (requires ) |
| Market created | New market details (requires ) |
| Market resolved | Resolution details with winning outcome (requires ) |
User Channel Events
| Event Type | Trigger | Description |
|---|
| Order matched / status change | Trade details with maker orders, status (, , , , ) |
| Order placed / updated / cancelled | Order details with type (, , ) |
Subscription
Send a JSON message upon connection:
json
{
"auth": { /* L2 auth for user channel */ },
"markets": ["0x...conditionId"],
"assets_ids": ["tokenId1", "tokenId2"],
"type": "market",
"custom_feature_enabled": true
}
Subscribe/unsubscribe to additional assets after connecting:
json
{
"assets_ids": ["tokenId3"],
"markets": [],
"operation": "subscribe",
"custom_feature_enabled": true
}
RTDS (Real-Time Data Stream)
wss://ws-live-data.polymarket.com
Low-latency streaming for crypto prices and comment feeds. Optimized for market makers.
Sports WebSocket
Real-time sports results via WebSocket:
Data Model
Event → Market → Token Hierarchy
Event (e.g., "Who will win the 2024 election?")
├── Market 1 (e.g., "Will Candidate A win?")
│ ├── Token: Yes (token_id: "abc...") price: 0.65
│ └── Token: No (token_id: "def...") price: 0.35
├── Market 2 (e.g., "Will Candidate B win?")
│ ├── Token: Yes (token_id: "ghi...") price: 0.30
│ └── Token: No (token_id: "jkl...") price: 0.70
└── ...
- Prices are implied probabilities (0.00–1.00). Yes + No prices sum to ≈ $1.
- from the Gamma API map to CLOB token IDs needed for trading.
- and arrays are 1:1 mapped.
Negative Risk Events
Multi-outcome events where only one outcome can resolve "Yes" use the negative risk architecture. A NO share in any market can be converted into 1 YES share in all other markets, enabling capital efficiency.
- on the event indicates negative risk.
- means placeholder outcomes can be clarified later.
Common Patterns
Fetch Active Events
bash
curl -s "https://gamma-api.polymarket.com/events?active=true&closed=false&limit=10" | jq '.[].title'
Get Event Details with Markets
bash
curl -s "https://gamma-api.polymarket.com/events?slug=will-bitcoin-reach-100k-by-2025" | jq '.[0] | {title, markets: [.markets[] | {question, outcomePrices, clobTokenIds}]}'
Get Current Price for a Token
bash
curl -s "https://clob.polymarket.com/price?token_id=YOUR_TOKEN_ID&side=buy"
# Returns: { "price": "0.65" }
Get Orderbook Depth
bash
curl -s "https://clob.polymarket.com/book?token_id=YOUR_TOKEN_ID" | jq '{bids: .bids[:3], asks: .asks[:3]}'
Get Midpoint Price
bash
curl -s "https://clob.polymarket.com/midpoint?token_id=YOUR_TOKEN_ID"
# Returns: { "mid": "0.655" }
Search for Markets
bash
curl -s "https://gamma-api.polymarket.com/search?query=bitcoin&limit=5" | jq '.markets[] | {question, slug}'
Discover Sports Markets
bash
# Get all supported sports leagues
curl -s "https://gamma-api.polymarket.com/sports" | jq '.'
# Get NBA events
curl -s "https://gamma-api.polymarket.com/events?series_id=10345&active=true&closed=false" | jq '.[].title'
Get User Positions (Data API)
bash
curl -s "https://data-api.polymarket.com/positions?user=0xYOUR_ADDRESS" | jq '.'
Place an Order (TypeScript)
typescript
import { ClobClient, Side, OrderType } from "@polymarket/clob-client";
import { Wallet } from "ethers";
const client = new ClobClient(
"https://clob.polymarket.com", 137, signer, apiCreds, 2, funderAddress
);
const market = await client.getMarket("CONDITION_ID");
const response = await client.createAndPostOrder(
{ tokenID: "TOKEN_ID", price: 0.50, size: 10, side: Side.BUY },
{ tickSize: market.tickSize, negRisk: market.negRisk },
OrderType.GTC
);
console.log("Order ID:", response.orderID);
Place an Order (Python)
python
from py_clob_client.client import ClobClient
from py_clob_client.clob_types import OrderArgs, OrderType
from py_clob_client.order_builder.constants import BUY
market = client.get_market("CONDITION_ID")
response = client.create_and_post_order(
OrderArgs(token_id="TOKEN_ID", price=0.50, size=10, side=BUY),
options={"tick_size": market["tickSize"], "neg_risk": market["negRisk"]},
order_type=OrderType.GTC,
)
print("Order ID:", response["orderID"])
CTF Operations (Split / Merge / Redeem)
The Conditional Token Framework enables conversion between USDCe and outcome tokens:
| Operation | Description | When to Use |
|---|
| Split | USDCe → 1 Yes token + 1 No token | Create inventory for market making |
| Merge | 1 Yes token + 1 No token → USDCe | Exit positions, reclaim collateral |
| Redeem | Winning token → $1 USDCe | After market resolution |
Builder Program
Builders are third-party developers who integrate Polymarket into their apps. The program offers permissionless integration with tiered rate limits, rewards, and revenue opportunities.
Builder credentials are separate from user credentials. You use builder credentials to tag/attribute orders, but each user still needs their own L2 credentials to trade.
Market Making
Usage Tips
- Always check first: https://docs.polymarket.com/llms.txt has every endpoint and guide.
- Never hardcode private keys — use environment variables or secure key storage.
- Prices are probabilities (0.00–1.00). Winning tokens redeem at $1 USDCe.
- Use when querying events to get only live, tradable markets.
- Token IDs come from Gamma — fetch events/markets from Gamma API, then use for CLOB queries and trading.
- Set correctly — multi-outcome events use negative risk. Check the event's field and pass it when creating orders.
- Use the SDK instead of signing manually — L1/L2 signing is complex (EIP-712 + HMAC-SHA256). The TypeScript and Python clients handle this.
- Allowances must be set — before placing orders, the funder address must have USDCe allowance set for the Exchange contract (buying) or conditional token allowance (selling).
- Combine REST + WebSocket — use REST for initial state and WebSocket for real-time deltas.
- Respect rate limits — implement backoff when throttled. Use batch endpoints (, ) to reduce request count.
- Signature type matters — type (EOA) for standalone wallets, type (Gnosis Safe) for most Polymarket.com accounts. Incorrect type will cause auth failures.
- Funder ≠ Signer for proxy wallets — the funder is the proxy wallet address (visible at polymarket.com/settings), not the private key's EOA address.
- Geographic restrictions apply — check https://docs.polymarket.com/developers/CLOB/geoblock.md before trading.
- Order validity is continuously monitored — balances, allowances, and on-chain cancellations are checked in real time. Abuse leads to blacklisting.
Error Handling
Standard HTTP error codes apply. The API returns JSON error bodies with descriptive messages.
- Throttled requests (rate limited): Requests are delayed/queued, not immediately rejected. Implement backoff.
- Authentication errors: Verify private key, signature type, funder address, and API credentials match.
- Insufficient balance: Check funder address has enough USDCe or conditional tokens, including existing open order commitments.
- Order rejected: Max order size =
balance - sum(openOrderSize - fillAmount)
- Geographic restriction: Trading blocked from restricted regions.
Resolution
Markets are resolved by the UMA Optimistic Oracle, a smart-contract-based optimistic oracle. Resolution can be disputed via the UMA protocol.
On-Chain Resources
Changelog
Monitor the
Polymarket Changelog for updates to the CLOB, API, UI, and mobile applications.