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