Polymarket Integration Skill

February 19, 2026 · View on GitHub

Agent skill for building on Polymarket — the world's largest prediction market. Gives agents the knowledge to authenticate, place orders, read markets, stream real-time data, manage positions, bridge assets across chains, and execute gasless transactions.

What's Included

web3-polymarket/
├── SKILL.md              # Entry point — quick reference, client setup, core patterns
├── README.md             # This file
├── authentication.md     # L1/L2 auth, builder headers, credential lifecycle
├── order-patterns.md     # Order types, tick sizes, cancel, heartbeat, errors
├── market-data.md        # Gamma API, Data API, CLOB orderbook, subgraph
├── websocket.md          # Market/user/sports channels, subscribe, heartbeat
├── ctf-operations.md     # Split, merge, redeem, negative risk, token IDs
├── bridge.md             # Deposits, withdrawals, supported chains/tokens
└── gasless.md            # Relayer client, wallet deployment, builder setup

How It Works

The skill uses progressive disclosure to stay efficient with context:

  1. SKILL.md loads first — contains API endpoints, contract addresses, client setup, and core code patterns. Enough for most tasks.
  2. Reference files load on demand — when a task needs deeper detail (e.g., full error code list, bridge chain support, WebSocket event schemas), the agent reads the relevant file.

This keeps the initial context small (~200 lines) while giving access to ~1,700 lines of detailed reference material when needed.

When Agents Use This Skill

An agent activates this skill when a user asks about:

  • Authentication — API keys, EIP-712 signing, HMAC-SHA256, builder credentials
  • Trading — placing limit/market orders (GTC, GTD, FOK, FAK), batch orders, cancellation, heartbeat keepalive
  • Market data — fetching events/markets from Gamma API, reading orderbook prices/spreads/midpoints, price history
  • Real-time data — WebSocket subscriptions for orderbook updates, trade notifications, sports scores
  • Token operations — splitting USDC.e into Yes/No tokens, merging, redeeming after resolution
  • Bridging — depositing from 15+ chains, withdrawing, checking status
  • Gasless transactions — relayer client for gas-free onchain operations
  • Negative risk — multi-outcome markets, token conversion, augmented neg risk

Quick Start for Humans

If you're a developer reading this directly (not an agent), here's the fastest path:

1. Install the SDK

# TypeScript
npm install @polymarket/clob-client ethers@5.8.0

# Python
pip install py-clob-client

2. Get API Credentials

import { ClobClient } from "@polymarket/clob-client";
import { Wallet } from "ethers";

const client = new ClobClient(
  "https://clob.polymarket.com",
  137,
  new Wallet(process.env.PRIVATE_KEY)
);
const creds = await client.createOrDeriveApiKey();

3. Place an Order

const tradingClient = new ClobClient(
  "https://clob.polymarket.com",
  137,
  signer,
  creds,
  2,              // GNOSIS_SAFE (most common)
  "FUNDER_ADDR"   // from polymarket.com/settings
);

const response = await tradingClient.createAndPostOrder(
  { tokenID: "TOKEN_ID", price: 0.50, size: 10, side: "BUY" },
  { tickSize: "0.01", negRisk: false },
  "GTC"
);

Key Concepts

ConceptDescription
USDC.eBridged USDC on Polygon — the collateral token for all markets
Condition IDIdentifies a market (used in API as market or conditionID)
Token IDIdentifies a specific outcome token (Yes or No) within a market
FunderThe proxy wallet address that holds funds — find at polymarket.com/settings
Signature Type0 = EOA, 1 = POLY_PROXY (Magic Link), 2 = GNOSIS_SAFE (most common)
Neg RiskMulti-outcome markets where outcomes are linked — set negRisk: true in order options
Tick SizeMinimum price increment for a market — must match or orders are rejected

API Endpoints

APIBase URLAuth Required
CLOBhttps://clob.polymarket.comL2 headers for trades, none for reads
Gammahttps://gamma-api.polymarket.comNone
Datahttps://data-api.polymarket.comNone
Bridgehttps://bridge.polymarket.comNone
Relayerhttps://relayer-v2.polymarket.com/Builder headers
WS Marketwss://ws-subscriptions-clob.polymarket.com/ws/marketNone
WS Userwss://ws-subscriptions-clob.polymarket.com/ws/userAPI creds in message
WS Sportswss://sports-api.polymarket.com/wsNone

Contract Addresses (Polygon)

ContractAddress
USDC.e (Bridged USDC)0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174
CTF0x4D97DCd97eC945f40cF65F87097ACe5EA0476045
CTF Exchange0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E
Neg Risk CTF Exchange0xC5d563A36AE78145C45a50134d48A1215220f80a
Neg Risk Adapter0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296

File Guide

FileRead when you need to...
SKILL.mdGet started — has everything for basic integration
authentication.mdUnderstand L1/L2 auth flow, builder headers, or troubleshoot credential issues
order-patterns.mdUse advanced order types (GTD, post-only, batch), handle errors, or implement heartbeat
market-data.mdQuery markets by slug/tag, paginate results, use subgraph, or estimate fill prices
websocket.mdStream real-time orderbook updates, trade notifications, or sports scores
ctf-operations.mdSplit/merge/redeem tokens, work with neg risk markets, or compute token IDs
bridge.mdDeposit from other chains, withdraw, check supported assets, or track transaction status
gasless.mdSet up gas-free transactions via the relayer, deploy wallets, or configure builder credentials

SDKs