polymarket开发文档-Developer Quickstart + Polymarket Builders Program

Fetching Market Data

1. 零门槛访问

无需 API 密钥、无需身份验证、无需连接钱包。
所有数据通过公开 HTTP 接口（主要是 Gamma API 和 CLOB API）即可获取。

2. Polymarket 数据模型

理解三层结构对正确使用 API 至关重要：

Event（事件）：代表一个预测问题，如 "Will Bitcoin reach $100K by 2025?"
Market（市场）：每个事件包含一个或多个可交易的二元市场（通常是"Yes/No"）。
Outcomes & Prices（结果与价格） ：
- outcomes 数组（如 ["Yes", "No"]）
- outcomePrices 数组（如 ["0.20", "0.80"]），表示各结果的隐含概率（即市场价格）。

3. 获取活跃事件

使用 Gamma API 列出当前可交易的事件：

bash 复制代码

curl "https://gamma-api.polymarket.com/events?active=true&closed=false&limit=5"

必须使用 active=true&closed=false 筛选仍在交易中的事件。

4. 市场发现最佳实践

▶ 体育赛事

先通过 /sports 获取支持的联赛列表。
再用 series_id 查询特定联赛（如 NBA）的事件。
可进一步用 tag_id=100639 过滤为"单场比赛"（而非赛季期货）。
注意：非自动化联赛（如 UFC、F1、高尔夫等）需直接通过 tag_id 查询 /events。

▶ 非体育话题（政治、经济、科技等）

通过 /tags 获取所有分类标签。
使用 tag_id（如 tag_id=2 代表"Politics"）筛选相关事件。
每个事件响应中包含 tags 字段，可用于动态构建分类映射。

5. 获取具体市场详情

通过市场 slug 或 ID 获取详细信息：

bash 复制代码

curl "https://gamma-api.polymarket.com/markets?slug=will-bitcoin-reach-100k-by-2025"

响应中包含 clobTokenIds，这是后续查询价格和下单所必需的 token ID。

6. 获取实时价格与订单簿

当前价格 （买方或卖方报价）：

bash 复制代码

curl "https://clob.polymarket.com/price?token_id=YOUR_TOKEN_ID&side=buy"

完整订单簿深度 （所有挂单）：

bash 复制代码

curl "https://clob.polymarket.com/book?token_id=YOUR_TOKEN_ID"

Placing Your First Order

安装依赖

TypeScript

bash 复制代码

npm install @polymarket/clob-client ethers@5

Python

bash 复制代码

pip install py-clob-client

Step 1: 使用私钥初始化客户端

TypeScript

ts 复制代码

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

const HOST = "https://clob.polymarket.com";
const CHAIN_ID = 137; // Polygon mainnet
const signer = new Wallet(process.env.PRIVATE_KEY);

const client = new ClobClient(HOST, CHAIN_ID, signer);

Python

python 复制代码

from py_clob_client.client import ClobClient
import os

host = "https://clob.polymarket.com"
chain_id = 137  # Polygon mainnet
private_key = os.getenv("PRIVATE_KEY")

client = ClobClient(host, key=private_key, chain_id=chain_id)

⚠️ 私钥仅用于本地派生 L2 API 凭据，不会随每次请求发送。

Step 2: 派生用户 API 凭据

这些凭据（API Key + Secret + Passphrase）将用于后续所有认证请求。

TypeScript

ts 复制代码

// Get existing API key, or create one if none exists
const userApiCreds = await client.createOrDeriveApiKey();

console.log("API Key:", userApiCreds.apiKey);
console.log("Secret:", userApiCreds.secret);
console.log("Passphrase:", userApiCreds.passphrase);

Python

python 复制代码

# Get existing API key, or create one if none exists
user_api_creds = client.create_or_derive_api_creds()

print("API Key:", user_api_creds["apiKey"])
print("Secret:", user_api_creds["secret"])
print("Passphrase:", user_api_creds["passphrase"])

Step 3: 配置签名类型（Signature Type）和资金方地址（Funder Address）

你想如何交易？	类型（Type）	值（Value）	资金方地址（Funder Address）
使用自己的 EOA 钱包（持有 USDCe 和结果代币，自己付 gas）	`EOA`	`0`	你的 EOA 钱包地址
通过 Polymarket.com 账户（Magic Link / Google 登录）	`POLY_PROXY`	`1`	你的代理钱包地址
通过 Polymarket.com 账户（浏览器连接钱包如 MetaMask）	`GNOSIS_SAFE`	`2`	你的代理钱包地址

🔍 如果你有 Polymarket.com 账户，资金实际存放在一个"代理钱包"中（可在网页端个人资料下拉菜单中查看），应使用类型 1 或 2。类型 0 仅适用于独立的 EOA 钱包。

Step 4: 使用完整认证信息重新初始化客户端

TypeScript

ts 复制代码

// Choose based on your wallet type (see table above)
const SIGNATURE_TYPE = 0; // EOA example
const FUNDER_ADDRESS = signer.address; // For EOA, funder is your wallet

const client = new ClobClient(
  HOST,
  CHAIN_ID,
  signer,
  userApiCreds,
  SIGNATURE_TYPE,
  FUNDER_ADDRESS
);

Python

python 复制代码

# Choose based on your wallet type (see table above)
signature_type = 0  # EOA example
funder_address = "YOUR_WALLET_ADDRESS"  # For EOA, funder is your wallet

client = ClobClient(
    host,
    key=private_key,
    chain_id=chain_id,
    creds=user_api_creds,
    signature_type=signature_type,
    funder=funder_address
)

❗ 注意：不要用 Builder API 凭据替代用户 API 凭据！Builder 凭据仅用于订单归属（attribution），不能用于用户身份认证。

Step 5: 下单交易

首先需从 Gamma API 获取目标市场的 token_id，然后提交订单。

TypeScript

ts 复制代码

import { Side, OrderType } from "@polymarket/clob-client";

// Get market info first
const market = await client.getMarket("TOKEN_ID");

const response = await client.createAndPostOrder(
  {
    tokenID: "TOKEN_ID",
    price: 0.50,        // Price per share ($0.50)
    size: 10,           // Number of shares
    side: Side.BUY,     // BUY or SELL
  },
  {
    tickSize: market.tickSize,
    negRisk: market.negRisk,    // true for multi-outcome events
  },
  OrderType.GTC  // Good-Til-Cancelled
);

console.log("Order ID:", response.orderID);
console.log("Status:", response.status);

Python

python 复制代码

from py_clob_client.clob_types import OrderArgs, OrderType
from py_clob_client.order_builder.constants import BUY

# Get market info first
market = client.get_market("TOKEN_ID")

response = client.create_and_post_order(
    OrderArgs(
        token_id="TOKEN_ID",
        price=0.50,       # Price per share ($0.50)
        size=10,          # Number of shares
        side=BUY,         # BUY or SELL
    ),
    options={
        "tick_size": market["tickSize"],
        "neg_risk": market["negRisk"],    # True for multi-outcome events
    },
    order_type=OrderType.GTC  # Good-Til-Cancelled
)

print("Order ID:", response["orderID"])
print("Status:", response["status"])

Step 6: 查询与管理订单

TypeScript

ts 复制代码

// View all open orders
const openOrders = await client.getOpenOrders();
console.log(`You have ${openOrders.length} open orders`);

// View your trade history
const trades = await client.getTrades();
console.log(`You've made ${trades.length} trades`);

// Cancel an order
await client.cancelOrder(response.orderID);

Python

python 复制代码

# View all open orders
open_orders = client.get_open_orders()
print(f"You have {len(open_orders)} open orders")

# View your trade history
trades = client.get_trades()
print(f"You've made {len(trades)} trades")

# Cancel an order
client.cancel_order(response["orderID"])

常见问题排查（Troubleshooting）

Invalid Signature / L2 Auth Not Available：检查私钥是否正确，或是否已成功派生 API 凭据。
Unauthorized / Invalid API Key ：确保使用的是 createOrDeriveApiKey 生成的用户凭据，而非 Builder 凭据。
Not Enough Balance / Allowance：确保钱包中有足够 USDCe（Polymarket 使用的是 Polygon 上的 USDC.e），并已授权给 CTF 合约。
Blocked by Cloudflare / Geoblock：某些地区可能被限制访问，需检查网络环境。

添加 Builder API 凭据（用于应用开发者）

如果你正在构建一个为用户路由订单的应用，可以附加 Builder 凭据 以获得 Builder Leaderboard 上的归属统计：

TypeScript（仅展示添加方式）

ts 复制代码

import { BuilderConfig, BuilderApiKeyCreds } from "@polymarket/builder-signing-sdk";

const builderCreds: BuilderApiKeyCreds = {
  key: process.env.POLY_BUILDER_API_KEY!,
  secret: process.env.POLY_BUILDER_SECRET!,
  passphrase: process.env.POLY_BUILDER_PASSPHRASE!,
};

const builderConfig = new BuilderConfig({ localBuilderCreds: builderCreds });

// Add builderConfig as the last parameter
const client = new ClobClient(
  HOST, 
  CHAIN_ID, 
  signer, 
  userApiCreds, 
  signatureType, 
  funderAddress,
  undefined, 
  false, 
  builderConfig
);

✅ Builder 凭据与用户凭据完全分离：每个用户仍需自己的 L2 凭据来交易，Builder 凭据仅用于标记"该订单由哪个 Builder 应用促成"。

术语表（Glossary）

市场与事件（Markets & Events）

术语	定义
Event（事件）	一组相关市场的集合，围绕同一主题组织。例如："2024 美国总统大选"事件下包含多个候选人胜选的独立市场。
Market（市场）	事件中的一个可交易二元结果（Yes/No）。每个市场对应一个链上 Condition ID、Question ID 和一对 Token ID。
Token（代币）	代表某一特定结果（Yes 或 No）的持仓凭证。价格区间为 0.00--1.00，结算后胜出代币可兑换 1 USDCe。也称"结果代币"（outcome token）。
Token ID（代币 ID）	某一结果代币的唯一标识符。下单、查价等操作必须提供此 ID。
Condition ID（条件 ID）	链上用于标识市场结算条件的唯一 ID，用于 CTF（Conditional Token Framework）操作。
Question ID（问题 ID）	将市场关联到其预言机（如 UMA）的标识符，用于确定最终结果。
Slug（短标识）	人类可读的 URL 路径标识符，见于 Polymarket 网页链接中，如 `polymarket.com/event/[slug]`。

交易（Trading）

术语	定义
CLOB（中央限价订单簿）	Polymarket 的链下订单撮合系统。所有订单在此匹配，之后才进行链上结算。
Tick Size（最小价格单位）	市场允许的最小价格变动幅度，通常为 0.01（1 美分）或 0.001（0.1 美分）。
Fill（成交）	订单被匹配并执行的过程。支持部分成交或完全成交。

订单类型（Order Types）

术语	定义
GTC（Good-Til-Cancelled）	"有效直至取消"：订单持续挂单，直到被完全成交或用户手动取消。
GTD（Good-Til-Date）	"有效直至指定时间"：若在设定时间前未成交，则自动取消。
FOK（Fill-Or-Kill）	"立即全成或取消"：必须一次性全部成交，否则立即取消，不允许部分成交。
FAK（Fill-And-Kill）	"立即部分成交并取消剩余"：尽可能立即成交一部分，未成交部分立即取消。

市场类型（Market Types）

术语	定义
Binary Market（二元市场）	仅有两个互斥结果（Yes/No）的市场，两者价格之和恒为约 $1。
Negative Risk（NegRisk，负风险市场）	多结果事件中仅有一个结果可胜出（如"谁将赢得大选？"）。下单时需显式设置 `negRisk: true`。

钱包（Wallets）

术语	定义
EOA（Externally Owned Account）	由私钥控制的标准以太坊外部账户（如 MetaMask）。
Funder Address（资金方地址）	实际持有 USDCe 和结果代币、用于交易结算的钱包地址。
Signature Type（签名类型）	标识交易使用的钱包类型： • `0` = EOA • `1` = Magic Link 代理钱包（Polymarket.com 邮箱登录） • `2` = Gnosis Safe 代理钱包（浏览器连接钱包）

代币操作（CTF，Conditional Token Framework）

术语	定义
CTF	条件代币框架，Polymarket 底层的链上智能合约系统，用于管理结果代币的创建与结算。
Split（拆分）	将 1 USDCe 拆分为一套完整的结果代币（1 Yes + 1 No）。
Merge（合并）	将一套完整的结果代币（1 Yes + 1 No）合并回 1 USDCe。
Redeem（赎回）	市场结算后，将胜出的结果代币按 1:1 兑换为 USDCe。

基础设施（Infrastructure）

术语	定义
Polygon	Polymarket 运行的区块链网络，Chain ID 为 137。
USDCe	Polymarket 使用的抵押稳定币，即桥接至 Polygon 网络的 USDC（常写作 USDC.e）。

API 速率限制（API Rate Limits）

限流机制说明

节流（Throttling）：超过速率上限的请求会被延迟/排队，而非立即丢弃。
突发容许（Burst Allowances）：部分接口允许在短时间内超过平均速率（如下单接口支持每秒 500 次的突发）。
滑动时间窗口（Sliding Time Windows）：限流按动态滚动的时间段计算（例如"最近 10 秒内"），而非固定整点重置。

各类 API 速率限制详情

1. 通用速率限制

接口	限制	说明
通用请求	15,000 次 / 10 秒	所有未单独列出的端点默认受此限制
`/ok` 健康检查端点	100 次 / 10 秒	用于探测服务可用性

2. Data API（用户数据接口）

接口	限制	说明
Data API（通用）	1,000 次 / 10 秒	查询持仓、活动等
`/trades`	200 次 / 10 秒	获取交易历史
`/positions`	150 次 / 10 秒	获取当前持仓
`/closed-positions`	150 次 / 10 秒	获取已平仓头寸
Data API `/ok`	100 次 / 10 秒	健康检查

3. Gamma API（市场发现与元数据）

接口	限制	说明
Gamma（通用）	4,000 次 / 10 秒	未单独列出的 Gamma 端点
`/comments`	200 次 / 10 秒	获取市场评论
`/events`	500 次 / 10 秒	获取事件列表
`/markets`	300 次 / 10 秒	获取市场详情
`/markets` + 事件列表	900 次 / 10 秒	批量获取市场与事件
`/tags`	200 次 / 10 秒	获取分类标签
`/search`	350 次 / 10 秒	市场搜索功能

4. CLOB API（核心交易接口）

▶ 通用 CLOB 端点

接口	限制	说明
CLOB（通用）	9,000 次 / 10 秒	默认 CLOB 请求上限
`GET /balance-allowance`	200 次 / 10 秒	查询余额与授权
`UPDATE /balance-allowance`	50 次 / 10 秒	更新授权（敏感操作，限制更严）

▶ 市场数据（行情）

接口	限制	说明
`/book`（单个订单簿）	1,500 次 / 10 秒	高频行情常用
`/books`（批量订单簿）	500 次 / 10 秒	批量查询多个市场
`/price` / `/midprice`	1,500 次 / 10 秒	单个价格查询
`/prices` / `/midprices`	500 次 / 10 秒	批量价格查询

▶ 账户与通知（Ledger）

接口	限制	说明
`/trades`, `/orders` 等	900 次 / 10 秒	查询个人订单/成交
`/data/orders` / `/data/trades`	500 次 / 10 秒	结构化数据接口
`/notifications`	125 次 / 10 秒	获取系统通知

▶ 市场与定价配置

接口	限制	说明
价格历史	1,000 次 / 10 秒	获取历史成交价
Tick Size 查询	200 次 / 10 秒	获取最小价格单位

▶ 认证

接口	限制	说明
API Key 管理	100 次 / 10 秒	创建/派生 API 凭据

▶ 交易操作（下单/撤单）

⚠️ 此类接口同时提供 短时突发（Burst） 和 长期平均 两种限制。

操作	突发限制（短时）	长期限制（10 分钟）	说明
`POST /order`（单笔下单）	3,500 / 10s（≈500/s）	36,000 / 10min（60/s）	支持高频做市
`DELETE /order`（单笔撤单）	3,000 / 10s（300/s）	30,000 / 10min（50/s）	---
`POST /orders`（批量下单）	1,000 / 10s（100/s）	15,000 / 10min（25/s）	最多 10 笔/请求
`DELETE /orders`（批量撤单）	1,000 / 10s（100/s）	15,000 / 10min（25/s）	---
`DELETE /cancel-all`	250 / 10s（25/s）	6,000 / 10min（10/s）	取消全部订单
`DELETE /cancel-market-orders`	1,000 / 10s（100/s）	1,500 / 10min（25/s）	仅取消市价单

5. 其他 API

接口	限制	说明
Relayer `/submit`	25 次 / 分钟	免 Gas 交易提交（严格限制）
用户盈亏（PNL）API	200 次 / 10 秒	查询收益数据

端点（Endpoints）

REST APIs（REST 接口）

API 名称	基础 URL	说明
CLOB API	`https://clob.polymarket.com`	用于订单管理、实时价格查询、订单簿获取等交易核心功能。
Gamma API	`https://gamma-api.polymarket.com`	用于市场发现、事件/市场元数据查询（如事件列表、标签、体育联赛等）。
Data API	`https://data-api.polymarket.com`	用于获取用户相关的持仓、活动记录和交易历史等私有数据。

WebSocket 端点（实时数据流）

服务	URL	说明
CLOB WebSocket	`wss://ws-subscriptions-clob.polymarket.com/ws/`	提供订单簿更新、价格变动（公开频道）及用户订单状态变更（认证频道）的实时推送。
RTDS（实时数据流服务）	`wss://ws-live-data.polymarket.com`	提供低延迟的加密货币价格行情、市场评论等公共实时数据流。

快速参考（Quick Reference）

CLOB API

https://clob.polymarket.com

常用端点：

GET /price --- 获取某 token 的当前价格
GET /book --- 获取某 token 的完整订单簿
GET /midpoint --- 获取中间价（midprice）
POST /order --- 下单（需认证）
DELETE /order --- 撤单（需认证）

📚 完整 CLOB 文档 →

Gamma API

https://gamma-api.polymarket.com

常用端点：

GET /events --- 获取事件列表
GET /markets --- 获取市场列表
GET /events/{id} --- 获取特定事件详情

📚 完整 Gamma 文档 →

Data API

https://data-api.polymarket.com

常用端点：

GET /positions --- 获取用户当前持仓
GET /activity --- 获取用户操作活动
GET /trades --- 获取用户交易历史

📚 完整 Data API 文档 →

CLOB WebSocket

wss://ws-subscriptions-clob.polymarket.com/ws/

频道类型：

market --- 公开频道，接收订单簿和价格更新
user --- 认证频道，接收个人订单状态变更通知

📚 完整 WebSocket 文档 →

RTDS（Real-Time Data Stream）

wss://ws-live-data.polymarket.com

频道类型：

加密货币价格行情（如 BTC、ETH 实时报价）
市场评论流（用户对事件的实时评论）

📚 完整 RTDS 文档 →

构建者计划介绍（Builder Program Introduction）

什么是构建者？（What is a Builder?）

"构建者"是指任何创建平台、应用或服务，并允许其用户通过该系统在 Polymarket 上进行交易的个人、团队或组织 。

例如：

预测市场聚合器
社交交易平台
自动化交易机器人前端
Web3 应用内嵌 Polymarket 交易功能

如果你的系统代表用户向 Polymarket 下单，那么你就是该计划的目标参与者。

计划核心权益（Program Benefits）

1. Relayer 接入（免 Gas 交易）

所有链上操作（如授权、拆分代币、下单等）通过 Polymarket 的 Relayer 执行，用户无需支付 Gas 费。
适用于通过 Proxy Wallet （代理钱包）交易的用户，包括：
- Gnosis Safe 钱包
- Magic Link 用户（由 Relayer Client 自动部署的轻量级代理钱包）
⚠️ 注意：EOA 钱包（如 MetaMask 直连）不享受此服务，Gas 费由用户自行承担。

2. 订单归属（Order Attribution）

通过在请求中添加自定义认证头（headers），将交易归因于你的构建者账户。
归属数据用于：
- 在 构建者排行榜（Builder Leaderboard）上展示业绩；
- 参与 奖励竞争（grants）；
- 通过 Data API 追踪自身平台的交易表现。

对于经你路由的订单，可获得一部分交易手续费分成（具体比例需另行协商或按计划规则执行）。

Relayer 免 Gas 机制详解

当用户通过你的平台使用 Proxy Wallet 时，以下操作均由 Polymarket 支付 Gas 费：

部署 Gnosis Safe 或 Magic Link 代理钱包；
授权 USDCe 和结果代币（token approvals）；
执行 CTF 操作（Split 拆分、Merge 合并、Redeem 赎回）；
通过 CLOB API 提交订单。

✅ 这极大降低了终端用户的使用门槛，尤其适合移动端或非加密原生用户。

交易归属与数据追踪

归属方式 ：在 CLOB API 请求中附加由 Signing SDK 生成的 Builder 认证头。
数据接口 ：
- Leaderboard API：获取指定时间段内构建者的综合排名；
- Volume API：获取每日交易量时间序列，用于趋势分析与业务洞察。

快速入门步骤（Getting Started）

获取构建者凭证
登录 Polymarket 构建者后台，生成专属 API 密钥。
配置订单归属
使用 CLOB Client 并集成 Signing SDK，确保每笔订单正确关联到你的账户。
启用免 Gas 交易
集成 Relayer Client，为用户自动部署代理钱包并执行链上操作。
参考示例项目
官方提供完整的 Next.js 示例应用，展示端到端集成流程。

官方 SDK 与库（SDKs & Libraries）

Polymarket 提供多语言 SDK，简化集成：

功能	TypeScript	Python
CLOB Client	✅ 支持带归属地下单	✅ 支持带归属地下单
Relayer Client	✅ 实现免 Gas 交易	✅ 实现免 Gas 交易
Signing SDK	✅ 签名 Builder 认证头	✅ 签名 Builder 认证头

此外，还提供 库存管理（Inventory Management）工具，帮助构建者高效处理 USDCe 与结果代币之间的转换。

构建者等级（Builder Tiers）

概述（Overview）

无需审批即可集成：任何开发者均可立即创建构建者账户并开始使用。
等级制度目的 ：
- 管理系统资源（如 Relayer 交易次数、API 调用频率）；
- 奖励高绩效集成方（通过奖励、分成、曝光等）；
- 为战略合作伙伴提供专属支持与优先权。
等级越高，权益越丰富：包括更高的限额、专属通道、收入分成、市场提案权等。

核心功能定义（Feature Definitions）

功能	说明
Daily Relayer Txn Limit	每日通过 Relayer 执行的代理钱包操作上限（如部署、授权、拆分等）
API Rate Limits	CLOB、Gamma 等非 Relayer 接口的请求频率限制
Subsidized Transactions	Polymarket 为 Safe/Proxy 钱包用户承担 Gas 费
Order Attribution	订单可归因至你的构建者账户，用于追踪与奖励
RevShare Protocol	允许你在 Polymarket 基础手续费之上加收自定义费用
Leaderboard Visibility	出现在官方构建者排行榜中
Weekly Rewards	基于交易量发放的每周 USDC 奖励
Grants	针对创新性或独家集成的专项资助
Telegram Channel	私有构建者频道，获取公告与技术支持
Badge	个人资料页显示"已验证构建者"徽章
Engineering Support	直接联系 Polymarket 工程团队
Marketing Support	官方社交媒体推广你的平台
Weekly Rewards Boost	奖励金额乘数（如 1.5x）
Priority Access	优先体验新功能或产品（如新市场类型、API）
Market Suggestions	提议新增预测市场主题
Base Fee Split	与 Polymarket 就基础手续费达成收入分成协议

等级对比（Tier Comparison）

功能	未验证（Unverified）	已验证（Verified）	合作伙伴（Partner）
Daily Relayer Txn Limit	100/天	1,500/天	无限制
API Rate Limits	标准	标准	最高
Subsidized Transactions	✅	✅	✅
Order Attribution	✅	✅	✅
RevShare Protocol	❌	✅	✅
Leaderboard Visibility	❌	✅	✅
Weekly Rewards	❌	✅	✅
Telegram Channel	❌	✅	✅
Badge	❌	✅	✅
Engineering Support	❌	标准支持	高级支持
Marketing Support	❌	标准推广	协同营销
Grants	❌	❌	✅
Weekly Reward Boosts	❌	❌	✅
Priority Access	❌	❌	✅
Market Suggestions	❌	❌	✅
Base Fee Split	❌	❌	✅

各等级详情

🔹 未验证（Unverified）

默认等级，所有新构建者自动进入。
每日 Relayer 限额：100 笔。
如何开始 ：
1. 访问 polymarket.com/settings?tab=builder
2. 创建构建者资料并生成 API 密钥
3. 集成 Builder Signing（用于订单归属与 Relayer 访问）
包含权益 ：
- 通过 Safe/Proxy 钱包实现免 Gas 交易；
- Relayer 操作 Gas 补贴（限 100 次/天）；
- 订单归因到你的账户；
- 完整 SDK 与文档访问权限。

🔸 已验证（Verified）

适用对象：需要更高吞吐量的活跃构建者。
升级方式 ：邮件联系 builder@polymarket.com，提供：
- Builder API Key
- 使用场景说明
- 预期交易量
- 应用链接、文档、X（Twitter）账号等
新增权益 （相比未验证）：
- Relayer 限额提升 15 倍（1,500/天）；
- 可启用 RevShare 协议（自定义收费）；
- 进入 构建者排行榜；
- 有资格参与 每周 USDC 奖励计划；
- 获得 官方认证徽章 与 Telegram 私有频道 入口；
- 可申请 创新性集成资助（Grants）。

🔶 合作伙伴（Partner）

定位：企业级集成方或战略生态伙伴。
申请方式：主动联系 Polymarket 商讨合作。
核心升级 （相比已验证）：
- Relayer 交易无上限；
- 最高级别 API 速率限制；
- 高级工程支持（如专属对接人）；
- 联合营销推广（如官方推文、活动联动）；
- 可 提议新预测市场；
- 优先体验新功能；
- 每周奖励乘数加成；
- 可协商 基础手续费分成（Base Fee Split）。

联系方式

如有升级需求或疑问，请联系：

📧 builder@polymarket.com

常见问题（FAQ）

如何知道自己是否已验证？

查看构建者资料页是否有"Verified Builder"徽章，或是否出现在排行榜。
超过每日 Relayer 限额会怎样？

超出部分将无法使用 Relayer，用户需自行支付 Gas（若使用 EOA）或等待次日重置。
能否临时提高限额？

高频需求可申请临时提升，建议直接申请升级至 Verified 或 Partner。

构建者资料与密钥（Builder Profile & Keys）

访问你的构建者资料（Accessing Your Builder Profile）

有两种方式进入构建者设置页面：

直接链接

访问：https://polymarket.com/settings?tab=builder
通过个人菜单
- 点击右上角头像；
- 在下拉菜单中选择 "Builders"。

构建者资料设置（Builder Profile Settings）

在构建者设置页面，你可以自定义公开身份并查看账户信息：

✏️ 自定义构建者身份

字段	说明
Profile Picture（头像）	上传一张图片，将显示在构建者排行榜（Leaderboard）上
Builder Name（名称）	设置公开显示的名称（如 "MyPredictionApp"）

👁️ 查看构建者信息

字段	说明
Builder Address	你的唯一构建者地址（用于系统识别）
Creation Date	账户创建时间
Current Tier	当前等级（如 Unverified 或 Verified），决定你的速率限制与权益

构建者 API 密钥（Builder API Keys）

⚠️ API 密钥是必需的：用于：

接入 Relayer（实现免 Gas 交易）；

在 CLOB 下单时进行订单归属（Order Attribution）。

🔑 创建 API 密钥

在 Builder Keys 区域操作：

查看已有密钥（含创建时间和状态）；
点击 "+ Create New" 生成新密钥。

每组密钥包含三个关键凭证：

凭证	用途
`apiKey`	构建者 API 密钥标识符（用于请求头）
`secret`	用于对请求进行 HMAC 签名的密钥（必须保密）
`passphrase`	额外的身份验证口令（增强安全性）

💡 这些凭证需配合 Signing SDK（TypeScript/Python）使用，以生成合法的认证头。

管理 API 密钥（Managing API Keys）

多环境支持：建议为开发、测试、生产环境分别创建独立密钥；
状态显示 ：有效密钥显示为 "ACTIVE"；
安全建议：如密钥泄露，应立即删除并生成新密钥。

后续步骤（Next Steps）

完成密钥创建后，建议继续以下操作：

配置订单归属 （Order Attribution）

使用 CLOB Client + Signing SDK，确保用户订单正确归因到你的构建者账户。
查看构建者排行榜 （Builder Leaderboard）

检查你的公开资料、交易量和排名（仅 Verified 及以上可见）。
了解构建者等级 （Builder Tiers）

规划如何从 Unverified 升级至 Verified 或 Partner 以解锁更高权限与奖励。

订单归属（Order Attribution）

核心概念

CLOB ：Polymarket 的订单撮合系统，所有交易最终通过 https://clob.polymarket.com 提交。
订单归属（Order Attribution）：通过签名机制，将用户订单与你的构建者身份绑定。
Builder API 凭据 （必须保密）：
- key：API 密钥标识
- secret：用于 HMAC 签名的密钥
- passphrase：额外认证口令

⚠️ 安全警告 ：这些凭据绝不能暴露在前端代码或客户端（如浏览器、移动端 App）中，必须保存在后端服务器或使用安全的远程签名服务。

两种签名方式（Signing Methods）

Polymarket 支持两种集成模式，适用于不同架构：

✅ 1. 远程签名（Remote Signing）【推荐】

适用于：前端（Web/App） + 后端签名服务 的典型架构。

优势：Builder 凭据完全保留在你控制的服务器上，安全性高。

工作流程：

前端调用 CLOB Client；
CLOB Client 将待签名的请求元数据（method, path, body）发送到你的 签名服务器 （/sign）；
签名服务器使用 buildHmacSignature 生成认证头；
CLOB Client 自动将这些头附加到最终请求中，发送至 Polymarket。

🔧 服务端实现（Server Implementation）

TypeScript（Node.js）

ts 复制代码

import { 
  buildHmacSignature, 
  BuilderApiKeyCreds 
} from "@polymarket/builder-signing-sdk";

const BUILDER_CREDENTIALS: BuilderApiKeyCreds = {
  key: process.env.POLY_BUILDER_API_KEY!,
  secret: process.env.POLY_BUILDER_SECRET!,
  passphrase: process.env.POLY_BUILDER_PASSPHRASE!,
};

// POST /sign - 接收来自客户端 SDK 的 { method, path, body }
export async function handleSignRequest(request) {
  const { method, path, body } = await request.json();
  
  const timestamp = Date.now().toString();
  
  const signature = buildHmacSignature(
    BUILDER_CREDENTIALS.secret,
    parseInt(timestamp),
    method,
    path,
    body
  );

  return new Response(JSON.stringify({
    POLY_BUILDER_SIGNATURE: signature,
    POLY_BUILDER_TIMESTAMP: timestamp,
    POLY_BUILDER_API_KEY: BUILDER_CREDENTIALS.key,
    POLY_BUILDER_PASSPHRASE: BUILDER_CREDENTIALS.passphrase,
  }), {
    headers: { "Content-Type": "application/json" }
  });
}

Python（FastAPI/Flask 示例）

python 复制代码

import os
import time
from py_builder_signing_sdk.signing.hmac import build_hmac_signature
from py_builder_signing_sdk import BuilderApiKeyCreds

BUILDER_CREDENTIALS = BuilderApiKeyCreds(
    key=os.environ["POLY_BUILDER_API_KEY"],
    secret=os.environ["POLY_BUILDER_SECRET"],
    passphrase=os.environ["POLY_BUILDER_PASSPHRASE"],
)

def handle_sign_request(method: str, path: str, body: str):
    timestamp = str(int(time.time()))
    
    signature = build_hmac_signature(
        BUILDER_CREDENTIALS.secret,
        timestamp,
        method,
        path,
        body
    )

    return {
        "POLY_BUILDER_SIGNATURE": signature,
        "POLY_BUILDER_TIMESTAMP": timestamp,
        "POLY_BUILDER_API_KEY": BUILDER_CREDENTIALS.key,
        "POLY_BUILDER_PASSPHRASE": BUILDER_CREDENTIALS.passphrase,
    }

📌 使用环境变量管理密钥，切勿提交到 Git！

🖥️ 客户端配置（Client Configuration）

TypeScript

ts 复制代码

import { ClobClient } from "@polymarket/clob-client";
import { BuilderConfig } from "@polymarket/builder-signing-sdk";

// 指向你的签名服务器
const builderConfig = new BuilderConfig({
  remoteBuilderConfig: { 
    url: "https://your-server.com/sign"
  }
});

const client = new ClobClient(
  "https://clob.polymarket.com",
  137,                    // Polygon Chain ID
  signer,                 // 用户的 EOA signer (ethers v5)
  creds,                  // 用户的 CLOB API 凭据
  2,                      // signatureType for Safe proxy wallet
  funderAddress,          // 代理钱包地址
  undefined,
  false,
  builderConfig           // 注入 Builder 配置
);

// 下单时自动调用签名服务器
const order = await client.createOrder({
  price: 0.40,
  side: "BUY",
  size: 5,
  tokenID: "YOUR_TOKEN_ID"
});

await client.postOrder(order);

Python

python 复制代码

from py_clob_client.client import ClobClient
from py_builder_signing_sdk import BuilderConfig, RemoteBuilderConfig

builder_config = BuilderConfig(
    remote_builder_config=RemoteBuilderConfig(
        url="https://your-server.com/sign"
    )
)

client = ClobClient(
    host="https://clob.polymarket.com",
    chain_id=137,
    key=private_key,        # 用户私钥（谨慎处理！）
    creds=creds,            # 用户 CLOB 凭据
    signature_type=2,       # Safe 代理钱包类型
    funder=funder_address,  # 代理钱包地址
    builder_config=builder_config
)

order = client.create_order({
    "price": 0.40,
    "side": "BUY",
    "size": 5,
    "token_id": "YOUR_TOKEN_ID"
})

client.post_order(order)

✅ 2. 本地签名（Local Signing）

适用于：全后端系统（如自动化做市机器人、机构交易平台），你完全控制订单生成和提交流程。

工作流程：

你的服务直接使用 Builder 凭据在本地生成认证头；
整个请求不经过第三方前端，Builder 密钥仍需严格保护（仅限可信后端）。

🖥️ 客户端（即服务端）配置

TypeScript

ts 复制代码

import { ClobClient } from "@polymarket/clob-client";
import { BuilderConfig, BuilderApiKeyCreds } from "@polymarket/builder-signing-sdk";

const builderCreds: BuilderApiKeyCreds = {
  key: process.env.POLY_BUILDER_API_KEY!,
  secret: process.env.POLY_BUILDER_SECRET!,
  passphrase: process.env.POLY_BUILDER_PASSPHRASE!
};

const builderConfig = new BuilderConfig({
  localBuilderCreds: builderCreds
});

const client = new ClobClient(
  "https://clob.polymarket.com",
  137,
  signer,
  creds,
  2,
  funderAddress,
  undefined,
  false,
  builderConfig
);

const order = await client.createOrder({
  price: 0.40,
  side: "BUY",
  size: 5,
  tokenID: "YOUR_TOKEN_ID"
});

await client.postOrder(order); // 自动附加 Builder 头

Python

python 复制代码

import os
from py_clob_client.client import ClobClient
from py_builder_signing_sdk import BuilderConfig, BuilderApiKeyCreds

builder_creds = BuilderApiKeyCreds(
    key=os.environ["POLY_BUILDER_API_KEY"],
    secret=os.environ["POLY_BUILDER_SECRET"],
    passphrase=os.environ["POLY_BUILDER_PASSPHRASE"]
)

builder_config = BuilderConfig(
    local_builder_creds=builder_creds
)

client = ClobClient(
    host="https://clob.polymarket.com",
    chain_id=137,
    key=private_key,
    creds=creds,
    signature_type=2,
    funder=funder_address,
    builder_config=builder_config
)

order = client.create_order({
    "price": 0.40,
    "side": "BUY",
    "size": 5,
    "token_id": "YOUR_TOKEN_ID"
})

client.post_order(order)

⚠️ 即使是本地签名，也必须使用环境变量或密钥管理服务（如 AWS Secrets Manager）存储凭据。

认证头说明（Authentication Headers）

无论哪种方式，最终请求都会包含以下四个头：

Header	说明
`POLY_BUILDER_API_KEY`	你的 Builder Key
`POLY_BUILDER_TIMESTAMP`	签名时间戳（Unix 毫秒）
`POLY_BUILDER_PASSPHRASE`	Passphrase
`POLY_BUILDER_SIGNATURE`	对 `(timestamp + method + path + body)` 的 HMAC-SHA256 签名

SDK 会自动处理这些头的生成与附加。

后续步骤（Next Steps）

✅ 集成 Relayer Client 实现免 Gas 交易；
📊 通过 Data API 或 Leaderboard API 监控你的交易量；
🏆 查看 Builder Leaderboard 确认归属是否生效；
🔑 回顾 [Builder Profile & Keys](#Builder Profile & Keys) 确保凭据正确配置。

示例（Examples）

概述（Overview）

所有示例应用均涵盖以下关键能力：

✅ 身份认证（Authentication）：支持多种钱包登录方式；
✅ 免 Gas 交易（Gasless Trading）：通过 Gnosis Safe 或 Proxy 代理钱包，由 Polymarket 承担链上操作的 Gas 费；
✅ 完整集成 （Full Integration）：
- 下单（Orders）
- 查看持仓（Positions）
- 执行 CTF 操作（如 Split 拆分、Merge 合并、Redeem 赎回）

这些项目代码开源，可直接作为开发模板使用。

支持的钱包集成类型

🔐 Safe 钱包示例（Safe Wallet Examples）

具体例子上链接去看

适用于为新用户部署 Gnosis Safe 智能合约钱包的场景，支持多种钱包提供商：

集成方案	说明
wagmi + Safe	使用 wagmi 框架，兼容 MetaMask、Phantom、Rabby 等主流浏览器钱包作为 Owner
Privy + Safe	结合 Privy 嵌入式钱包，支持社交/邮箱登录，并自动创建 Safe 钱包
Magic Link + Safe	使用 Magic Link 实现无密钥登录（邮箱/社交），后端自动部署 Safe 钱包
Turnkey + Safe	集成 Turnkey 嵌入式 MPC 钱包，提供高安全性的私钥管理

💡 这些方案适合希望为用户提供全新、可编程、Gasless 的交易体验的平台。

🧩 Proxy 钱包示例（Proxy Wallet Examples）

专为已使用 Polymarket.com Magic Link 登录的现有用户设计：

集成方案	说明
Magic Link + Proxy	自动为来自 Polymarket.com 的 Magic 用户部署轻量级自定义代理钱包（Custom Proxy Wallet），复用其身份，实现无缝迁移与 Gasless 交易

⚠️ 注意：Proxy 钱包仅适用于特定用户群体（即已在 Polymarket 使用 Magic 登录的用户），而 Safe 钱包适用于所有新用户。

polymarket开发文档-Developer Quickstart + Polymarket Builders Program

Fetching Market Data

1. 零门槛访问

2. Polymarket 数据模型

3. 获取活跃事件

4. 市场发现最佳实践

▶ 体育赛事

▶ 非体育话题（政治、经济、科技等）

5. 获取具体市场详情

6. 获取实时价格与订单簿

Placing Your First Order

安装依赖

TypeScript

Python

Step 1: 使用私钥初始化客户端

TypeScript

Python

Step 2: 派生用户 API 凭据

TypeScript

Python

Step 3: 配置签名类型（Signature Type）和资金方地址（Funder Address）

Step 4: 使用完整认证信息重新初始化客户端

TypeScript

Python

Step 5: 下单交易

TypeScript

Python

Step 6: 查询与管理订单

TypeScript

Python

常见问题排查（Troubleshooting）

添加 Builder API 凭据（用于应用开发者）

TypeScript（仅展示添加方式）

术语表（Glossary）

市场与事件（Markets & Events）

交易（Trading）

订单类型（Order Types）

市场类型（Market Types）

钱包（Wallets）

代币操作（CTF，Conditional Token Framework）

基础设施（Infrastructure）

API 速率限制（API Rate Limits）

限流机制说明

各类 API 速率限制详情

1. 通用速率限制

2. Data API（用户数据接口）

3. Gamma API（市场发现与元数据）

4. CLOB API（核心交易接口）

▶ 通用 CLOB 端点

▶ 市场数据（行情）

▶ 账户与通知（Ledger）

▶ 市场与定价配置

▶ 认证

▶ 交易操作（下单/撤单）

5. 其他 API

端点（Endpoints）

REST APIs（REST 接口）

WebSocket 端点（实时数据流）

快速参考（Quick Reference）

CLOB API

Gamma API

Data API

CLOB WebSocket

RTDS（Real-Time Data Stream）

构建者计划介绍（Builder Program Introduction）

什么是构建者？（What is a Builder?）

计划核心权益（Program Benefits）

1. Relayer 接入（免 Gas 交易）

2. 订单归属（Order Attribution）

3. 费用分成（Fee Share）

Relayer 免 Gas 机制详解

交易归属与数据追踪

快速入门步骤（Getting Started）

官方 SDK 与库（SDKs & Libraries）

构建者等级（Builder Tiers）

概述（Overview）

核心功能定义（Feature Definitions）

等级对比（Tier Comparison）

各等级详情

🔹 未验证（Unverified）