Skill: Polymarket Trading Setup

Use this skill when the user wants to:

• Set up automated trading on Polymarket
• Build a Polymarket trading bot from scratch
• Configure wallet, API credentials, or token approvals for Polymarket
• Understand how to connect to Polymarket's APIs
• Debug issues with an existing Polymarket bot setup

The full technical reference is in GUIDE.md (same directory as this file). Read it before starting.

What You're Setting Up

Polymarket trading requires four things in order:

1. A funded proxy wallet with USDC on Polygon
2. Token approvals (USDC spend approved for exchange contracts)
3. CLOB API credentials (derived from the wallet, stored in env)
4. Connectivity verified across all four API surfaces

Step-by-Step Agent Instructions

Step 1: Check What Already Exists

Before doing anything, check:

• Is there an .env file with POLYMARKET_PRIVATE_KEY and POLYMARKET_PROXY_ADDRESS?
• Is there a config.json with Polymarket settings?
• Is there an existing bot directory to work within?

If credentials already exist, load and validate them rather than starting from scratch.

Step 2: Environment Setup

If starting fresh, create a .env file with:

POLYMARKET_PRIVATE_KEY=0x...
POLYMARKET_PUBLIC_ADDRESS=0x...     # proxy wallet address
POLYMARKET_PROXY_ADDRESS=0x...      # same as PUBLIC_ADDRESS for type 2
POLYMARKET_SIGNATURE_TYPE=2
POLYMARKET_WEBSOCKET_URL=wss://ws-subscriptions-clob.polymarket.com
POLYMARKET_DATA_API=https://data-api.polymarket.com

The proxy wallet address comes from the user's Polymarket account settings page.

Step 3: Install Dependencies

pip install "py-clob-client>=0.28.0" httpx "websocket-client>=1.9.0" orjson pandas python-dotenv

Or add to pyproject.toml and run uv sync.

Step 4: Token Approvals

Via UI (recommended for new users): Deposit USDC through the Polymarket web app — approvals happen automatically.

Headless (server deployment): Use the programmatic approval flow from GUIDE.md Section 4. This requires Polymarket Builder API credentials (separate from CLOB creds).

The four contracts that need approval are listed in GUIDE.md Section 2.

Step 5: Derive and Persist API Credentials

from py_clob_client.client import ClobClient

client = ClobClient(
    "https://clob.polymarket.com",
    key=os.getenv("POLYMARKET_PRIVATE_KEY"),
    chain_id=137,
    signature_type=int(os.getenv("POLYMARKET_SIGNATURE_TYPE", "2")),
    funder=os.getenv("POLYMARKET_PROXY_ADDRESS"),
)
creds = client.derive_api_key()
# Write credentials to .env — do not log or print them

Add to .env:

POLYMARKET_API_KEY=...
POLYMARKET_API_SECRET=...
POLYMARKET_API_PASSPHRASE=...

On subsequent startups, load from env instead of re-deriving (see GUIDE.md Section 3).

Step 6: Verify Connectivity

Test each surface in order. Stop and diagnose if any step fails.

import httpx, json