AgentSkillsCN

polymarket

精通 Polymarket 预测市场 API。适用于实现 Polymarket 交易机器人、构建认证流程、探索市场动态、建立 WebSocket 连接,或排查 py-clob-client 相关问题。涵盖 CLOB API、Gamma API、Data API,以及诸如 USDC.e 与原生 USDC 的差异、订单约束条件,和各类生产场景下的特殊用例。

SKILL.md
--- frontmatter
name: polymarket
description: Polymarket prediction market API expertise. Use when implementing Polymarket trading bots, authentication flows, market discovery, WebSocket connections, or debugging py-clob-client issues. Covers CLOB API, Gamma API, Data API, edge cases like USDC.e vs native USDC, order constraints, and production patterns.

Polymarket API Skills

Complete knowledge base for Polymarket API integration using py-clob-client.

Quick Navigation

Navigate to the right module based on what you need:

NeedGo To
First time setup?auth/README.md - Credentials, wallet types, allowances
Finding markets?market-discovery/README.md - Gamma API, search, token IDs
Placing orders?trading/README.md - CLOB API, order types, management
Real-time data?real-time/README.md - WebSocket streams, orderbook
Analytics/positions?data-analytics/README.md - PnL, history, export
Something not working?edge-cases/README.md - Common pitfalls, solutions
Library patterns?library/README.md - Error handling, production code

Essential Context

Always-relevant reference information for Polymarket integration.

API Base URLs

APIURLPurpose
CLOBhttps://clob.polymarket.comTrading, orders, orderbook
Gammahttps://gamma-api.polymarket.comMarket discovery, metadata
Datahttps://data-api.polymarket.comPositions, balances, history
WebSocketwss://ws-subscriptions-clob.polymarket.com/ws/Real-time streams

Key Contract Addresses

ContractAddressPurpose
USDC.e0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174Trading currency
Conditional Tokens0x4D97DCd97eC945f40cF65F87097ACe5EA0476045Position tokens (ERC-1155)
CTF Exchange0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982EPrimary exchange
Neg Risk Exchange0xC5d563A36AE78145C45a50134d48A1215220f80aMulti-outcome exchange
Neg Risk Adapter0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296NegRisk adapter

Network

  • Chain: Polygon Mainnet
  • Chain ID: 137
  • RPC: https://polygon-rpc.com

Critical Warnings

The top 3 pitfalls that cause the most debugging time:

1. USDC.e, Not Native USDC

Polymarket uses USDC.e (bridged USDC), not Polygon's native USDC.

code
USDC.e:      0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174  <- Use this
Native USDC: 0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359  <- Wrong token

Symptom: Polygon wallet shows USDC balance, Polymarket shows $0.00 Solution: Swap native USDC to USDC.e via Polymarket or QuickSwap

See: edge-cases/usdc-token-confusion.md

2. FOK Order Precision

Fill-or-Kill orders require max 2 decimal places for size.

python
# Wrong - will fail with "invalid amounts"
order = OrderArgs(price=0.45, size=100.123, side=BUY, token_id=token_id)

# Correct
order = OrderArgs(price=0.45, size=100.12, side=BUY, token_id=token_id)

Fallback: If FOK fails on precision, use GTC which has no precision limits.

See: edge-cases/order-constraints.md

3. Proxy Wallet Funder Address

For proxy wallets (Magic/email login), use the proxy address as funder, not your EOA.

python
# Wrong - using EOA address
client = ClobClient(host, key, chain_id=137, signature_type=1, funder=eoa_address)

# Correct - using proxy address (from Polymarket profile)
client = ClobClient(host, key, chain_id=137, signature_type=1, funder=proxy_address)

Finding proxy address: Check your Polymarket profile - if the address differs from your EOA, that's your proxy.

See: auth/wallet-types.md

Quick Start Workflow

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

# 1. Initialize and authenticate
client = ClobClient(
    host="https://clob.polymarket.com",
    key="YOUR_PRIVATE_KEY",
    chain_id=137,
    signature_type=0,  # 0=EOA, 1=Proxy, 2=Safe
    funder="YOUR_WALLET_ADDRESS"
)
client.set_api_creds(client.create_or_derive_api_creds())

# 2. Discover markets (Gamma API - no auth needed)
events = requests.get("https://gamma-api.polymarket.com/events", params={
    "active": "true", "closed": "false", "limit": 10
}).json()
market = events[0]["markets"][0]
token_id = market["clobTokenIds"][0]  # YES token

# 3. Place order (CLOB API - authenticated)
order = client.create_order(OrderArgs(
    price=0.45, size=100.0, side=BUY, token_id=token_id
))
response = client.post_order(order, OrderType.GTC)
print(f"Order: {response.get('orderID')}")

Skill Modules

ModuleFilesTopics
auth/5 docsWallet types, credentials, allowances, client setup
market-discovery/4 docsGamma API, events, markets, search
trading/5 docsCLOB API, order types, placement, management
real-time/4 docsWebSocket, market/user channels, connection
data-analytics/4 docsPositions, history, prices, export
edge-cases/6 docsUSDC, constraints, pricing, resolution, negRisk
library/2 docsError handling, production patterns

Version

See VERSION.md for version history and API compatibility notes.