name: polymarket description: Polymarket CLOB 集成完整操作手册。涵盖认证（L1/L2、构建器头信息、HMAC签名）、订单提交（GTC/GTD/FOK/FAK、批量、仅限挂单、心跳）、市场数据（Gamma API、数据API、订单簿）、WebSocket流（市场/用户/体育频道）、CTF操作（拆分、合并、赎回、负风险）、桥接（存款、提款、多链）以及无Gas交易（中继客户端、订单归属）。适用于构建AI代理、自动化做市商、预测市场UI或任何需要集成Polymarket CLOB API的应用程序。

Polymarket CLOB 技能

此技能的用途

当用户询问以下内容时使用此技能：

Polymarket API 认证（L1/L2、API密钥、HMAC签名）
提交订单（限价、市价、GTC、GTD、FOK、FAK、批量）
读取订单簿数据（价格、价差、中点、深度）
获取市场数据（事件、市场、通过slug、通过标签、分页）
WebSocket订阅（市场频道、用户频道、体育）
CTF操作（拆分、合并、赎回头寸）
负风险市场（多结果、转换、增强负风险）
桥接操作（存款、提款、多链）
无Gas交易（中继客户端、订单归属）
构建器计划集成（订单归属、API密钥）
Polymarket SDK使用（TypeScript @polymarket/clob-client, Python py-clob-client）

API 配置

API	基础URL	认证	用途
CLOB	`https://clob.polymarket.com`	L2用于交易端点	订单簿、价格、订单提交
Gamma / 数据	`https://gamma-api.polymarket.com`	无	事件、市场、搜索
数据API	`https://data-api.polymarket.com`	无	交易、头寸、用户数据
WebSocket (市场)	`wss://ws-subscriptions-clob.polymarket.com/ws/market`	无	实时订单簿
WebSocket (用户)	`wss://ws-subscriptions-clob.polymarket.com/ws/user`	消息中包含API凭证	交易/订单更新
WebSocket (体育)	`wss://sports-api.polymarket.com/ws`	无	实时比分
中继器	`https://relayer-v2.polymarket.com/`	构建器头信息	无Gas交易
桥接	`https://bridge.polymarket.com`	无	存款/提款

合约地址 (Polygon)

合约	地址
USDC (USDC.e)	`0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174`
CTF (条件代币)	`0x4D97DCd97eC945f40cF65F87097ACe5EA0476045`
CTF交易所	`0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E`
负风险CTF交易所	`0xC5d563A36AE78145C45a50134d48A1215220f80a`
负风险适配器	`0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296`

客户端设置

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

// 步骤 1: L1 — 派生API凭证
const tempClient = new ClobClient(HOST, CHAIN_ID, signer);
const apiCreds = await tempClient.createOrDeriveApiKey();

// 步骤 2: L2 — 初始化交易客户端
const client = new ClobClient(
  HOST,
  CHAIN_ID,
  signer,
  apiCreds,
  2,                // signatureType: 0=EOA, 1=POLY_PROXY, 2=GNOSIS_SAFE
  "FUNDER_ADDRESS"  // 来自 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")

# 步骤 1: L1 — 派生API凭证
temp_client = ClobClient(host, key=pk, chain_id=chain_id)
api_creds = temp_client.create_or_derive_api_creds()

# 步骤 2: L2 — 初始化交易客户端
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",
)

快速参考：订单类型

类型	行为	使用场景
GTC	在订单簿上保持直到成交或取消	默认限价订单
GTD	在到期（UTC秒）前有效。最小值 = `当前时间 + 60 + N`	事件前自动过期
FOK	立即全部成交或取消	全有或全无市价订单
FAK	成交可用部分，取消剩余部分	部分成交市价订单

FOK/FAK 买入：amount = 花费的美元金额
FOK/FAK 卖出：amount = 卖出的份额数量
仅限挂单：仅限GTC/GTD — 如果会跨越价差则被拒绝

快速参考：签名类型

类型	值	描述
EOA	`0`	标准钱包。Funder = EOA地址。需要POL支付Gas费。
POLY_PROXY	`1`	Magic Link代理钱包。用户从Polymarket.com导出的私钥。
GNOSIS_SAFE	`2`	Gnosis Safe多签代理。新集成中最常见。

核心模式：提交订单

TypeScript

const response = await client.createAndPostOrder(
  {
    tokenID: "TOKEN_ID",
    price: 0.50,
    size: 10,
    side: Side.BUY,
  },
  {
    tickSize: "0.01",  // 来自 client.getTickSize(tokenID) 或市场对象
    negRisk: false,    // 来自 client.getNegRisk(tokenID) 或市场对象
  },
  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"])

核心模式：读取订单簿

TypeScript

// 无需认证
const readClient = new ClobClient("https://clob.polymarket.com", 137);
const book = await readClient.getOrderBook("TOKEN_ID");
console.log("最佳买价:", book.bids[0], "最佳卖价:", 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")

核心模式：WebSocket订阅

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,
  }));
  // 每10秒发送PING以保持连接
  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"
};

渐进式披露（需要时阅读）

认证深入： authentication.md
订单类型与模式： order-patterns.md
市场数据与获取： market-data.md
WebSocket频道： websocket.md
CTF操作： ctf-operations.md
桥接（存款/提款）： bridge.md
无Gas交易： gasless.md