polymarket-api Checked

Polymarket exchange mechanics — on-chain Polygon CTF, Gamma/CLOB/Data APIs, EIP-712 auth, identifier model, WebSocket, settlement, and geo/KYC constraint

Polymarket API

Polymarket is a **prediction market on Polygon mainnet**. Every market is a pair of YES/NO **ERC-1155** tokens issued by the Conditional Token Framework (CTF), collateralized 1:1 in USDC. Off-chain CLOB matching, on-chain settlement, **zero taker fees**. Prices are in [0.00, 1.00] USDC; YES + NO ≈ 1.0 per market.

---

> **Before you write any API code — read the live docs first.**

>

> - Docs: https://docs.polymarket.com

> - Official Python SDK: https://github.com/Polymarket/py-clob-client

>

> Polymarket endpoints and auth flows have changed without notice. Prefer the official py-clob-client SDK over hand-rolled HTTP; it handles EIP-712 derivation, API credential management, and order signing. Only hand-roll when the SDK doesn't expose what you need.

---

Polymarket exchange mechanics — on-chain Polygon CTF, Gamma/CLOB/Data APIs, EIP-712 auth, identifier model, WebSocket, settlement, and geo/KYC constraint

Polymarket API

Polymarket is a **prediction market on Polygon mainnet**. Every market is a pair of YES/NO **ERC-1155** tokens issued by the Conditional Token Framework (CTF), collateralized 1:1 in USDC. Off-chain CLOB matching, on-chain settlement, **zero taker fees**. Prices are in [0.00, 1.00] USDC; YES + NO ≈ 1.0 per market.

---

> **Before you write any API code — read the live docs first.**

>

> - Docs: https://docs.polymarket.com

> - Official Python SDK: https://github.com/Polymarket/py-clob-client

>

> Polymarket endpoints and auth flows have changed without notice. Prefer the official py-clob-client SDK over hand-rolled HTTP; it handles EIP-712 derivation, API credential management, and order signing. Only hand-roll when the SDK doesn't expose what you need.

---

Identifier model

You will juggle four distinct IDs — get them confused and queries silently return wrong data.

| ID | What it is |

|----|-----------|

| condition_id | On-chain hex ID of the market (the CTF condition) |

| clob_token_ids | The YES/NO **pair** of ERC-1155 token IDs — a two-element list |

| token_id | A **single** outcome token — what you pass to order-book and WebSocket queries |

| event_id | Parent grouping (e.g. all brackets for "NYC high today") |

---

Quick Start

### 1. Read markets — Gamma API (no auth required)

import httpx

# CRITICAL: default sort is OLDEST-first — always override or you silently get closed markets
events = httpx.get("https://gamma-api.polymarket.com/events", params={
    "tag_id": 103040,        # category tag (e.g. weather)
    "order": "endDate",
    "ascending": "false",    # must be string "false", not bool
    "closed": "false",
}).json()

# Each event → markets[], each market has:
#   condition_id, clob_token_ids (YES/NO pair), question, outcomes, outcomePrices
for event in events:
    for mkt in event.get("markets", []):
        yes_token, no_token = mkt["clobTokenIds"]  # split the pair here
        print(mkt["question"], mkt["outcomePrices"])

**Pagination:** limit=100&offset=N, step by 100.

### 2. Order book and trading — CLOB API (EIP-712 auth)

uv pip install py-clob-client

import os
from py_clob_client.client import ClobClient

client = ClobClient(
    "https://clob.polymarket.com",
    chain_id=137,                                     # Polygon mainnet
    key=os.environ["POLYMARKET_PRIVATE_KEY"],          # wallet private key — env only, NEVER hardcode
    signature_type=2,                                  # 2 = Gnosis Safe proxy (Polymarket UI accounts)
                                                       # 0 = direct EOA you fully control
)
# Derives API key/secret/passphrase from the wallet signature — call once per session
client.set_api_creds(client.create_or_derive_api_creds())