Agent skill for building on Polymarket — the world's largest prediction market. Gives agents the knowledge to authenticate, place orders, read markets, stream real-time data, manage positions, bridge assets across chains, and execute gasless transactions.
web3-polymarket/
├── SKILL.md # Entry point — quick reference, client setup, core patterns
├── README.md # This file
├── authentication.md # L1/L2 auth, builder headers, credential lifecycle
├── order-patterns.md # Order types, tick sizes, cancel, heartbeat, errors
├── market-data.md # Gamma API, Data API, CLOB orderbook, subgraph
├── websocket.md # Market/user/sports channels, subscribe, heartbeat
├── ctf-operations.md # Split, merge, redeem, negative risk, token IDs
├── bridge.md # Deposits, withdrawals, supported chains/tokens
└── gasless.md # Relayer client, wallet deployment, builder setup
The skill uses progressive disclosure to stay efficient with context:
- SKILL.md loads first — contains API endpoints, contract addresses, client setup, and core code patterns. Enough for most tasks.
- Reference files load on demand — when a task needs deeper detail (e.g., full error code list, bridge chain support, WebSocket event schemas), the agent reads the relevant file.
This keeps the initial context small (~200 lines) while giving access to ~1,700 lines of detailed reference material when needed.
An agent activates this skill when a user asks about:
- Authentication — API keys, EIP-712 signing, HMAC-SHA256, builder credentials
- Trading — placing limit/market orders (GTC, GTD, FOK, FAK), batch orders, cancellation, heartbeat keepalive
- Market data — fetching events/markets from Gamma API, reading orderbook prices/spreads/midpoints, price history
- Real-time data — WebSocket subscriptions for orderbook updates, trade notifications, sports scores
- Token operations — splitting USDC.e into Yes/No tokens, merging, redeeming after resolution
- Bridging — depositing from 15+ chains, withdrawing, checking status
- Gasless transactions — relayer client for gas-free onchain operations
- Negative risk — multi-outcome markets, token conversion, augmented neg risk
If you're a developer reading this directly (not an agent), here's the fastest path:
# TypeScript
npm install @polymarket/clob-client ethers@5.8.0
# Python
pip install py-clob-clientimport { ClobClient } from "@polymarket/clob-client";
import { Wallet } from "ethers";
const client = new ClobClient(
"https://clob.polymarket.com",
137,
new Wallet(process.env.PRIVATE_KEY)
);
const creds = await client.createOrDeriveApiKey();const tradingClient = new ClobClient(
"https://clob.polymarket.com",
137,
signer,
creds,
2, // GNOSIS_SAFE (most common)
"FUNDER_ADDR" // from polymarket.com/settings
);
const response = await tradingClient.createAndPostOrder(
{ tokenID: "TOKEN_ID", price: 0.50, size: 10, side: "BUY" },
{ tickSize: "0.01", negRisk: false },
"GTC"
);| Concept | Description |
|---|---|
| USDC.e | Bridged USDC on Polygon — the collateral token for all markets |
| Condition ID | Identifies a market (used in API as market or conditionID) |
| Token ID | Identifies a specific outcome token (Yes or No) within a market |
| Funder | The proxy wallet address that holds funds — find at polymarket.com/settings |
| Signature Type | 0 = EOA, 1 = POLY_PROXY (Magic Link), 2 = GNOSIS_SAFE (most common) |
| Neg Risk | Multi-outcome markets where outcomes are linked — set negRisk: true in order options |
| Tick Size | Minimum price increment for a market — must match or orders are rejected |
| API | Base URL | Auth Required |
|---|---|---|
| CLOB | https://clob.polymarket.com |
L2 headers for trades, none for reads |
| Gamma | https://gamma-api.polymarket.com |
None |
| Data | https://data-api.polymarket.com |
None |
| Bridge | https://bridge.polymarket.com |
None |
| Relayer | https://relayer-v2.polymarket.com/ |
Builder headers |
| WS Market | wss://ws-subscriptions-clob.polymarket.com/ws/market |
None |
| WS User | wss://ws-subscriptions-clob.polymarket.com/ws/user |
API creds in message |
| WS Sports | wss://sports-api.polymarket.com/ws |
None |
| Contract | Address |
|---|---|
| USDC.e (Bridged USDC) | 0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174 |
| CTF | 0x4D97DCd97eC945f40cF65F87097ACe5EA0476045 |
| CTF Exchange | 0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E |
| Neg Risk CTF Exchange | 0xC5d563A36AE78145C45a50134d48A1215220f80a |
| Neg Risk Adapter | 0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296 |
| File | Read when you need to... |
|---|---|
| SKILL.md | Get started — has everything for basic integration |
| authentication.md | Understand L1/L2 auth flow, builder headers, or troubleshoot credential issues |
| order-patterns.md | Use advanced order types (GTD, post-only, batch), handle errors, or implement heartbeat |
| market-data.md | Query markets by slug/tag, paginate results, use subgraph, or estimate fill prices |
| websocket.md | Stream real-time orderbook updates, trade notifications, or sports scores |
| ctf-operations.md | Split/merge/redeem tokens, work with neg risk markets, or compute token IDs |
| bridge.md | Deposit from other chains, withdraw, check supported assets, or track transaction status |
| gasless.md | Set up gas-free transactions via the relayer, deploy wallets, or configure builder credentials |
- TypeScript: @polymarket/clob-client
- Python: py-clob-client
- Rust: rs-clob-client
- Builder Relayer (TS): @polymarket/builder-relayer-client
- Builder Relayer (Python): py-builder-relayer-client
- Builder Signing (TS): @polymarket/builder-signing-sdk
- Builder Signing (Python): py-builder-signing-sdk