Polymarket CLOB Skill

Name: polymarket
Rating: 92
Author: 0xinit

What this Skill is for

Use this Skill when the user asks for:

•Polymarket API authentication (L1/L2, API keys, HMAC signing)
•Placing orders (limit, market, GTC, GTD, FOK, FAK, batch)
•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)
•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

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

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 wallet. Funder = EOA address. Needs POL for gas.
POLY_PROXY	`1`	Magic Link proxy wallet. User exported PK from Polymarket.com.
GNOSIS_SAFE	`2`	Gnosis Safe multisig proxy. Most common for new integrations.

Core Pattern: Place an Order

TypeScript

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

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

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

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

typescript

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"
};

Progressive Disclosure (read when needed)

•Authentication deep-dive: authentication.md
•Order types & patterns: order-patterns.md
•Market data & fetching: market-data.md
•WebSocket channels: websocket.md
•CTF operations: ctf-operations.md
•Bridge (deposits/withdrawals): bridge.md
•Gasless transactions: gasless.md