Skip to content
Back to search

web3-polymarket

SkillWorks with Claude CodeGitHub

Polymarket integration for prediction market trading on Polygon. Covers authentication (L1 EIP-712, L2 HMAC-SHA256, builder headers), order placement (GTC/GTD/FOK/FAK, batch, post-only, heartbeat), market data (Gamma API, Data API, orderbook, subgraph), WebSocket streaming (market/user/sports channels), CTF operations (split, merge, redeem, negative risk), bridge (deposits, withdrawals, multi-chain), and gasless relayer transactions. Use when building AI agents, autonomous market makers, prediction market UIs, or any application integrating with Polymarket on Polygon.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/polymarket--agent-skills/badge.svg)](/listings/polymarket--agent-skills)

HTML

<a href="/listings/polymarket--agent-skills"><img src="/api/listings/polymarket--agent-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 204 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: web3-polymarket
  3. description: Polymarket integration for prediction market trading on Polygon. Covers authentication (L1 EIP-712, L2 HMAC-SHA256, builder headers), order placement (GTC/GTD/FOK/FAK, batch, post-only, heartbeat), market data (Gamma API, Data API, orderbook, subgraph), WebSocket streaming (market/user/sports channels), CTF operations (split, merge, redeem, negative risk), bridge (deposits, withdrawals, multi-chain), and gasless relayer transactions. Use when building AI agents, autonomous market makers, prediction market UIs, or any application integrating with Polymarket on Polygon.
  4. compatibility: Requires network access to Polymarket APIs (clob.polymarket.com, gamma-api.polymarket.com) and Polygon RPC
  5. ---
  6. # Polymarket Skill
  7. ## When to use this skill
  8. Use this skill when the user asks about or needs to build:
  9. - Polymarket API authentication (L1/L2, API keys, HMAC signing)
  10. - Placing or managing orders (limit, market, GTC, GTD, FOK, FAK, batch, cancel)
  11. - Reading orderbook data (prices, spreads, midpoints, depth)
  12. - Market data fetching (events, markets, by slug, by tag, pagination)
  13. - WebSocket subscriptions (market channel, user channel, sports)
  14. - CTF operations (split, merge, redeem positions)
  15. - Negative risk markets (multi-outcome, conversion, augmented neg risk)
  16. - Bridge operations (deposits, withdrawals, multi-chain)
  17. - Gasless transactions (relayer client, order attribution)
  18. - Builder program integration (order attribution, API keys, tiers)
  19. - Polymarket SDK usage (TypeScript @polymarket/clob-client, Python py-clob-client)
  20. ## API Configuration
  21. | API | Base URL | Auth | Purpose |
  22. |-----|----------|------|---------|
  23. | CLOB | `https://clob.polymarket.com` | L2 for trade endpoints | Orderbook, prices, order submission |
  24. | Gamma / Data | `https://gamma-api.polymarket.com` | None | Events, markets, search |
  25. | Data API | `https://data-api.polymarket.com` | None | Trades, positions, user data |
  26. | WebSocket (Market) | `wss://ws-subscriptions-clob.polymarket.com/ws/market` | None | Real-time orderbook |
  27. | WebSocket (User) | `wss://ws-subscriptions-clob.polymarket.com/ws/user` | API creds in message | Trade/order updates |
  28. | WebSocket (Sports) | `wss://sports-api.polymarket.com/ws` | None | Live scores |
  29. | Relayer | `https://relayer-v2.polymarket.com/` | Builder headers | Gasless transactions |
  30. | Bridge | `https://bridge.polymarket.com` | None | Deposits/withdrawals |
  31. ## Contract Addresses (Polygon)
  32. | Contract | Address |
  33. |----------|---------|
  34. | USDC (USDC.e) | `0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174` |
  35. | CTF (Conditional Tokens) | `0x4D97DCd97eC945f40cF65F87097ACe5EA0476045` |
  36. | CTF Exchange | `0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E` |
  37. | Neg Risk CTF Exchange | `0xC5d563A36AE78145C45a50134d48A1215220f80a` |
  38. | Neg Risk Adapter | `0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296` |
  39. ## Client Setup
  40. ### TypeScript
  41. ```typescript
  42. import { ClobClient, Side, OrderType } from "@polymarket/clob-client";
  43. import { Wallet } from "ethers"; // v5.8.0
  44. const HOST = "https://clob.polymarket.com";
  45. const CHAIN_ID = 137;
  46. const signer = new Wallet(process.env.PRIVATE_KEY);
  47. // Step 1: L1 — derive API credentials
  48. const tempClient = new ClobClient(HOST, CHAIN_ID, signer);
  49. const apiCreds = await tempClient.createOrDeriveApiKey();
  50. // Step 2: L2 — init trading client
  51. const client = new ClobClient(
  52. HOST,
  53. CHAIN_ID,
  54. signer,
  55. apiCreds,
  56. 2, // signatureType: 0=EOA, 1=POLY_PROXY, 2=GNOSIS_SAFE
  57. "FUNDER_ADDRESS" // proxy wallet address from polymarket.com/settings
  58. );
  59. ```
  60. ### Python
  61. ```python
  62. from py_clob_client.client import ClobClient
  63. import os
  64. host = "https://clob.polymarket.com"
  65. chain_id = 137
  66. pk = os.getenv("PRIVATE_KEY")
  67. # Step 1: L1 — derive API credentials
  68. temp_client = ClobClient(host, key=pk, chain_id=chain_id)
  69. api_creds = temp_client.create_or_derive_api_creds()
  70. # Step 2: L2 — init trading client
  71. client = ClobClient(
  72. host,
  73. key=pk,
  74. chain_id=chain_id,
  75. creds=api_creds,
  76. signature_type=2, # 0=EOA, 1=POLY_PROXY, 2=GNOSIS_SAFE
  77. funder="FUNDER_ADDRESS",
  78. )
  79. ```
  80. ## Quick Reference: Order Types
  81. | Type | Behavior | Use Case |
  82. |------|----------|----------|
  83. | **GTC** | Rests on book until filled or cancelled | Default limit orders |
  84. | **GTD** | Active until expiration (UTC seconds). Min = `now + 60 + N` | Auto-expire before events |
  85. | **FOK** | Fill entirely immediately or cancel | All-or-nothing market orders |
  86. | **FAK** | Fill what's available, cancel rest | Partial-fill market orders |
  87. - FOK/FAK BUY: `amount` = dollar amount to spend
  88. - FOK/FAK SELL: `amount` = number of shares to sell
  89. - Post-only: GTC/GTD only — rejected if would cross spread
  90. ## Quick Reference: Signature Types
  91. | Type | Value | Description |
  92. |------|-------|-------------|
  93. | EOA | `0` | Standard Ethereum wallet (MetaMask). Funder is the EOA address and will need POL for gas. |
  94. | POLY_PROXY | `1` | Custom proxy wallet for Magic Link email/Google users who exported PK from Polymarket.com. |
  95. | GNOSIS_SAFE | `2` | Gnosis Safe multisig proxy wallet (most common). Use for any new or returning user. |
  96. ## Core Pattern: Place an Order
  97. ### TypeScript
  98. ```typescript
  99. const response = await client.createAndPostOrder(
  100. {
  101. tokenID: "TOKEN_ID",
  102. price: 0.50,
  103. size: 10,
  104. side: Side.BUY,
  105. },
  106. {
  107. tickSize: "0.01", // from client.getTickSize(tokenID) or market object
  108. negRisk: false, // from client.getNegRisk(tokenID) or market object
  109. },
  110. OrderType.GTC
  111. );
  112. console.log(response.orderID, response.status);
  113. ```
  114. ### Python
  115. ```python
  116. from py_clob_client.clob_types import OrderArgs, OrderType
  117. from py_clob_client.order_builder.constants import BUY
  118. response = client.create_and_post_order(
  119. OrderArgs(token_id="TOKEN_ID", price=0.50, size=10, side=BUY),
  120. options={"tick_size": "0.01", "neg_risk": False},
  121. order_type=OrderType.GTC,
  122. )
  123. print(response["orderID"], response["status"])
  124. ```
  125. ## Core Pattern: Read Orderbook
  126. ### TypeScript
  127. ```typescript
  128. // No auth needed
  129. const readClient = new ClobClient("https://clob.polymarket.com", 137);
  130. const book = await readClient.getOrderBook("TOKEN_ID");
  131. console.log("Best bid:", book.bids[0], "Best ask:", book.asks[0]);
  132. const mid = await readClient.getMidpoint("TOKEN_ID");
  133. const spread = await readClient.getSpread("TOKEN_ID");
  134. ```
  135. ### Python
  136. ```python
  137. read_client = ClobClient("https://clob.polymarket.com", chain_id=137)
  138. book = read_client.get_order_book("TOKEN_ID")
  139. mid = read_client.get_midpoint("TOKEN_ID")
  140. spread = read_client.get_spread("TOKEN_ID")
  141. ```
  142. ## Core Pattern: WebSocket Subscribe
  143. ```typescript
  144. const ws = new WebSocket("wss://ws-subscriptions-clob.polymarket.com/ws/market");
  145. ws.onopen = () => {
  146. ws.send(JSON.stringify({
  147. type: "market",
  148. assets_ids: ["TOKEN_ID"],
  149. custom_feature_enabled: true,
  150. }));
  151. // Send PING every 10s to keep alive
  152. setInterval(() => ws.send("PING"), 10_000);
  153. };
  154. ws.onmessage = (event) => {
  155. if (event.data === "PONG") return;
  156. const msg = JSON.parse(event.data);
  157. // msg.event_type: "book" | "price_change" | "last_trade_price" | "tick_size_change" | "best_bid_ask" | "new_market" | "market_resolved"
  158. };
  159. ```
  160. ## Reference files (load on demand)
  161. Only read these when the task requires deeper detail on a specific topic:
  162. - **Authentication** (L1/L2, builder headers, credential lifecycle): [authentication.md](authentication.md)
  163. - **Order patterns** (GTC/GTD/FOK/FAK, tick sizes, cancel, heartbeat, errors): [order-patterns.md](order-patterns.md)
  164. - **Market data** (Gamma API, Data API, CLOB orderbook, subgraph): [market-data.md](market-data.md)
  165. - **WebSocket** (market/user/sports channels, subscribe, heartbeat): [websocket.md](websocket.md)
  166. - **CTF operations** (split, merge, redeem, neg risk, token IDs): [ctf-operations.md](ctf-operations.md)
  167. - **Bridge** (deposits, withdrawals, supported chains/tokens, status): [bridge.md](bridge.md)
  168. - **Gasless transactions** (relayer client, wallet deployment, builder setup): [gasless.md](gasless.md)
README.md · README · 145 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Polymarket Integration Skill
  2. 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.
  3. ## What's Included
  4. ```
  5. web3-polymarket/
  6. ├── SKILL.md # Entry point — quick reference, client setup, core patterns
  7. ├── README.md # This file
  8. ├── authentication.md # L1/L2 auth, builder headers, credential lifecycle
  9. ├── order-patterns.md # Order types, tick sizes, cancel, heartbeat, errors
  10. ├── market-data.md # Gamma API, Data API, CLOB orderbook, subgraph
  11. ├── websocket.md # Market/user/sports channels, subscribe, heartbeat
  12. ├── ctf-operations.md # Split, merge, redeem, negative risk, token IDs
  13. ├── bridge.md # Deposits, withdrawals, supported chains/tokens
  14. └── gasless.md # Relayer client, wallet deployment, builder setup
  15. ```
  16. ## How It Works
  17. The skill uses **progressive disclosure** to stay efficient with context:
  18. 1. **SKILL.md loads first** — contains API endpoints, contract addresses, client setup, and core code patterns. Enough for most tasks.
  19. 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.
  20. This keeps the initial context small (~200 lines) while giving access to ~1,700 lines of detailed reference material when needed.
  21. ## When Agents Use This Skill
  22. An agent activates this skill when a user asks about:
  23. - **Authentication** — API keys, EIP-712 signing, HMAC-SHA256, builder credentials
  24. - **Trading** — placing limit/market orders (GTC, GTD, FOK, FAK), batch orders, cancellation, heartbeat keepalive
  25. - **Market data** — fetching events/markets from Gamma API, reading orderbook prices/spreads/midpoints, price history
  26. - **Real-time data** — WebSocket subscriptions for orderbook updates, trade notifications, sports scores
  27. - **Token operations** — splitting USDC.e into Yes/No tokens, merging, redeeming after resolution
  28. - **Bridging** — depositing from 15+ chains, withdrawing, checking status
  29. - **Gasless transactions** — relayer client for gas-free onchain operations
  30. - **Negative risk** — multi-outcome markets, token conversion, augmented neg risk
  31. ## Quick Start for Humans
  32. If you're a developer reading this directly (not an agent), here's the fastest path:
  33. ### 1. Install the SDK
  34. ```bash
  35. # TypeScript
  36. npm install @polymarket/clob-client ethers@5.8.0
  37. # Python
  38. pip install py-clob-client
  39. ```
  40. ### 2. Get API Credentials
  41. ```typescript
  42. import { ClobClient } from "@polymarket/clob-client";
  43. import { Wallet } from "ethers";
  44. const client = new ClobClient(
  45. "https://clob.polymarket.com",
  46. 137,
  47. new Wallet(process.env.PRIVATE_KEY)
  48. );
  49. const creds = await client.createOrDeriveApiKey();
  50. ```
  51. ### 3. Place an Order
  52. ```typescript
  53. const tradingClient = new ClobClient(
  54. "https://clob.polymarket.com",
  55. 137,
  56. signer,
  57. creds,
  58. 2, // GNOSIS_SAFE (most common)
  59. "FUNDER_ADDR" // from polymarket.com/settings
  60. );
  61. const response = await tradingClient.createAndPostOrder(
  62. { tokenID: "TOKEN_ID", price: 0.50, size: 10, side: "BUY" },
  63. { tickSize: "0.01", negRisk: false },
  64. "GTC"
  65. );
  66. ```
  67. ## Key Concepts
  68. | Concept | Description |
  69. |---------|-------------|
  70. | **USDC.e** | Bridged USDC on Polygon — the collateral token for all markets |
  71. | **Condition ID** | Identifies a market (used in API as `market` or `conditionID`) |
  72. | **Token ID** | Identifies a specific outcome token (Yes or No) within a market |
  73. | **Funder** | The proxy wallet address that holds funds — find at polymarket.com/settings |
  74. | **Signature Type** | `0` = EOA, `1` = POLY_PROXY (Magic Link), `2` = GNOSIS_SAFE (most common) |
  75. | **Neg Risk** | Multi-outcome markets where outcomes are linked — set `negRisk: true` in order options |
  76. | **Tick Size** | Minimum price increment for a market — must match or orders are rejected |
  77. ## API Endpoints
  78. | API | Base URL | Auth Required |
  79. |-----|----------|---------------|
  80. | CLOB | `https://clob.polymarket.com` | L2 headers for trades, none for reads |
  81. | Gamma | `https://gamma-api.polymarket.com` | None |
  82. | Data | `https://data-api.polymarket.com` | None |
  83. | Bridge | `https://bridge.polymarket.com` | None |
  84. | Relayer | `https://relayer-v2.polymarket.com/` | Builder headers |
  85. | WS Market | `wss://ws-subscriptions-clob.polymarket.com/ws/market` | None |
  86. | WS User | `wss://ws-subscriptions-clob.polymarket.com/ws/user` | API creds in message |
  87. | WS Sports | `wss://sports-api.polymarket.com/ws` | None |
  88. ## Contract Addresses (Polygon)
  89. | Contract | Address |
  90. |----------|---------|
  91. | USDC.e (Bridged USDC) | `0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174` |
  92. | CTF | `0x4D97DCd97eC945f40cF65F87097ACe5EA0476045` |
  93. | CTF Exchange | `0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E` |
  94. | Neg Risk CTF Exchange | `0xC5d563A36AE78145C45a50134d48A1215220f80a` |
  95. | Neg Risk Adapter | `0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296` |
  96. ## File Guide
  97. | File | Read when you need to... |
  98. |------|--------------------------|
  99. | [SKILL.md](SKILL.md) | Get started — has everything for basic integration |
  100. | [authentication.md](authentication.md) | Understand L1/L2 auth flow, builder headers, or troubleshoot credential issues |
  101. | [order-patterns.md](order-patterns.md) | Use advanced order types (GTD, post-only, batch), handle errors, or implement heartbeat |
  102. | [market-data.md](market-data.md) | Query markets by slug/tag, paginate results, use subgraph, or estimate fill prices |
  103. | [websocket.md](websocket.md) | Stream real-time orderbook updates, trade notifications, or sports scores |
  104. | [ctf-operations.md](ctf-operations.md) | Split/merge/redeem tokens, work with neg risk markets, or compute token IDs |
  105. | [bridge.md](bridge.md) | Deposit from other chains, withdraw, check supported assets, or track transaction status |
  106. | [gasless.md](gasless.md) | Set up gas-free transactions via the relayer, deploy wallets, or configure builder credentials |
  107. ## SDKs
  108. - **TypeScript**: [@polymarket/clob-client](https://github.com/Polymarket/clob-client)
  109. - **Python**: [py-clob-client](https://github.com/Polymarket/py-clob-client)
  110. - **Rust**: [rs-clob-client](https://github.com/Polymarket/rs-clob-client)
  111. - **Builder Relayer (TS)**: [@polymarket/builder-relayer-client](https://github.com/Polymarket/builder-relayer-client)
  112. - **Builder Relayer (Python)**: [py-builder-relayer-client](https://github.com/Polymarket/py-builder-relayer-client)
  113. - **Builder Signing (TS)**: [@polymarket/builder-signing-sdk](https://github.com/Polymarket/builder-signing-sdk)
  114. - **Builder Signing (Python)**: [py-builder-signing-sdk](https://github.com/Polymarket/py-builder-signing-sdk)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.