Polymarket Skill When to use this skill Use this skill when the user asks about or needs to build: Polymarket API authentication (L1/L2, API keys, HMAC signing) Placing or managing orders (limit, market, GTC, GTD, FOK, FAK, batch, cancel) Reading orderbook data (prices, spreads, midpoints, depth) Market data fetching (events, markets, by slug, by tag, pagination) WebSocket subscriptions (market channel, user channel, sports) CTF operations (split, merge, redeem positions) Negative risk markets (multi-outcome, conversion, augmented neg risk) Bridge operations (deposits, withdrawals, multi-chain) Gasless transactions (relayer client, order attribution) Builder program integration (order attribution, API keys, tiers) Polymarket SDK usage (TypeScript @polymarket/clob-client, Python py-clob-client) API Configuration API Base URL Auth Purpose CLOB https://clob.polymarket.com L2 for trade endpoints Orderbook, prices, order submission Gamma / Data https://gamma-api.polymarket.com None Events, markets, search Data API https://data-api.polymarket.com None Trades, positions, user data WebSocket (Market) wss://ws-subscriptions-clob.polymarket.com/ws/market None Real-time orderbook WebSocket (User) wss://ws-subscriptions-clob.polymarket.com/ws/user API creds in message Trade/order updates WebSocket (Sports) wss://sports-api.polymarket.com/ws None Live scores Relayer https://relayer-v2.polymarket.com/ Builder headers Gasless transactions Bridge https://bridge.polymarket.com None Deposits/withdrawals Contract Addresses (Polygon) Contract Address USDC (USDC.e) 0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174 CTF (Conditional Tokens) 0x4D97DCd97eC945f40cF65F87097ACe5EA0476045 CTF Exchange 0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E Neg Risk CTF Exchange 0xC5d563A36AE78145C45a50134d48A1215220f80a Neg Risk Adapter 0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296 Client Setup TypeScript import { ClobClient , Side , OrderType } from "@polymarket/clob-client" ; import { Wallet } from "ethers" ; // v5.8.0 const HOST = "https://clob.polymarket.com" ; const CHAIN_ID = 137 ; const signer = new Wallet ( process . env . PRIVATE_KEY ) ; // Step 1: L1 — derive API credentials const tempClient = new ClobClient ( HOST , CHAIN_ID , signer ) ; const apiCreds = await tempClient . createOrDeriveApiKey ( ) ; // Step 2: L2 — init trading client const client = new ClobClient ( HOST , CHAIN_ID , signer , apiCreds , 2 , // signatureType: 0=EOA, 1=POLY_PROXY, 2=GNOSIS_SAFE "FUNDER_ADDRESS" // proxy wallet address from polymarket.com/settings ) ; Python from py_clob_client . client import ClobClient import os host = "https://clob.polymarket.com" chain_id = 137 pk = os . getenv ( "PRIVATE_KEY" )

Step 1: L1 — derive API credentials

temp_client

ClobClient ( host , key = pk , chain_id = chain_id ) api_creds = temp_client . create_or_derive_api_creds ( )

Step 2: L2 — init trading client

client

ClobClient ( host , key = pk , chain_id = chain_id , creds = api_creds , signature_type = 2 ,

0=EOA, 1=POLY_PROXY, 2=GNOSIS_SAFE

funder

"FUNDER_ADDRESS" , ) Quick Reference: Order Types Type Behavior Use Case GTC Rests on book until filled or cancelled Default limit orders GTD Active until expiration (UTC seconds). Min = now + 60 + N Auto-expire before events FOK Fill entirely immediately or cancel All-or-nothing market orders FAK Fill what's available, cancel rest Partial-fill market orders FOK/FAK BUY: amount = dollar amount to spend FOK/FAK SELL: amount = number of shares to sell Post-only: GTC/GTD only — rejected if would cross spread Quick Reference: Signature Types Type Value Description EOA 0 Standard Ethereum wallet (MetaMask). Funder is the EOA address and will need POL for gas. POLY_PROXY 1 Custom proxy wallet for Magic Link email/Google users who exported PK from Polymarket.com. GNOSIS_SAFE 2 Gnosis Safe multisig proxy wallet (most common). Use for any new or returning user. Core Pattern: Place an Order TypeScript const response = await client . createAndPostOrder ( { tokenID : "TOKEN_ID" , price : 0.50 , size : 10 , side : Side . BUY , } , { tickSize : "0.01" , // from client.getTickSize(tokenID) or market object negRisk : false , // from client.getNegRisk(tokenID) or market object } , OrderType . GTC ) ; console . log ( response . orderID , response . status ) ; Python from py_clob_client . clob_types import OrderArgs , OrderType from py_clob_client . order_builder . constants import BUY response = client . create_and_post_order ( OrderArgs ( token_id = "TOKEN_ID" , price = 0.50 , size = 10 , side = BUY ) , options = { "tick_size" : "0.01" , "neg_risk" : False } , order_type = OrderType . GTC , ) print ( response [ "orderID" ] , response [ "status" ] ) Core Pattern: Read Orderbook TypeScript // No auth needed const readClient = new ClobClient ( "https://clob.polymarket.com" , 137 ) ; const book = await readClient . getOrderBook ( "TOKEN_ID" ) ; console . log ( "Best bid:" , book . bids [ 0 ] , "Best ask:" , book . asks [ 0 ] ) ; const mid = await readClient . getMidpoint ( "TOKEN_ID" ) ; const spread = await readClient . getSpread ( "TOKEN_ID" ) ; Python read_client = ClobClient ( "https://clob.polymarket.com" , chain_id = 137 ) book = read_client . get_order_book ( "TOKEN_ID" ) mid = read_client . get_midpoint ( "TOKEN_ID" ) spread = read_client . get_spread ( "TOKEN_ID" ) Core Pattern: WebSocket Subscribe const ws = new WebSocket ( "wss://ws-subscriptions-clob.polymarket.com/ws/market" ) ; ws . onopen = ( ) => { ws . send ( JSON . stringify ( { type : "market" , assets_ids : [ "TOKEN_ID" ] , custom_feature_enabled : true , } ) ) ; // Send PING every 10s to keep alive setInterval ( ( ) => ws . send ( "PING" ) , 10_000 ) ; } ; ws . onmessage = ( event ) => { if ( event . data === "PONG" ) return ; const msg = JSON . parse ( event . data ) ; // msg.event_type: "book" | "price_change" | "last_trade_price" | "tick_size_change" | "best_bid_ask" | "new_market" | "market_resolved" } ; Reference files (load on demand) Only read these when the task requires deeper detail on a specific topic: Authentication (L1/L2, builder headers, credential lifecycle): authentication.md Order patterns (GTC/GTD/FOK/FAK, tick sizes, cancel, heartbeat, errors): order-patterns.md Market data (Gamma API, Data API, CLOB orderbook, subgraph): market-data.md WebSocket (market/user/sports channels, subscribe, heartbeat): websocket.md CTF operations (split, merge, redeem, neg risk, token IDs): ctf-operations.md Bridge (deposits, withdrawals, supported chains/tokens, status): bridge.md Gasless transactions (relayer client, wallet deployment, builder setup): gasless.md