Polymarket API Recipes: Copy-Paste Snippets (V2, Python)

API · Build

Copy-paste recipes for the things every Polymarket bot needs. All CLOB V2 / pUSD, Python (the reads need no key). Grab one, run it, move on. Run any read live in the sandbox first:

1. Get a market's token IDs from a slug

Every trade starts here: a human slug in, the two outcome token IDs out.

import requests, json
m = requests.get("https://gamma-api.polymarket.com/markets",
                 params={"slug": SLUG}).json()[0]
outcomes  = json.loads(m["outcomes"])       # ["Yes","No"]
token_ids = json.loads(m["clobTokenIds"])   # aligned with outcomes
yes_token = token_ids[outcomes.index("Yes")]
tick_size = m.get("orderPriceMinTickSize", "0.01")   # use this, don't hardcode
neg_risk  = bool(m.get("negRisk", False))            # needed for multi-outcome markets

2. Derive your API credentials (one time)

Trading needs an API key/secret/passphrase derived from your private key. Derive once, then pass creds to every client - there is no set_api_creds in V2.

import os
from py_clob_client_v2 import ClobClient
boot = ClobClient(host="https://clob.polymarket.com", chain_id=137, key=os.environ["PK"])
creds = boot.create_or_derive_api_key()      # idempotent: same key -> same creds
client = ClobClient(host="https://clob.polymarket.com", chain_id=137,
                    key=os.environ["PK"], creds=creds)

3. Read the book & estimate slippage

Walk the asks to get the real average fill price for a buy (bids for a sell) before you commit size.

book = client.get_order_book(token_id)
def cost_to_buy(book, shares):
    rem, spent = shares, 0.0
    for lvl in book.asks:                     # asks sorted best (lowest) first
        take = min(rem, float(lvl.size)); spent += take*float(lvl.price); rem -= take
        if rem <= 0: break
    return (spent/shares, rem)                 # (avg fill price, unfilled shares)

4. Place & cancel a limit order (GTC)

from py_clob_client_v2 import (ClobClient, OrderArgs, OrderType,
                               PartialCreateOrderOptions, Side, OrderPayload)
resp = client.create_and_post_order(
    order_args=OrderArgs(token_id=token_id, price=0.45, side=Side.BUY, size=100),
    options=PartialCreateOrderOptions(tick_size=tick_size, neg_risk=neg_risk),
    order_type=OrderType.GTC,                 # rests on the book until filled/cancelled
)
client.cancel_order(OrderPayload(orderID=resp["orderID"]))

5. Take liquidity now - a market order (FOK)

A market order is sized in USDC, not shares, and fills immediately or cancels. Use FOK when you must be filled in full, FAK to fill what you can.

from py_clob_client_v2 import MarketOrderArgs
client.create_and_post_market_order(
    order_args=MarketOrderArgs(token_id=token_id, amount=25.0, side=Side.BUY),  # $25
    options=PartialCreateOrderOptions(tick_size=tick_size, neg_risk=neg_risk),
    order_type=OrderType.FOK,
)

6. List, batch-post, and cancel orders

orders = client.get_orders()                  # your resting orders
client.cancel_orders([o["orderID"] for o in orders])   # cancel a batch
client.cancel_all()                           # or wipe everything (panic button)

# Post several quotes in ONE request (POST /orders, max 15 per batch).
# post_only=True makes each strictly a maker order - it's rejected rather than
# allowed to cross the book, so you never accidentally pay the taker fee.
client.create_and_post_orders([
    OrderArgs(token_id=token_id, price=0.44, side=Side.BUY,  size=50),
    OrderArgs(token_id=token_id, price=0.48, side=Side.SELL, size=50),
], options=PartialCreateOrderOptions(tick_size=tick_size, neg_risk=neg_risk, post_only=True))

7. Track any wallet's positions & PnL (no key)

import requests
for p in requests.get("https://data-api.polymarket.com/positions",
                      params={"user": PROXY_ADDRESS}).json():
    print(p["title"], p["outcome"], "PnL", p["cashPnl"], p["percentPnl"])

8. Watch your fills over WebSocket

# wss://ws-subscriptions-clob.polymarket.com/ws/user  (auth: api key/secret/passphrase)
# subscribe by condition_id; you get fills/cancels for your orders in real time.
# Send a PING every ~10s or the server drops you. Full reconnect+heartbeat pattern:
#   /en/api/polymarket-websocket/

9. A minimal market-maker tick

mid = float(client.get_midpoint(token_id)["mid"])
spread = 0.02                                  # quote 1 cent each side of mid
bid = round(mid - spread/2, 2); ask = round(mid + spread/2, 2)   # round to tick
for price, side in [(bid, Side.BUY), (ask, Side.SELL)]:
    client.create_and_post_order(
        order_args=OrderArgs(token_id=token_id, price=price, side=side, size=50),
        options=PartialCreateOrderOptions(tick_size=tick_size, neg_risk=neg_risk),
        order_type=OrderType.GTC)
# reprice on every book update; makers pay 0 fees and can earn liquidity rewards.

New project? Polymarket now ships a unified SDK (py-sdk / @polymarket/sdk) that folds the REST APIs and WebSockets into one package - worth a look once you've outgrown these snippets. See the SDK chooser.

Next: CLOB reference · Data API · Skip the plumbing - the boilerplates.