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:

https://docs.polymarket.com/llms.txt

Always consult llms.txt 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 `0.01` (1 cent) or `0.001` (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 `negRisk: true` 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: `0` = EOA, `1` = Magic Link proxy (POLY_PROXY), `2` = Gnosis Safe proxy.

Full glossary: https://docs.polymarket.com/quickstart/reference/glossary.md

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

Endpoints reference: https://docs.polymarket.com/quickstart/reference/endpoints.md

Documentation & References

All detailed examples, request/response schemas, and walkthroughs live in the official docs. Always consult these before building:

Resource	URL
Full documentation index (llms.txt)	https://docs.polymarket.com/llms.txt
Developer Quickstart	https://docs.polymarket.com/quickstart/overview.md
Fetching Market Data	https://docs.polymarket.com/quickstart/fetching-data.md
Placing Your First Order	https://docs.polymarket.com/quickstart/first-order.md
API Rate Limits	https://docs.polymarket.com/quickstart/introduction/rate-limits.md
Endpoints Reference	https://docs.polymarket.com/quickstart/reference/endpoints.md
Glossary	https://docs.polymarket.com/quickstart/reference/glossary.md
CLOB Introduction	https://docs.polymarket.com/developers/CLOB/introduction.md
Authentication	https://docs.polymarket.com/developers/CLOB/authentication.md
Client Methods Overview	https://docs.polymarket.com/developers/CLOB/clients/methods-overview.md
Public Methods	https://docs.polymarket.com/developers/CLOB/clients/methods-public.md
L1 Methods	https://docs.polymarket.com/developers/CLOB/clients/methods-l1.md
L2 Methods	https://docs.polymarket.com/developers/CLOB/clients/methods-l2.md
Orders Overview	https://docs.polymarket.com/developers/CLOB/orders/orders.md
Place Single Order	https://docs.polymarket.com/developers/CLOB/orders/create-order.md
Place Multiple Orders	https://docs.polymarket.com/developers/CLOB/orders/create-order-batch.md
Cancel Orders	https://docs.polymarket.com/developers/CLOB/orders/cancel-orders.md
WebSocket Overview	https://docs.polymarket.com/developers/CLOB/websocket/wss-overview.md
Market Channel	https://docs.polymarket.com/developers/CLOB/websocket/market-channel.md
User Channel	https://docs.polymarket.com/developers/CLOB/websocket/user-channel.md
Gamma Structure	https://docs.polymarket.com/developers/gamma-markets-api/gamma-structure.md
How to Fetch Markets	https://docs.polymarket.com/developers/gamma-markets-api/fetch-markets-guide.md
Negative Risk Overview	https://docs.polymarket.com/developers/neg-risk/overview.md
CTF Overview	https://docs.polymarket.com/developers/CTF/overview.md
Builder Program	https://docs.polymarket.com/developers/builders/builder-intro.md
Market Makers Introduction	https://docs.polymarket.com/developers/market-makers/introduction.md
Bridge Overview	https://docs.polymarket.com/developers/misc-endpoints/bridge-overview.md
Polymarket Platform	https://polymarket.com

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
`POLY_ADDRESS`	Polygon signer address
`POLY_SIGNATURE`	EIP-712 signature
`POLY_TIMESTAMP`	Current UNIX timestamp
`POLY_NONCE`	Nonce (default 0)

The POLY_SIGNATURE is generated by signing an EIP-712 struct with domain ClobAuthDomain (version 1, chainId 137).

TypeScript example:

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:

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": "..." }

Full L1 auth details: https://docs.polymarket.com/developers/CLOB/authentication.md

L2 Authentication (API Credentials)

L2 uses the API credentials (apiKey, secret, passphrase) derived from L1. Requests are signed with HMAC-SHA256 using the secret.

L2 Headers (for direct REST calls):

Header	Description
`POLY_ADDRESS`	Polygon signer address
`POLY_SIGNATURE`	HMAC-SHA256 signature
`POLY_TIMESTAMP`	Current UNIX timestamp
`POLY_API_KEY`	User's API `apiKey` value
`POLY_PASSPHRASE`	User's API `passphrase` value

TypeScript example (full L2 client):

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):

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.

Full auth guide: https://docs.polymarket.com/developers/CLOB/authentication.md

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
`/events`	500 / 10s
`/markets`	300 / 10s
`/markets` & `/events` listing	900 / 10s
Search	350 / 10s
Tags	200 / 10s
Comments	200 / 10s

CLOB API

Endpoint	Limit
CLOB (General)	9,000 / 10s
`/book`	1,500 / 10s
`/price`	1,500 / 10s
`/midprice`	1,500 / 10s
`/books`, `/prices`, `/midprices`	500 / 10s
Price History	1,000 / 10s

CLOB Trading

Endpoint	Burst Limit	Sustained Limit
POST `/order`	3,500 / 10s (500/s)	36,000 / 10min (60/s)
DELETE `/order`	3,000 / 10s (300/s)	30,000 / 10min (50/s)
POST `/orders` (batch)	1,000 / 10s (100/s)	15,000 / 10min (25/s)
DELETE `/orders` (batch)	1,000 / 10s (100/s)	15,000 / 10min (25/s)
DELETE `/cancel-all`	250 / 10s (25/s)	6,000 / 10min (10/s)

Data API

Endpoint	Limit
Data API (General)	1,000 / 10s
`/trades`	200 / 10s
`/positions`	150 / 10s
`/closed-positions`	150 / 10s

Full rate limits: https://docs.polymarket.com/quickstart/introduction/rate-limits.md

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

Endpoint	Method	Description	Docs
`/events`	GET	List events (filter by `active`, `closed`, `tag_id`, `series_id`, etc.)	List Events
`/events/{id}`	GET	Get event by ID	Get Event by ID
`/events/{slug}`	GET	Get event by slug	Get Event by Slug
`/events/tags`	GET	Get event tags	Get Event Tags
`/markets`	GET	List markets (filter by various criteria)	List Markets
`/markets/{id}`	GET	Get market by ID	Get Market by ID
`/markets/{slug}`	GET	Get market by slug	Get Market by Slug
`/tags`	GET	List tags	List Tags
`/tags/{id}`	GET	Get tag by ID	Get Tag by ID
`/tags/{slug}`	GET	Get tag by slug	Get Tag by Slug
`/series`	GET	List series	List Series
`/series/{id}`	GET	Get series by ID	Get Series by ID
`/sports`	GET	Get sports metadata	Get Sports Metadata
`/sports/market-types`	GET	Get valid sports market types	Get Valid Sports Market Types
`/teams`	GET	List teams	List Teams
`/search`	GET	Search markets, events, and profiles	Search
`/comments`	GET	List comments	List Comments
`/profiles/{address}`	GET	Get public profile by wallet address	Get Profile

Gamma structure guide: https://docs.polymarket.com/developers/gamma-markets-api/gamma-structure.md

CLOB API — Pricing & Orderbooks (Public)

Base: https://clob.polymarket.com

Endpoint	Method	Auth	Description	Docs
`/price`	GET	No	Get current price for a token and side	Get Market Price
`/prices`	POST	No	Get prices for multiple tokens and sides	Get Multiple Market Prices
`/midpoint`	GET	No	Get midpoint price for a token	Get Midpoint Price
`/book`	GET	No	Get order book for a token	Get Order Book Summary
`/books`	POST	No	Get order books for multiple tokens	Get Multiple Order Books
`/prices-history`	GET	No	Get historical price data for a token	Get Price History
`/spreads`	GET	No	Get bid-ask spreads for multiple tokens	Get Bid-Ask Spreads

CLOB API — Trading (Authenticated)

Base: https://clob.polymarket.com

Endpoint	Method	Auth	Description	Docs
`/order`	POST	L2	Place a single order	Place Single Order
`/order`	DELETE	L2	Cancel a single order	Cancel Orders
`/orders`	POST	L2	Place multiple orders (batch, up to 15)	Place Multiple Orders
`/orders`	DELETE	L2	Cancel multiple orders	Cancel Orders
`/cancel-all`	DELETE	L2	Cancel all open orders	Cancel Orders
`/cancel-market-orders`	DELETE	L2	Cancel all orders for a specific market	Cancel Orders

CLOB API — Orders & Trades (Authenticated)

Endpoint	Method	Auth	Description	Docs
`/data/order/{orderId}`	GET	L2	Get a specific order	Get Order
`/data/orders`	GET	L2	Get active/open orders	Get Active Orders
`/data/trades`	GET	L2	Get user's trades	Get Trades
`/order/scoring`	GET	L2	Check order reward scoring eligibility	Check Scoring

CLOB API — Auth Endpoints

Endpoint	Method	Auth	Description
`/auth/api-key`	POST	L1	Create new API credentials
`/auth/derive-api-key`	GET	L1	Derive existing API credentials
`/auth/api-keys`	GET	L2	List API keys
`/auth/api-key`	DELETE	L2	Delete/revoke an API key

Data API — Positions & Activity

Base: https://data-api.polymarket.com

Endpoint	Method	Description	Docs
`/positions`	GET	Get current positions for a user	Get Current Positions
`/closed-positions`	GET	Get closed positions for a user	Get Closed Positions
`/positions/market`	GET	Get positions for a market	Get Positions for Market
`/positions/value`	GET	Get total value of a user's positions	Get Total Value
`/top-holders`	GET	Get top holders for markets	Get Top Holders
`/trades`	GET	Get trades for a user or markets	Get Trades
`/activity`	GET	Get user on-chain activity	Get User Activity
`/leaderboard`	GET	Get trader leaderboard rankings	Get Leaderboard
`/open-interest`	GET	Get open interest	Get Open Interest
`/volume`	GET	Get live volume for an event	Get Live Volume

Bridge API — Deposits & Withdrawals

Endpoint	Method	Description	Docs
`/deposit`	POST	Create deposit addresses	Create Deposit Addresses
`/withdraw`	POST	Create withdrawal addresses	Create Withdrawal Addresses
`/supported-assets`	GET	Get supported chains & tokens	Get Supported Assets
`/quote`	GET	Get deposit/withdrawal quote	Get a Quote
`/status`	GET	Get transaction status	Get Transaction Status

Bridge overview: https://docs.polymarket.com/developers/misc-endpoints/bridge-overview.md

Builder Program Endpoints

Endpoint	Method	Description	Docs
`/builders/leaderboard`	GET	Get aggregated builder leaderboard	Builder Leaderboard
`/builders/volume`	GET	Get daily builder volume time-series	Builder Volume

Builder program: https://docs.polymarket.com/developers/builders/builder-intro.md

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)

Fees details: https://docs.polymarket.com/developers/CLOB/introduction.md

Maker rebates program: https://docs.polymarket.com/developers/market-makers/maker-rebates-program.md

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
`market`	No	Orderbook and price updates (public)	Market Channel
`user`	Yes	Order status and trade updates	User Channel

Market Channel Events

Event Type	Trigger	Description
`book`	First subscribe / trade	Full orderbook snapshot with bids and asks
`price_change`	New order / cancellation	Incremental price level changes with best bid/ask
`tick_size_change`	Price > 0.96 or < 0.04	Minimum tick size update
`last_trade_price`	Trade match	Last trade price, side, and size
`best_bid_ask`	Best price change	Best bid, ask, and spread (requires `custom_feature_enabled`)
`new_market`	Market created	New market details (requires `custom_feature_enabled`)
`market_resolved`	Market resolved	Resolution details with winning outcome (requires `custom_feature_enabled`)

User Channel Events

Event Type	Trigger	Description
`trade`	Order matched / status change	Trade details with maker orders, status (`MATCHED`, `MINED`, `CONFIRMED`, `RETRYING`, `FAILED`)
`order`	Order placed / updated / cancelled	Order details with type (`PLACEMENT`, `UPDATE`, `CANCELLATION`)

Subscription

Send a JSON message upon connection:

{
  "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:

{
  "assets_ids": ["tokenId3"],
  "markets": [],
  "operation": "subscribe",
  "custom_feature_enabled": true
}

Full WebSocket guide: https://docs.polymarket.com/developers/CLOB/websocket/wss-overview.md WSS Authentication: https://docs.polymarket.com/developers/CLOB/websocket/wss-auth.md

RTDS (Real-Time Data Stream)

wss://ws-live-data.polymarket.com

Low-latency streaming for crypto prices and comment feeds. Optimized for market makers.

RTDS Overview: https://docs.polymarket.com/developers/RTDS/RTDS-overview.md
RTDS Crypto Prices: https://docs.polymarket.com/developers/RTDS/RTDS-crypto-prices.md
RTDS Comments: https://docs.polymarket.com/developers/RTDS/RTDS-comments.md

Sports WebSocket

Real-time sports results via WebSocket:

Overview: https://docs.polymarket.com/developers/sports-websocket/overview.md
Quickstart: https://docs.polymarket.com/developers/sports-websocket/quickstart.md
Message Format: https://docs.polymarket.com/developers/sports-websocket/message-format.md

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.
clobTokenIds from the Gamma API map to CLOB token IDs needed for trading.
outcomes and outcomePrices 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.

negRisk: true on the event indicates negative risk.
negRiskAugmented: true means placeholder outcomes can be clarified later.

Full NegRisk docs: https://docs.polymarket.com/developers/neg-risk/overview.md

Common Patterns

Fetch Active Events

curl -s "https://gamma-api.polymarket.com/events?active=true&closed=false&limit=10" | jq '.[].title'

Get Event Details with Markets

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

curl -s "https://clob.polymarket.com/price?token_id=YOUR_TOKEN_ID&side=buy"
# Returns: { "price": "0.65" }

Get Orderbook Depth

curl -s "https://clob.polymarket.com/book?token_id=YOUR_TOKEN_ID" | jq '{bids: .bids[:3], asks: .asks[:3]}'

Get Midpoint Price

curl -s "https://clob.polymarket.com/midpoint?token_id=YOUR_TOKEN_ID"
# Returns: { "mid": "0.655" }

Search for Markets

curl -s "https://gamma-api.polymarket.com/search?query=bitcoin&limit=5" | jq '.markets[] | {question, slug}'

Discover Sports Markets

# 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)

curl -s "https://data-api.polymarket.com/positions?user=0xYOUR_ADDRESS" | jq '.'

Place an Order (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)

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

Split: https://docs.polymarket.com/developers/CTF/split.md
Merge: https://docs.polymarket.com/developers/CTF/merge.md
Redeem: https://docs.polymarket.com/developers/CTF/redeem.md
Deployment & addresses: https://docs.polymarket.com/developers/CTF/deployment-resources.md

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.

Resource	URL
Builder Introduction	https://docs.polymarket.com/developers/builders/builder-intro.md
Builder Profile & Keys	https://docs.polymarket.com/developers/builders/builder-profile.md
Builder Tiers	https://docs.polymarket.com/developers/builders/builder-tiers.md
Order Attribution	https://docs.polymarket.com/developers/builders/order-attribution.md
Builder Methods	https://docs.polymarket.com/developers/CLOB/clients/methods-builder.md
Relayer Client (gasless txns)	https://docs.polymarket.com/developers/builders/relayer-client.md
Examples (Next.js)	https://docs.polymarket.com/developers/builders/examples.md

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

Resource	URL
Introduction	https://docs.polymarket.com/developers/market-makers/introduction.md
Setup	https://docs.polymarket.com/developers/market-makers/setup.md
Trading	https://docs.polymarket.com/developers/market-makers/trading.md
Inventory Management	https://docs.polymarket.com/developers/market-makers/inventory.md
Data Feeds	https://docs.polymarket.com/developers/market-makers/data-feeds.md
Liquidity Rewards	https://docs.polymarket.com/developers/market-makers/liquidity-rewards.md
Maker Rebates	https://docs.polymarket.com/developers/market-makers/maker-rebates-program.md

Usage Tips

Always check llms.txt 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 active=true&closed=false when querying events to get only live, tradable markets.
Token IDs come from Gamma — fetch events/markets from Gamma API, then use clobTokenIds for CLOB queries and trading.
Set negRisk correctly — multi-outcome events use negative risk. Check the event's negRisk 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 (/books, /prices) to reduce request count.
Signature type matters — type 0 (EOA) for standalone wallets, type 2 (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) per market.
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.

Resolution overview: https://docs.polymarket.com/developers/resolution/UMA.md
How markets are resolved: https://docs.polymarket.com/polymarket-learn/markets/how-are-markets-resolved.md
How markets are disputed: https://docs.polymarket.com/polymarket-learn/markets/dispute.md

On-Chain Resources

Resource	URL
Exchange contract source	GitHub
Exchange contract docs	GitHub
Security audit (Chainsecurity)	Audit PDF
Negative Risk Adapter	Polygonscan
Subgraph overview	https://docs.polymarket.com/developers/subgraph/overview.md
Blockchain data resources	https://docs.polymarket.com/developers/builders/blockchain-data-resources.md
USDC on Polygon	`0x2791bca1f2de4661ed88a30c99a7a9449aa84174`

Changelog

Monitor the Polymarket Changelog for updates to the CLOB, API, UI, and mobile applications.