polymarket-skill

Polymarket Skill (CLOB V2)

会话初始化

执行任何 Polymarket 命令前，请确认已设置 Polymarket 密钥：

agent polymarket proxy-wallet

如果返回结果中 ok: true，且包含 eoaAddress 和 proxyWalletAddress，则表示密钥已配置，可以直接开始交易。如果出现错误，用户需要运行 set-key（见下文「入门设置」）。

---

了解这 3 个地址

每位 Polymarket 用户都有 3 个地址。请勿混淆：

名称	含义	用途
EOA	私钥所有者。在 CLI 输出中显示为 eoaAddress	为交易和 CLOB 订单签名。仅在运行 approve 时需要 POL 支付 Gas
代理钱包	在 CLI 输出中显示为 proxyWalletAddress。这是 Polymarket 在 UI 中显示的「您的地址」	持有 pUSD 和结果代币。CLOB 的 maker
智能钱包	OMS 钱包（agent wallet）	按笔交易向代理钱包转入 USDC.e（自动兑换为 pUSD）

交易时： USDC.e 从 OMS 智能钱包流向代理钱包 → 自动兑换为 pUSD → 用于 CLOB 订单。代理钱包是交易身份。

---

交易前检查清单

下单前，请按顺序确认以下四项：

1. 已配置 EOA 密钥

agent polymarket proxy-wallet
# → must return ok: true with eoaAddress and proxyWalletAddress

2. 已接受 Polymarket 服务条款 ← 每个 EOA 仅需一次，永久有效

• 访问 https://polymarket.com，使用 EOA 地址连接并接受服务条款
• 如果尚未接受服务条款，提交 CLOB 订单会失败并提示 not authorized
• 如果用户之前已使用此 EOA 在 Polymarket 交易，则表示已接受服务条款 — 跳过此步骤

3. 代理钱包已为 V2 交易所设置授权 ← V2 迁移后所有用户都必须设置

• 授权可使代理钱包与 V2 CTF 交易所合约和 CollateralOnramp 交互
• 所有用户都必须在 V2 迁移后（2026 年 4 月 28 日）运行 approve --broadcast — 旧交易所合约上的 V1 授权不会迁移
• 运行一次 V2 授权后，该授权会永久记录在链上，适用于此 EOA

4. 智能钱包中有 USDC.e ← 每笔交易都需要，最低 $1

agent balances
# → check USDC.e balance (0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174)
# → must have at least $1 USDC.e to place any order
# → USDC.e is auto-wrapped to pUSD during the buy flow

---

入门设置：首次配置

选项 A — 使用电子邮件登录（已有 Polymarket 账户）

步骤 1：从 Polymarket 获取私钥

1. Go to: https://reveal.magic.link/polymarket
2. Connect/authenticate with the same email used for Polymarket
3. Copy the exported private key (0x...)

步骤 2：将密钥导入 CLI

agent polymarket set-key <privateKey>

输出会确认 eoaAddress 和 proxyWalletAddress。

步骤 3：向用户显示其地址

agent polymarket proxy-wallet

告诉用户：「您的 EOA 是 <eoaAddress> — 一次性授权步骤需要少量 POL。您的 Polymarket 交易地址（代理钱包）是 <proxyWalletAddress> — 您的 pUSD 和结果代币存放在这里。」

步骤 4：为 EOA 转入 POL 以支付 Gas（仅用于授权步骤）

agent send-native --to <eoaAddress> --amount 0.1 --broadcast

EOA 只需在一次性 approve 交易中使用 POL。之后交易无需 EOA 支付 Gas。

步骤 5：接受服务条款

1. Go to https://polymarket.com
2. Connect with the EOA address
3. Accept Terms of Service when prompted

步骤 6：为 V2 设置代理钱包授权（一次性，永久有效）

agent polymarket approve --broadcast

此操作会为 V2 交易所合约和 CollateralOnramp 设置授权。授权永久记录在链上 — 此 EOA 无需再次运行。

选项 B — 使用构建者 EOA（没有 Polymarket 账户）

步骤 1：确认地址

agent polymarket proxy-wallet

步骤 2：接受服务条款（必需）

1. Go to https://polymarket.com
2. Connect with the EOA address shown above
3. Accept Terms of Service when prompted

步骤 3：为 EOA 转入 POL 以支付 Gas

agent send-native --to <eoaAddress> --amount 0.1 --broadcast

步骤 4：为 V2 设置代理钱包授权（一次性）

agent polymarket approve --broadcast

---

命令

浏览市场

# List top markets by volume
agent polymarket markets

# Search by keyword
agent polymarket markets --search "bitcoin" --limit 10

# Paginate
agent polymarket markets --limit 20 --offset 20

每个市场的关键输出字段：

• conditionId — 所有交易命令都需要的 ID
• question — 市场提出的问题
• yesPrice / noPrice — 当前概率（0 到 1，例如 0.65 = 65%）
• negRisk — 如果为 true，在该市场交易前设置 neg-risk 授权
• endDate — 市场结算时间

获取单个市场

agent polymarket market <conditionId>

下单前可用此命令确认价格和代币 ID。

显示代理钱包地址

agent polymarket proxy-wallet

确认当前使用的 EOA 和代理钱包。pUSD 和代币存放在代理钱包中。

设置授权（V2 迁移后必需）

# Standard markets
agent polymarket approve --broadcast

# Neg-risk markets (only if you see negRisk: true on a market you want to trade)
agent polymarket approve --neg-risk --broadcast

所有用户都必须在 V2 迁移后执行此操作——旧交易合约上的 V1 授权不会沿用。V2 授权涵盖：pUSD → V2 交易所、CTF → V2 交易所，以及 USDC.e → CollateralOnramp（用于包装）。设置后，这些授权会永久保留在链上。

买入仓位

# Dry-run first — always check before executing
agent polymarket clob-buy <conditionId> YES|NO <usdcAmount>

# Execute — funds proxy wallet, wraps USDC.e → pUSD, then places order
agent polymarket clob-buy <conditionId> YES|NO <usdcAmount> --broadcast

# If proxy wallet already has pUSD from a previous failed order (skip the funding step)
agent polymarket clob-buy <conditionId> YES|NO <usdcAmount> --skip-fund --broadcast

# Limit order — fill only at this price or better
agent polymarket clob-buy <conditionId> YES <usdcAmount> --price 0.45 --broadcast

工作原理：

1. 智能钱包将 usdcAmount USDC.e 转至代理钱包（OMS 交易）
2. 代理钱包通过 CollateralOnramp 将 USDC.e 包装为 pUSD（链上操作，消耗 EOA Gas）
3. 提交 CLOB BUY 订单：maker=代理钱包，signer=EOA（链下操作，不消耗 Gas）
4. 成交后，代币会到达代理钱包

订单类型：

• 不指定 --price：FOK 市价单（全部成交，否则取消）
• --fak：FAK 市价单（允许部分成交）
• --price 0.x：GTC 限价单（保持挂单，直至成交或取消）

订单最低金额：$1。 CLOB 会拒绝低于 $1 的订单。如果资金划转和包装步骤已执行，但订单遭到拒绝，pUSD 会留在代理钱包中——重试时使用 --skip-fund。

卖出仓位

# Dry-run first
agent polymarket sell <conditionId> YES|NO <shares>

# Execute
agent polymarket sell <conditionId> YES|NO <shares> --broadcast

# Limit sell
agent polymarket sell <conditionId> YES <shares> --price 0.80 --broadcast

<shares> 是结果代币的数量（不是美元）。从 positions 获取份额数量。 卖出完全在链下进行——不消耗 Gas，也没有链上交易。卖出所得以 pUSD 形式存入代理钱包。

查看仓位

agent polymarket positions

显示代理钱包中的所有未平仓仓位，包括当前价值、盈亏和结果。

查看未成交订单

agent polymarket orders

列出仍未成交的 GTC 限价单（FOK/FAK 订单不会处于“未成交”状态——它们会立即成交或取消）。

取消订单

agent polymarket cancel <orderId>

从 orders 命令的输出或 clob-buy 输出中的 orderId 字段获取 orderId。

---

完整的自主交易流程

# ── FIRST TIME (run once per EOA) ──────────────────────────────────────

# 1. Import Polymarket private key
agent polymarket set-key 0x<yourPrivateKey>
# → save eoaAddress and proxyWalletAddress

# 2. Accept ToS at https://polymarket.com (connect EOA, accept when prompted)

# 3. Fund EOA with POL for the one-time approval tx
agent send-native --to <eoaAddress> --amount 0.1 --broadcast

# 4. Set V2 approvals (one-time, permanent — covers pUSD, CTF, and CollateralOnramp)
agent polymarket approve --broadcast

# ── RETURNING USER ──────────────────────────────────────────────────────
# If V2 approvals were already set: skip steps 1-4, go straight to trading.
# NOTE: V1 approvals (pre-April 28 2026) do NOT carry over — re-run approve once.

# ── FIND A MARKET ────────────────────────────────────────────────────────

# 5. Search for markets
agent polymarket markets --search "bitcoin" --limit 10

# 6. Get details on a specific market
agent polymarket market 0x<conditionId>
# → check: yesPrice, noPrice, negRisk, endDate
# → if negRisk: true → run approve --neg-risk --broadcast first

# ── ENTER A POSITION ────────────────────────────────────────────────────

# 7. Dry-run to confirm
agent polymarket clob-buy 0x<conditionId> YES 5
# → review: currentPrice, proxyWalletAddress, flow (includes pUSD wrapping)

# 8. Execute
agent polymarket clob-buy 0x<conditionId> YES 5 --broadcast
# → check: orderStatus === "matched"

# ── MANAGE ──────────────────────────────────────────────────────────────

# 9. Check positions
agent polymarket positions
# → review: size (shares), curPrice, cashPnl

# 10. Sell when ready
agent polymarket sell 0x<conditionId> YES <shares> --broadcast
# → orderStatus === "matched" means pUSD is back in proxy wallet

---

自主 Agent 的决策逻辑

决定是否买入时：

1. 运行 proxy-wallet——确认 EOA 和代理钱包地址
2. 运行 balances——确认智能钱包中至少有 $1 USDC.e
3. 检查 positions——避免加仓已有仓位
4. 检查 markets——使用 yesPrice/noPrice 作为概率输入
5. 检查目标市场的 negRisk——如果为 true，确认已设置否定风险授权
6. 如果代理钱包已有上次尝试留下的足够 pUSD，则使用 --skip-fund
7. 始终先进行试运行，然后再广播

决定是否卖出时：

1. 从 positions 获取当前 size（份额）
2. 使用 curPrice 与 avgPrice 评估盈亏
3. 市价卖出（sell --broadcast）以立即退出
4. 限价卖出（--price 0.x --broadcast）以等待更好的价格

---

故障排除

错误	原因	解决方法
No EOA key found	尚未运行 set-key	运行 agent polymarket set-key <pk>
Could not create api key（仅 stderr）	尚未接受服务条款	非致命错误——CLI 会使用 deriveApiKey 重试，仍可能成功。如果订单也失败，请访问 polymarket.com 并使用 EOA 接受服务条款
CLOB order error: not authorized	尚未接受服务条款	访问 polymarket.com，连接 EOA 钱包并接受条款
insufficient funds for gas	EOA 没有 POL	agent send-native --to <eoaAddress> --amount 0.1 --broadcast
Market not found	市场交易量低或已关闭	市场可能已结算；尝试使用 --search 并更换搜索词
Market has no tokenIds	市场已关闭	检查 endDate——市场已结算
FOK 的 orderStatus: "unmatched"	市价下没有流动性	尝试使用 --fak 部分成交，或使用 --price 0.x 限价下单
invalid amount for a marketable BUY order ($X), min size: $1	金额低于 CLOB 最低金额	至少使用 $1。如果 pUSD 已经到账，使用 --skip-fund 重试
Wallet not found: main	尚未登录	运行 agent wallet login
会话过期（OMS_SESSION_EXPIRED）	登录会话已过期（约 1 周）	运行 agent wallet login
V2 迁移后授权交易回退	V1 授权使用了错误的交易合约	重新运行 agent polymarket approve --broadcast，以授权 V2 合约

---

Agent 关键事实

• CLOB V2 已启用（自 2026 年 4 月 28 日起）。抵押品为 pUSD，而非 USDC.e。
• 所有命令默认以试运行模式执行。 不带 --broadcast 时，approve、clob-buy 和 sell 均不会执行任何操作。
• 所有用户都必须完成 V2 授权。 旧交易所合约上的 V1 授权不会沿用。迁移后运行一次 approve --broadcast。
• clob-buy 会自动处理完整流程： 将 USDC.e 从智能钱包转入代理钱包，将 USDC.e 兑换为 pUSD，然后下达 CLOB 订单（除非使用 --skip-fund）。
• 持仓位于代理钱包中，而非 OMS 智能钱包。positions 会查询代理钱包。
• 卖出免费。 无需 gas，也不会产生链上交易。通过 CLOB 卖出时，仅发送经过签名的链下消息。卖出所得为 pUSD。
• orderStatus: "matched" 表示交易已成交。"unmatched" 表示 FOK 失败（流动性不足）。
• 费用由协议在撮合时确定。 做市方无需支付费用，只有吃单方需要支付。订单中没有 feeRateBps。
• 代理钱包地址永远不会改变。 它通过 CREATE2 根据 EOA 确定性生成。
• 标准错误输出中的 Could not create api key 不会导致操作失败。 CLI 会自动处理此问题。