polymarket

Files (3)

• SKILL.md
• evals.json · evals/
• smoke_test.py · scripts/

SKILL.md (first lines)

# Polymarket

Two-tier API surface: the unauthenticated **Gamma API** for market discovery and metadata, and the **CLOB API** for live order books, prices, the user's authenticated state (positions, orders, balances), and order placement.

**Order placement is gated behind explicit user instruction.** Reads (markets, books, history, balances) can happen freely as part of research. Writes (place, modify, cancel orders) only happen when the user has asked for a specific action — never as a side effect of analysis, never proactively. If the user's request is ambiguous (size, side, market, price unclear), echo the proposed order back and confirm before signing.

## Which API to use

| Need | API | Auth required? |
|---|---|---|
| Find markets by topic, tag, slug, status | Gamma | No |
| Market metadata (description, end date, outcomes) | Gamma | No |
| Live order book / spread / depth | CLOB `/book/{token_id}` | No |
| Best bid/ask | CLOB `/price/{token_id}` | No |
| Historical prices | CLOB `/prices-history` | No |
| User's own positions, orders, fills, balance | CLOB | **Yes** |
| Place / modify / cancel an order | CLOB | **Yes** |

Default to Gamma for discovery and CLOB only when you need live book data or user state. Gamma is friendlier (richer metadata, simple filters) and avoids any auth setup.

## One-time setup

Polymarket migrated to **CLOB V2** on April 28, 2026 — V1-signed orders are now rejected with `order_version_mismatch`. We use `py-clob-client-v2` for trading and reads, plus the legacy `py-clob-client` for one specific thing: deriving API credentials, because V2's `/auth/api-key` endpoint is Cloudflare-blocked while V1's still works (the L2 creds are deterministic from the wallet sig, so they're interchangeable across versions).

A dedicated venv at `~/.venvs/polymarket/` is required (macOS Homebrew Python is PEP 668):

```bash
python3 -m venv ~/.venvs/polymarket
~/.venvs/polymarket/bin/pip install --upgrade pip py-clob-client py-clob-client-v2
```

Always invoke Python through the venv's interpreter:

```bash
~/.venvs/polymarket/bin/python your_script.py
```

For unauthenticated reads (Gamma), the venv isn't strictly needed — `requests` from system Python works fine. The venv only matters for the CLOB clients.

For authenticated reads (positions, orders, balance), the user needs these env vars set in their shell:

| Var | What it is |
|---|---|
| `POLYMARKET_PRIVATE_KEY` | Polygon EOA private key (hex, no `0x` required by client) |
| `POLYMARKET_FUNDER` | Address of the user's Polymarket proxy wallet (the address shown in the Polymarket UI) |
| `POLYMARKET_SIGNATURE_TYPE` | `1` for the standard Polymarket proxy wallet (most users); `0` for direct EOA; `2` for Magic/email-login proxy |
| `POLYMARKET_HOST` | Optional, defaults to `https://clob.polymarket.com` |

If any of these are missing when an auth'd read is requested, stop and tell the user which one to set rather than guessing — silently failing wastes their time. Never log or echo `POLYMARKET_PRIVATE_KEY` in any output.

## Gamma — market discovery

Base URL: `https://gamma-api.polymarket.com`. Public, no auth. Hit it with `requests`.

Common endpoints:
- `GET /markets` — list/filter markets. Useful params: `active=true`, `closed=false`, `archived=false`, `limit` (default 100), `offset`, `order` (e.g. `volume24hr`), `ascending=false`, `tag_id`, `slug`.
- `GET /markets/{id}` — single market by id (numeric) or slug.
- `GET /events` — events grouping multiple related markets (e.g. an election with one market per candidate).
- `GET /events/{slug}` — single event with all its markets.

Each market exposes `clobTokenIds` — a JSON-encoded list of two token IDs (one per outcome, typically YES and NO). You'll need the right token id to query CLOB endpoints.

Pattern: search markets by keyword + active filter, sort by 24h volume to find the live ones.

```python
import requests

resp = requests.get(
    "https://gamma-api.polymarket.com/markets",
    params={
        "active": "true",
        "closed": "false",
        "limit": 20,
        "order": "volume24hr",
        "ascending": "false",
    },
    timeout=10,
)
resp.raise_for_status()
markets = resp.json()
for m in markets:
    print(m["question"], "→", m.get("volume24hr"), "vol24h")
```

For a topical search, filter client-side on `question` / `description` substring — Gamma's full-text search is limited.

## CLOB — public reads (no auth)

Base URL: `https://clob.polymarket.com`. Use `py-clob-client-v2` without creds for clean reads, or hit endpoints directly with `requests`.

```python
from py_clob_client_v2 import ClobClient
from py_clob_client_v2.constants import POLYGON

client = ClobClient("https://clob.polymarket.com", chain_id=POLYGON)

# Order book for a token (token_id from Gamma's clobTokenIds)
book = client.get_order_book(token_id)
# In V2, book is a dict: {"bids": [{"price": "...", "size": "..."}, ...], "asks": [...]}
# (V1 returned a dataclass — V2 returns dicts for most read responses.)

# Best price for a side
price = client.get_price(token_id, side="BUY")  # what you'd pay to buy

# Historical prices
hist = client.get_prices_history(market=token_id, interval="1h", fidelity=60)
```

When a market has two outcomes (YES/NO), prices are complementary (`p_yes + p_no ≈ 1`) but the books are separate — quote both if the user is asking about implied probability.

## CLOB — authenticated reads (user state)

Bootstrap pattern: derive L2 creds via the V1 client (its endpoint isn't Cloudflare-blocked), then plug them into a V2 client for everything else. Creds are deterministic from the wallet, so they're interchangeable.

```python
import os
from py_clob_client.client import ClobClient as V1Client
from py_clob_client.constants import POLYGON as POLYGON_V1
from py_clob_client_v2 import ApiCreds, ClobClient

From byronxlg/skills, MIT.

More from byronxlg/skills