polymarket-api · agiprolabs — Claude Code skill: prediction market trading
Skill for Polymarket API integration, a decentralized prediction exchange on Polygon blockchain. Access market data, order books, and settlement mechanics through Gamma, CLOB, and Data APIs.
MIT 351 installs ★ 582 updated 2026-09-03
npx skills add agiprolabs/claude-trading-skills --skill polymarket-api -a claude-codeWhat polymarket-api does
Polymarket is a prediction market on Polygon mainnet where every contract is a YES/NO token pair (ERC-1155) backed 1:1 by USDC. Prices range from 0.00 to 1.00 USDC with zero taker fees. This skill covers the full stack: Gamma API for market metadata (no auth), CLOB API for order books with EIP-712 signatures, Data API for trade history, and WebSocket for real-time updates.
The core challenge is the identifier model—you must distinguish between condition_id (on-chain contract hash), clob_token_ids (YES/NO token pair), token_id (single outcome for book queries), and event_id (market grouping). Mixing them silently returns wrong data. The skill uses the official py-clob-client SDK, which handles API key derivation, credential management, and order signing; hand-rolling EIP-712 is error-prone.
A second constraint is geography: API access from the US is blocked; you need a SOCKS5 proxy. After market resolution, winning tokens must be manually redeemed on-chain via redeemPositions()—they don't auto-transfer to your wallet. Weather settlement ties to the metro's local timezone with DST conversion, unlike Kalshi which uses LST without adjustment.
What it helps with
- build a trading bot on Polymarket using py-clob-client SDK
- fetch current prices and order book for a specific prediction market
- sign and submit a buy/sell order through EIP-712 to the CLOB
- subscribe to price updates and trade ticks in real-time over WebSocket
- map market identifiers correctly—condition_id to token_id to clob_token_ids
Example prompts for the agent
- List all open weather markets and sort by trading volume
- Sign an order to buy YES tokens at 0.65 USDC for condition_id XYZ
- Connect to WebSocket and log every price change for token ABC
How to install polymarket-api
1Skills CLI (Vercel)
npx skills add agiprolabs/claude-trading-skills --skill polymarket-api -a claude-code2Manually: put the files in place
~/.claude/skills/polymarket-api/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/polymarket-api/
1Skills CLI (Vercel)
npx skills add agiprolabs/claude-trading-skills --skill polymarket-api -a codex2Manually: put the files in place
.agents/skills/polymarket-api/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add agiprolabs/claude-trading-skills --skill polymarket-api -a cursor2Manually: put the files in place
.cursor/skills/polymarket-api/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install agiprolabs/claude-trading-skills skills/polymarket-api2Manually: put the files in place
.github/skills/polymarket-api/SKILL.md1Skills CLI (Vercel)
npx skills add agiprolabs/claude-trading-skills --skill polymarket-api -a gemini-cli2Platform CLI
gemini skills install https://github.com/agiprolabs/claude-trading-skills --path skills/polymarket-apiManually: put the files in place
.devin/skills/polymarket-api/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add agiprolabs/claude-trading-skills --skill polymarket-api -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about polymarket-api
How do I install polymarket-api in Claude Code?
Run npx skills add agiprolabs/claude-trading-skills --skill polymarket-api -a claude-code, then open ~/.claude/skills/polymarket-api/SKILL.md for full API docs and code examples.
What does polymarket-api do?
It provides access to all Polymarket APIs: market metadata (Gamma, unauthenticated), order book and order placement (CLOB with EIP-712), trade history (Data API), and real-time subscriptions (WebSocket). Built on the official py-clob-client SDK.
How does Polymarket differ from Kalshi?
Polymarket is on-chain with UMA oracle settlement (dispute risk exists), while Kalshi is traditional exchange with CFTC-CCP clearing. Polymarket resolves weather via local timezone with DST through Weather Underground; Kalshi uses LST without DST via NWS.
Source text
SKILL.md · MIT
---
name: polymarket-api
description: 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)
```python
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)
```bash
uv pip install py-clob-client
```
```python
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())
token_id = "<yes_token_from_clob_token_ids>"
book = client.get_order_book(token_id) # bids/asks for one outcome token
price = client.get_price(token_id, side="BUY")
```
`signature_type=2` is for the proxy/Safe accounts the Polymarket web UI creates (the funder address is the Safe). Use `signature_type=0` for a raw EOA you control directly. Read the live SDK docs — the type you choose affects how orders are signed on-chain.
Wallet env vars: `POLYMARKET_PRIVATE_KEY`, `POLYMARKET_FUNDER`. Never hardcode keys.
---
## API surface overview
| API | Host | Auth | Purpose |
|-----|------|------|---------|
| Gamma | `https://gamma-api.polymarket.com` | none | Events/markets/conditions/prices metadata |
| CLOB | `https://clob.polymarket.com` | EIP-712 | Order book, order placement/cancel |
| Data | `https://data-api.polymarket.com` | none | Historical trades |
| WebSocket | `wss://ws-subscriptions-clob.polymarket.com/ws/` | none (market) / JWT (user) | Real-time book + trade ticks |
Chain: Polygon mainnet `chain_id=137`. Collateral: USDC.e at `0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174`.
---
## WebSocket
```python
# Connect to: wss://ws-subscriptions-clob.polymarket.com/ws/market
# Subscribe message:
{"type": "market", "assets_ids": ["<token_id>", "<token_id2>"]}
```
Event types: `book` (full snapshot on subscribe), `price_change` (delta updates), `last_trade_price`.
For user-level order/fill events, connect to `/ws/user` with a JWT derived from your API credentials.
---
## On-chain settlement and redemption
Polymarket weather markets resolve via **Weather Underground** ("History" tab), on the metro's **local clock with DST**, midnight-to-midnight. This differs from Kalshi, which uses LST (no DST) and NWS CLI — see `kalshi-weather-markets` for the divergence.
After resolution, winning tokens **must be redeemed manually on-chain**:
```python
# Call CTF contract redeemPositions() — the SDK or direct web3.py call
# Winnings are NOT auto-swept to your wallet
```
Disputes on the international book escalate to the **UMA optimistic oracle** (token-holder vote). This is a real resolution-divergence risk vs. Kalshi's CFTC-CCP settlement — factor it into any cross-venue comparison.
---
## US geo / KYC constraint
US persons are **blocked** from Polymarket. API calls from a US IP typically require a **SOCKS5 proxy** from an allowed jurisdiction (use a `USE_PROXY` env flag pattern; never hardcode the proxy address). This constraint — combined with on-chain capital lockup and USDC/USD friction — is why most Kalshi/Polymarket arbitrage is not executable at retail scale.
---
## Cross-references
- For strategy, sizing, and backtesting that apply across venues: `prediction-market-strategy`
- For the Kalshi counterpart (RSA-PSS auth, REST host, tickers, order schema): `kalshi-api`
- For weather settlement specifics (WU local-clock+DST vs Kalshi LST, KLGA vs KNYC station): `kalshi-weather-markets`
---
## Files
### References
- `references/clob-and-gamma-apis.md` — Full API surface, all endpoints, EIP-712 auth detail, pagination, order schema, trading-parameter defaults
- `references/settlement-and-ops.md` — WU/UMA resolution, `redeemPositions`, truth-source priority (IEM > WU > Open-Meteo), known-bad dates, geo/KYC, host-segregation, two-exchange architecture notes
© agiprolabs · MIT · agiprolabs/claude-trading-skills
Similar skills
All skills for Finance and business →polymarket-api by other authors comes first.