Polymarket Trading Setup

Set up automated trading on Polymarket. Covers wallet setup, token approvals, API authentication, market discovery, order placement, WebSocket feeds, and pos...

Security Scan

The skill's requirements and instructions are coherent with setting up a Polymarket trading bot; the environment variables and guidance align with that purpose, with only a few minor documentation mismatches to be aware of.

Purpose & Capability

The name/description (Polymarket trading setup) align with the requested secrets and runtime actions: a signing private key, proxy wallet address, signature type, and derived CLOB API credentials are all expected for programmatic trading on Polymarket. Optional Builder credentials for headless token approvals are also reasonable for server deployments.

Instruction Scope

The SKILL.md gives explicit step-by-step instructions to check for and read/write a .env and config.json, derive API credentials, call Polymarket endpoints (Gamma, CLOB, Data, WebSocket), and submit token approvals. Those actions are within the stated setup task. Note: the agent is told to look for an “existing bot directory” which could lead it to inspect unrelated files in the working directory — this is broad but not necessarily malicious. Also the SKILL.md references POLYMARKET_WEBSOCKET_URL and POLYMARKET_DATA_API (and other example values) that are used in examples but are not listed in the metadata's required env list (minor inconsistency).

Install Mechanism

This is instruction-only with no install spec or downloadable artifacts. That minimizes install-time risk; dependencies referenced (py-clob-client, httpx, websocket-client, etc.) are plausible and standard for Python-based trading bots.

Credentials

The required environment variables (private key, proxy address, signature type, and derived API key/secret/passphrase) are proportionate to the stated function. Caveat: SKILL.md also uses POLYMARKET_WEBSOCKET_URL and POLYMARKET_DATA_API in examples but these are not listed among required env in the metadata — an inconsistency a user should be aware of. The skill requests highly sensitive secrets (private key and API secret) which are legitimately required for trading but demand secure handling.

Persistence & Privilege

The skill does not request always:true and makes no claims about modifying other skills or system-wide settings. It instructs persisting derived API credentials into a local .env file — normal for this use-case but worth protecting (avoid committing to VCS, restrict filesystem permissions).

Assessment

This skill appears to be what it says: a how-to for setting up a Polymarket trading bot. Before installing or running it, consider the following: - It requires your signing private key and derived API secrets — these are extremely sensitive. Only proceed if you trust the skill source and you run it in an isolated, secure environment. - The skill will (and instructs the agent to) read and write a local .env file and may inspect any existing bot/config folders in the working directory; review those commands first to avoid accidental exfiltration of unrelated secrets. - The metadata omits a couple of example env variables used in the guide (POLYMARKET_WEBSOCKET_URL, POLYMARKET_DATA_API). Expect to need those or to hardcode endpoints in code examples. - Prefer performing token approvals manually via the Polymarket UI if you are unsure about programmatic approvals; the guide notes bounded approvals are safer than unbounded approvals. - Store derived API credentials securely (do not commit .env to version control), consider role-restricted or ephemeral credentials where possible, and limit approval amounts on token allowances. - If you want additional assurance, review the referenced py-clob-client library code (or vendor it from an official release) rather than blindly executing the example code. If any of these points make you uncomfortable, do not run the skill or run it in a sandboxed workstation/VM and manually inspect every step before providing credentials.

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

# 1. Gamma API
event = httpx.get("https://gamma-api.polymarket.com/events/slug/bitcoin-price-on-february-11").json()
print(f"Gamma OK: {event.get('title')}")

# 2. CLOB REST - order book
book = httpx.get("https://clob.polymarket.com/book", params={"token_id": "<any_token_id>"}).json()
print(f"CLOB OK: {len(book.get('bids', []))} bids, {len(book.get('asks', []))} asks")

# 3. Data API - positions
positions = httpx.get(
    "https://data-api.polymarket.com/positions",
    params={"user": os.getenv("POLYMARKET_PROXY_ADDRESS")}
).json()
print(f"Data API OK: {len(positions)} open positions")

Step 7: Place a Test Order

Place a 2-share order at a far-from-market price (very low probability on a real market) to verify the full signing and posting flow without risk of a fill:

from py_clob_client.clob_types import OrderArgs, OrderType
from py_clob_client.order_builder.constants import BUY

# Use a real token ID from Step 6, price far from market
order = OrderArgs(price=0.02, side=BUY, size=2, token_id="<token_id>")
signed = client.create_order(order)
resp = client.post_order(signed, OrderType.FAK)
print(resp)  # Should show success: true

---

Key Facts to Remember

• Chain: Polygon mainnet (ID: 137)
• Currency: USDC (0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359)
• Signature type 2 is standard for programmatic trading
• Proxy address ≠ signing key address — positions live on proxy, orders signed by EOA
• clobTokenIds[0] = YES, clobTokenIds[1] = NO — never mix these up
• Minimum order value: $1.00 — size * price >= 1.0
• Order size must be integer — always int()
• Update positions only on MINED, not MATCHED — MATCHED can fail

---

Common First-Time Failures

Symptom	Likely Cause
insufficient balance	Wrong address used (EOA instead of proxy), or USDC not deposited
Order silently rejected	Price has too many decimal places — round to 2dp (or 3dp if price < 0.04 or > 0.96)
Order value error	size * price < 1.0
WebSocket never sends data	Wrong subscription message format, or using array instead of object
Positions always empty	Querying EOA address instead of proxy wallet address
Stale positions after trade	Updating on MATCHED instead of MINED

---

Reference

Full API reference, all code patterns, and detailed explanations: GUIDE.md (same directory).