Polymarket

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)

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

Order Types

Base URLs

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:

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

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

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

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

SDKs

Polymarket provides official SDKs. Prefer these for production integrations:

For builders routing orders for users, also install:

Rate Limits

Polymarket uses Cloudflare-based throttling (requests are delayed, not immediately rejected). Key limits:

General

Gamma API

CLOB API

CLOB Trading

Data API

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

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

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

Data API — Positions & Activity

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

Bridge API — Deposits & Withdrawals

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

Builder Program Endpoints

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

Fees

Current fee schedule (subject to change):

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:

Market Channel Events

User Channel Events

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:

• 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.

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

Changelog

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