polymarket-skill/SKILL.md

name

description

polymarket

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

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>:

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

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.

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

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.