polymarket

Polymarket 交易（CLOB V2）

以脚本为主。每个工作流只需调用一次 bash，最多再调用一次 wallet_sign_typed_data（这是钱包 RPC，无法通过脚本调用）。已通过实时验证：请参见 Changelog v5.1.0。

---

简明指南——3 步完成交易

# 1. One-time setup (idempotent — safe to re-run)
python3 scripts/setup.py --all 10        # wrap 10 USDC.e -> pUSD + all approvals

# 2. Find a market
python3 scripts/search.py "trump" --limit 3   # returns token_ids

# 3. Place order
python3 scripts/prepare_order.py <token_id> BUY <price> <size>
# → sign /tmp/poly_order.json via wallet_sign_typed_data
python3 scripts/post_order.py <signature>

所有脚本都位于 skills/polymarket/scripts/，并假定当前工作目录是技能文件夹。

---

账户前置条件（一次性链上操作）

CLOB V2 使用 pUSD（ERC-20 USDC 包装代币）进行结算，而不是原始 USDC.e。首次下单前，EOA 必须：

1. 在 Polygon 上持有 USDC.e（数量至少达到你想交易的金额）。
2. 通过 CollateralOnramp.wrap() 将 USDC.e 包装为 pUSD。
3. 对 3 个 V2 交易所 spender 执行 approve(pUSD, spender, MAX)。
4. 对相同的 3 个 spender 执行 setApprovalForAll(CTF, spender, true)（卖出／赎回时需要）。

scripts/setup.py 会完成以上所有操作，并且是幂等的：它会读取链上状态，并跳过已完成的操作。Gas 由 Privy/Alchemy paymaster 赞助，用户无需支付 MATIC。

python3 scripts/setup.py                  # dry-run: show current state + next step
python3 scripts/setup.py --all 10         # wrap 10 USDC.e + approve everything
python3 scripts/setup.py --wrap 50        # wrap more later
python3 scripts/setup.py --approve        # re-issue approvals only

---

脚本

脚本	用途	工具调用次数
setup.py	一次性包装并授权（幂等）	0–8 次 wallet_transfer
search.py	查找事件／市场，返回 token_ids + 实时价格	0
status.py	余额 + 持仓 + 未成交订单 + 最近交易	0
prepare_order.py	获取订单簿 + 构建 EIP-712 载荷	0
post_order.py	提交已签名订单并验证成交情况	0
cancel.py	取消单个订单（--id）或全部订单（--all）	0
close_positions.py	为所有持仓构建 SELL 订单	0
auth.py	检查／从钱包派生 CLOB API 密钥	0–1 次签名

搜索

python3 scripts/search.py "ceasefire" --limit 3

• 使用简短关键词（trump、btc、ceasefire），不要输入完整的问题原文——较长的查询通常会返回空结果。
• 输出 JSON 包含 outcomes[i].token_id（YES = 索引 0，NO = 索引 1）和当前价格。

下单——完整流程

# 1. Prepare: fetches market info + orderbook, writes /tmp/poly_order.json
python3 scripts/prepare_order.py 7892825...50228 BUY 0.65 10

# 2. Sign (Python in agent runtime, ONE tool call)
#    from core.skill_tools import wallet
#    p = json.load(open('/tmp/poly_order.json'))
#    sig = wallet.wallet_sign_typed_data(
#        domain=p['domain'], types=p['types'],
#        primaryType=p['primaryType'], message=p['message']
#    )['signature']

# 3. Post: submits and prints order ID + fill status + tx hash
python3 scripts/post_order.py 0xSIGNATURE

平掉一个或所有持仓

python3 scripts/close_positions.py                # all positions
python3 scripts/close_positions.py --token_id X   # one position
# → writes one /tmp/poly_close_N.json per position; sign each + post

---

YES / NO 与订单簿

每个二元市场都有两个互补代币：YES + NO ≈ $1.00。

下注	操作	使用	买入价格
事件会发生	BUY YES	outcomes[0].token_id	YES 价格
事件不会发生	BUY NO	outcomes[1].token_id	NO 价格

务必查看你打算买入的代币对应的订单簿：

• BUY → 入场价 ≈ best_ask
• SELL → 出场价 ≈ best_bid
• 如果看到 0.01 / 0.99，说明你查看的是错误代币的订单簿。

---

订单规则（CLOB V2）

• 最低订单金额： $1（即 price × size ≥ 1.0）
• 最小数量： 5 份
• 价格刻度： prepare_order.py 会自动规范化（通常为 $0.01）
• signatureType： Privy 钱包始终使用 0（EOA）

V2 线格式严格——post_order.py 已处理这些要求，但如果你要手动构建载荷：

• salt 必须是 int（不能是字符串）
• 不要发送 taker / nonce / feeRateBps（这些是 V1 字段，V2 中已移除）
• metadata 和 builder 均为 bytes32 零值（0x + 64 个零）

---

刷新身份验证

CLOB 凭据（POLY_API_KEY / POLY_SECRET / POLY_PASSPHRASE）通过一次钱包签名派生并持久保存。如果 status.py 返回 401：

python3 scripts/auth.py --check                   # quick sanity check
python3 scripts/auth.py --prepare 0xWALLET        # build signing payload
# → wallet_sign_typed_data(...)
python3 scripts/auth.py --save 0xSIG 0xWALLET TIMESTAMP

不变条件：--save 中的 TIMESTAMP 和 0xWALLET 必须与最近一次 --prepare 中的值一致。如果仍然返回 401，请使用新的时间戳重新执行完整的 prepare→sign→save 流程。

---

地理位置／VPN

CLOB API 会屏蔽来自美国 IP 的访问。scripts/common.py 会自动通过 sc-vpn.internal:8080 路由，并缓存速度最快的区域。无需 Agent 采取任何操作。使用 POLY_VPN_REGION=ar 覆盖，或使用 POLY_DISABLE_VPN=true 禁用。

---

错误 → 修复方法

错误	原因	修复方法
Invalid order payload	V2 网络格式错误（盐值为字符串 / 含有额外的 V1 字段）	使用 post_order.py（它会发送正确的格式）
invalid amount for a marketable BUY order ($X), min size: $1	订单金额 < $1	将价格 × 数量提高到 ≥ $1
not enough balance / 购买力为 0	pUSD 尚未包装，或缓存中的 signature_type 不匹配	运行 setup.py --all 10，然后运行 status.py
L2_BALANCE_TOO_LOW	EOA 中没有 pUSD	包装更多：setup.py --wrap N
order_version_mismatch	使用了旧版 V1 签名架构	重新运行 prepare_order.py（使用 V2 域 version=2）
401 / Invalid API key	CLOB 凭据已过期	使用 auth.py 刷新流程
403 地理位置限制	VPN 状态不佳	重试；如果问题仍然存在，将 POLY_VPN_REGION 设置为其他区域
订单簿显示 0.01 / 0.99	查看了错误结果的订单簿	使用你实际计划购买的 token_id

已知的暂时性错误

• Privy / Alchemy paymaster HTTP 500 可能会在短时间内连续进行链上调用时出现。
• 这通常是暂时的基础设施波动，并非钱包 / 技能问题。
• 实用的解决方法：等待约 10 秒，然后重试相同步骤。

---

架构摘要

• 钱包： Privy EOA，signatureType=0。Agent 通过 wallet_sign_typed_data 签署 EIP-712；Agent 上下文中不包含私钥。
• Gas： 由 Alchemy paymaster 赞助 — 每次链上调用都会通过 wallet_transfer 路由。
• 抵押品： pUSD（0xC011a7E1...DFB），6 位小数，与 USDC.e 按 1:1 比例包装。
• 交易所： CTF Exchange V2（二元）、Neg-Risk Adapter、Neg-Risk Exchange V2 — SELL / 结算都必须获得这 3 项批准。
• CLOB： https://clob.polymarket.com（V2 后端，自 2026 年 4 月 28 日起上线）。L1 = 钱包签名，L2 = 使用派生 API 密钥生成的 HMAC。

---

更新日志

• v6.0.1 — 错误修复：（1）scripts/common.py::save_env_var() 现在会处理 .env 文件末尾缺少换行符的情况，以防止密钥拼接；（2）scripts/close_positions.py 已从 V1 网络字段迁移到 CLOB V2 架构（timestamp/metadata/builder，域 version=2），与 prepare_order.py 保持一致。新增“已知的暂时性错误”说明，介绍 Privy/Alchemy paymaster 在短时间内连续调用时偶尔出现 HTTP 500 的情况（约 10 秒后重试）。
• v6.0.0 — 重大更新：全面重写 SKILL，使内容更清晰（“3 步完成交易”）；新增幂等的 setup.py，用于一次性包装和批准；已在 CLOB V2 上完成端到端实时验证（BUY 0x43f20c67...20b653 → SELL 0x19f475e4...fedde1，5 NO @ 0.989 → @ 0.988，滑点约 $0.005）。完全取代 V1 时代的流程。
• v5.1.0 — 新增 setup.py（幂等包装和批准）。全面重写 SKILL，使内容更清晰。已完成实时验证：BUY 0x43f20c67...20b653，SELL 0x19f475e4...fedde1（5 NO @ 0.989 → @ 0.988，滑点约 $0.005）。
• v5.0.5 — 修复 CLOB V2 网络格式：salt 必须是整数；移除 taker/nonce/feeRateBps。
• v5.0.4 — 迁移到 V2 EIP-712 域（version=2）、V2 合约和 V2 订单字段。
• v5.0.0 — 采用脚本优先架构（BUY：8 次调用 → 3 次）。