polymarket

What this skill does

# Polymarket API

[Polymarket](https://polymarket.com) 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](https://docs.polymarket.com) _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:**

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