polymarket-skill/SKILL.md

---
name: polymarket
description: >-
  Interact with the Polymarket prediction-market APIs (Gamma, Data, CLOB,
  Bridge, Relayer) from Python: browse and search Polymarket markets and events;
  read prices, order books, midpoints, spreads and price history; look up a
  wallet's positions, trades, activity, PnL, holders, leaderboard, open interest
  and liquidity-mining rewards; and place, cancel or query real CLOB orders.
  Trigger whenever the user wants Polymarket market data or wants to trade on
  Polymarket, even without naming an endpoint — including Chinese requests like
  查询/看 Polymarket 的行情、赔率、订单簿、持仓、成交、盈亏、排行榜、奖励，或下单/
  挂单/撤单/交易; answer in Chinese when the user writes in Chinese. Specific to
  Polymarket: do NOT use for other venues (Kalshi, DraftKings/sportsbooks,
  Binance, Coinbase, Robinhood), for conceptual questions about how prediction
  markets work or their legality, or for pure opinion/comparison of platforms.
---

# Polymarket API

A Python client (`scripts/polymarket.py`) covering the full Polymarket REST
surface. Public read endpoints use plain HTTP; authenticated **trading** is
delegated to the official `py_clob_client_v2` (the docs recommend it —
hand-rolling EIP-712 order signing risks real funds).

When the user writes in Chinese, answer in Chinese (tables, labels, and summary
in 中文); keep API field names, token ids, and command snippets as-is.

## The four+1 APIs

| API | Base URL | Auth | What it has |
|-----|----------|------|-------------|
| Gamma | gamma-api.polymarket.com | none | markets, events, tags, series, comments, sports, search, public profiles |
| Data | data-api.polymarket.com | none | positions, trades, activity, holders, value, leaderboard, open interest |
| CLOB (public) | clob.polymarket.com | none | order book, price, midpoint, spread, tick size, price history, markets |
| CLOB (trade) | clob.polymarket.com | L1+L2 | place / cancel / query orders, balances, API keys |
| Bridge / Relayer | bridge / relayer-v2 | varies | deposits, withdrawals, proxy-wallet tx |

## Setup

```bash
pip install requests            # public endpoints
pip install py_clob_client_v2   # only needed for authenticated trading (official v2 SDK)
```

## Reading data (no auth) — use the CLI

The fastest path. Every public method is exposed as `<api>.<method>`:

```bash
cd scripts
python polymarket.py list-commands                      # see everything
python polymarket.py gamma.list_markets --json '{"limit":5,"closed":false}'
python polymarket.py gamma.search --q "election"
python polymarket.py gamma.get_event_by_slug --slug some-event-slug
python polymarket.py clob.order_book --token_id 7193...        # full book
python polymarket.py clob.midpoint --token_id 7193...
python polymarket.py clob.prices_history --market 7193... --json '{"interval":"1d","fidelity":60}'
python polymarket.py data.positions --user 0xABC... --json '{"limit":50}'
python polymarket.py data.trades --json '{"user":"0xABC...","limit":20}'
python polymarket.py data.leaderboard --json '{"window":"7d","limit":10}'
```

Pass simple flags as `--key value`; pass anything structured (numbers, bools,
lists, multiple params) as one `--json '{...}'`. Both can be combined.

Key id concepts the user will hand you:
- **slug** — human URL fragment of an event/market.
- **condition_id** — identifies a market (a yes/no question) on-chain.
- **token_id (clob)** — the ERC1155 asset id of *one outcome* (YES or SELL side).
  Order book / price / midpoint / price-history all key on token_id.

To go from a market to its token ids: `gamma.list_markets` / `gamma.get_market`
return `clobTokenIds`. Use those with the `clob.*` pricing calls.

## Reading data from Python

```python
import sys; sys.path.insert(0, "scripts")
from polymarket import GammaClient, DataClient, ClobPublicClient
g = GammaClient()
markets = g.list_markets(limit=10, closed=False, order="volume24hr", ascending=False)
book = ClobPublicClient().order_book(token_id="7193...")
pos = DataClient().positions(user="0xABC...", limit=100)
```

## Trading (authenticated — real money)

Trading needs the user's wallet private key, so it runs from Python with env
vars, never through the flat CLI. **Before placing any order, confirm with the
user the token_id, side, price, and size** — these move real funds and are not
easily reversible.

```bash
export PK=0xYOUR_PRIVATE_KEY
export POLY_PROXY_ADDRESS=0xYOUR_PROXY   # if using a Polymarket proxy wallet
```

```python
from polymarket import TradingClient
t = TradingClient()                      # auto-derives L2 API creds on first run

# Limit order: buy 10 shares of outcome token at $0.42
t.create_and_post_order(token_id="7193...", price=0.42, size=10, side="BUY",
                        order_type="GTC")

# Market order by USDC amount
t.create_and_post_market_order(token_id="7193...", amount=20, side="BUY")

t.get_open_orders()                # open orders
t.cancel_order(payload="0x...")    # cancel one
t.cancel_all()                     # cancel everything
t.get_trades()                     # your fills
t.get_balance_allowance()

# L2-authenticated rewards / rebates (read-only, signed for you)
t.rewards_user_earnings(date="2026-06-22")
t.rebates_current(date="2026-06-22", maker_address="0x...")
```

`TradingClient` wraps the official **v2** SDK (`py_clob_client_v2`): L1 (EIP-712)
order signing and L2 (HMAC-SHA256 `POLY_*` headers) are handled automatically.
The user-scoped rewards/rebates GETs aren't exposed by the SDK, so the skill
signs those L2 requests itself. Set `POLY_SIGNATURE_TYPE` (0 EOA / 1 proxy /
2 gnosis-safe) if you hit balance/allowance errors. See `references/trading.md`.

## When you need an endpoint that isn't obvious

`references/endpoints.md` maps every documented Polymarket endpoint to its
client method and notes the exact query parameters. Read it when the user asks
for something specific (rewards, rebates, combo markets, builder analytics,
maker quotes, accounting snapshots) so you call the right method with the right
params. These tools hit **undocumented-stability** internal APIs and can change;
if a call 404s, check the live path in `references/endpoints.md` and the docs at
https://docs.polymarket.com/api-reference.