web3-polymarket

Polymarket 技能

何时使用此技能

当用户询问或需要构建以下内容时，请使用此技能：

• Polymarket API 身份验证（L1/L2、API 密钥、HMAC 签名）
• 下单或管理订单（限价、市价、GTC、GTD、FOK、FAK、批量、取消）
• 读取订单簿数据（价格、价差、中间价、深度）
• 获取市场数据（事件、市场、按 slug、按标签、分页）
• WebSocket 订阅（市场频道、用户频道、体育）
• CTF 操作（拆分、合并、赎回持仓）
• 负风险市场（多结果、转换、增强型负风险）
• Bridge 操作（存款、提款、多链）
• 无 Gas 交易（中继器客户端、订单归因）
• Builder 计划集成（订单归因、API 密钥、等级）
• 使用 Polymarket SDK（TypeScript @polymarket/clob-client、Python py-clob-client）

API 配置

API	基础 URL	身份验证	用途
CLOB	https://clob.polymarket.com	交易端点使用 L2	订单簿、价格、提交订单
Gamma / Data	https://gamma-api.polymarket.com	无	事件、市场、搜索
Data API	https://data-api.polymarket.com	无	交易、持仓、用户数据
WebSocket（Market）	wss://ws-subscriptions-clob.polymarket.com/ws/market	无	实时订单簿
WebSocket（User）	wss://ws-subscriptions-clob.polymarket.com/ws/user	在消息中提供 API 凭据	交易/订单更新
WebSocket（Sports）	wss://sports-api.polymarket.com/ws	无	实时比分
Relayer	https://relayer-v2.polymarket.com/	Builder 标头	无 Gas 交易
Bridge	https://bridge.polymarket.com	无	存款/提款

合约地址（Polygon）

合约	地址
USDC (USDC.e)	0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174
CTF（Conditional Tokens）	0x4D97DCd97eC945f40cF65F87097ACe5EA0476045
CTF Exchange	0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E
Neg Risk CTF Exchange	0xC5d563A36AE78145C45a50134d48A1215220f80a
Neg Risk Adapter	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);

// 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",
)

快速参考：订单类型

类型	行为	用例
GTC	挂在订单簿上，直到成交或取消	默认限价订单
GTD	持续有效，直到到期（UTC 秒）。最短 = now + 60 + N	在事件开始前自动到期
FOK	立即全部成交，否则取消	全部成交或全不成交的市价订单
FAK	成交可用部分，取消其余部分	部分成交的市价订单

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

快速参考：签名类型

类型	值	说明
EOA	0	标准 Ethereum 钱包（MetaMask）。出资方是 EOA 地址，需要 POL 支付 Gas。
POLY_PROXY	1	供从 Polymarket.com 导出 PK 的 Magic Link 邮箱/Google 用户使用的自定义代理钱包。
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",  // 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"])

核心模式：读取订单簿

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

核心模式：订阅 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,
  }));
  // 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"
};

参考文件（按需加载）

仅在需要深入了解特定主题时阅读：

• 身份验证（L1/L2、构建器标头、凭据生命周期）：authentication.md
• 订单模式（GTC/GTD/FOK/FAK、刻度大小、取消、心跳、错误）：order-patterns.md
• 市场数据（Gamma API、Data API、CLOB 订单簿、子图）：market-data.md
• WebSocket（市场/用户/体育频道、订阅、心跳）：websocket.md
• CTF 操作（拆分、合并、赎回、负风险、令牌 ID）：ctf-operations.md
• Bridge（存款、取款、支持的链/令牌、状态）：bridge.md
• 免 Gas 交易（中继客户端、钱包部署、构建器设置）：gasless.md