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:

Essential Context

Always-relevant reference information for Polymarket integration.

API Base URLs

Key Contract Addresses

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.

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.

# 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.

# 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

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

Version

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