polymarket

Polymarket

通过终端查询 Polymarket 预测市场并进行交易。浏览赔率、研究事件、比较市场、跟踪投资组合、流式接收实时数据、桥接资金并执行交易——全部通过自然语言完成。

Polymarket 提供 4 个独立 API，以及 Gamma 便捷层。本技能涵盖所有 API。

设置

只读命令可立即使用（无需安装）。浏览、搜索、查看热门内容、类别、市场研究和比较模式均使用公开的 Gamma API。

如需交易、查看订单簿、价格历史记录和使用高级功能，请安装 Polymarket CLI（Rust 二进制文件，v0.1.5+）：

brew install polymarket/tap/polymarket-cli

如需交易，请设置钱包：

polymarket wallet create
polymarket approve set

或者手动使用私钥配置 ~/.config/polymarket/config.json。详情请参阅 CLI 文档。

CLI 还提供交互式 REPL：

polymarket shell

在任何 CLI 命令中使用 --output json，即可获取适合脚本处理和管道传递的机器可读输出。

命令

浏览市场（无需 CLI）

# Trending/active markets (sorted by 24h volume)
python3 {baseDir}/scripts/polymarket.py trending

# Trending with more results
python3 {baseDir}/scripts/polymarket.py trending --limit 20

# Search markets by keyword
python3 {baseDir}/scripts/polymarket.py search "trump"

# Get specific event by slug
python3 {baseDir}/scripts/polymarket.py event "fed-decision-in-october"

# Get markets by category
python3 {baseDir}/scripts/polymarket.py category politics
python3 {baseDir}/scripts/polymarket.py category crypto
python3 {baseDir}/scripts/polymarket.py category sports
python3 {baseDir}/scripts/polymarket.py category tech
python3 {baseDir}/scripts/polymarket.py category entertainment
python3 {baseDir}/scripts/polymarket.py category science
python3 {baseDir}/scripts/polymarket.py category business

热门市场仪表板（无需 CLI）

显示 Polymarket 上最热门市场的分类仪表板。结合热门市场与类别筛选条件，构建完整概览。

# Full trending dashboard - run these in sequence to build a picture:
python3 {baseDir}/scripts/polymarket.py trending --limit 10
python3 {baseDir}/scripts/polymarket.py category politics --limit 5
python3 {baseDir}/scripts/polymarket.py category crypto --limit 5
python3 {baseDir}/scripts/polymarket.py category sports --limit 5
python3 {baseDir}/scripts/polymarket.py category tech --limit 5

当用户要求查看“仪表板”或“概览”时，运行所有类别查询，并按版块分组展示结果，同时使用清晰的标题。列出每个市场的交易量和当前赔率。

市场研究模式（无需 CLI）

市场研究将 Polymarket 赔率与背景分析结合起来。当用户要求“研究”某个市场，或希望获取赔率以外的深入分析时：

1. 获取市场数据：使用搜索或事件命令
2. 分析赔率：市场反映了什么？是否存在优势？
3. 提供背景信息：运用你的知识解释影响赔率的因素
4. 展示历史走势：如果 CLI 可用，获取价格历史记录
5. 对比共识：Polymarket 赔率与民调、专家意见或其他预测市场相比如何？

# Step 1: Find the market
python3 {baseDir}/scripts/polymarket.py search "fed rate cut"

# Step 2: Get detailed event data
python3 {baseDir}/scripts/polymarket.py event "fed-rate-decision-march-2026"

# Step 3: If CLI available, get price history to show trend
python3 {baseDir}/scripts/polymarket.py price-history TOKEN_ID --interval 1d

# Step 4: Check order book depth for liquidity assessment
python3 {baseDir}/scripts/polymarket.py book TOKEN_ID

收集数据后，将研究结果综合整理为一份结构化报告：

• 当前赔率：是/否的百分比及其含义
• 交易量与流动性：该市场的资金规模如何？流动性是否足以支持交易？
• 趋势：赔率是在上升还是下降？近期是否出现任何突变？
• 背景信息：哪些现实世界事件或数据点正在影响赔率？
• 关键日期：市场何时结算？近期是否有催化事件？
• 风险因素：哪些因素可能导致赔率突然变动？

市场比较模式（无需 CLI）

并排比较相关市场。这有助于发现套利机会、理解条件概率，或了解不同结果之间的关联。

# Compare two or more related markets by searching for each
python3 {baseDir}/scripts/polymarket.py search "trump 2028"
python3 {baseDir}/scripts/polymarket.py search "desantis 2028"
python3 {baseDir}/scripts/polymarket.py search "newsom 2028"

当用户要求“比较市场”或“并排查看赔率”时：

1. 搜索用户提到的每个市场
2. 使用比较表格展示赔率
3. 指出交易量差异（交易量越高，赔率越可靠）
4. 标记任何明显的不一致（例如，概率总和理应约为 100%，但实际并非如此）
5. 突出相关结果之间的价差

按表格格式展示比较结果：

Market Comparison: 2028 Presidential Election

| Candidate     | Yes     | Volume  | Liquidity |
|---------------|---------|---------|-----------|
| Trump         | 32.5%   | $4.2M   | High      |
| DeSantis      | 18.1%   | $1.8M   | Medium    |
| Newsom        | 12.4%   | $890K   | Medium    |
| Harris        | 8.7%    | $2.1M   | Medium    |

投资组合仪表板（需要 CLI 和钱包）

在一个视图中查看完整投资组合，包括持仓、盈亏和未结订单。

# View all open positions
python3 {baseDir}/scripts/polymarket.py positions

# View positions for a specific wallet
python3 {baseDir}/scripts/polymarket.py positions --address 0xYOUR_WALLET

# Check USDC balance
python3 {baseDir}/scripts/polymarket.py wallet-balance

# Check balance for a specific token
python3 {baseDir}/scripts/polymarket.py wallet-balance --token TOKEN_ID

# List all open orders
python3 {baseDir}/scripts/polymarket.py orders

当用户要求查看“投资组合仪表板”或询问“我的情况如何”时，运行全部三个命令（positions、wallet-balance、orders），并统一展示结果：

• 持仓：每个持仓的当前市场价格、买入价格（如有）和未实现盈亏
• USDC 余额：可用于新交易的资金
• 未结订单：待成交限价订单的价格和数量
• 投资组合总价值：持仓价值 + USDC 余额

订单簿与价格（需要 CLI，无需钱包）

# Order book for a token
python3 {baseDir}/scripts/polymarket.py book TOKEN_ID

# Price history (intervals: 1m, 1h, 6h, 1d, 1w, max)
python3 {baseDir}/scripts/polymarket.py price-history TOKEN_ID --interval 1d

# Price history with specific number of data points
python3 {baseDir}/scripts/polymarket.py price-history TOKEN_ID --interval 1h --fidelity 48

钱包（需要 CLI）

polymarket wallet create
polymarket wallet show
polymarket wallet balance
polymarket wallet balance --token TOKEN_ID

交易（需要 CLI 和钱包）

所有交易都需要使用 --confirm 才会执行。否则只会预览订单。这是一项安全功能，可确保你在操作执行前始终了解其影响。

成本与费用透明度

执行任何交易前，技能都会显示：

• 订单类型：限价单或市价单
• 方向：买入或卖出
• 价格：你的限价（市价单则显示“market”）
• 数量：股数
• 预估成本：限价单为价格 × 数量，市价单则为金额
• Polymarket 费用：Polymarket 不会在 CLOB（中央限价订单簿）上收取交易费用
• Gas 费用：链上操作（授权、拆分、赎回）需要在 Polygon 上使用 MATIC 支付 Gas 费。典型 Gas 费为 0.01–0.05 美元

# Preview a limit order (no --confirm = preview only)
python3 {baseDir}/scripts/polymarket.py trade buy --token TOKEN_ID --price 0.50 --size 10

# Execute a limit order
python3 {baseDir}/scripts/polymarket.py --confirm trade buy --token TOKEN_ID --price 0.50 --size 10

# Sell limit order
python3 {baseDir}/scripts/polymarket.py --confirm trade sell --token TOKEN_ID --price 0.70 --size 10

# Market order: buy $5 worth at current price
python3 {baseDir}/scripts/polymarket.py --confirm trade buy --token TOKEN_ID --market-order --amount 5

# Post-only limit order (rests on book only, never takes liquidity - Jan 2026+)
python3 {baseDir}/scripts/polymarket.py --confirm trade buy --token TOKEN_ID --price 0.45 --size 20 --post-only

订单与持仓（需要 CLI 和钱包）

# List open orders
python3 {baseDir}/scripts/polymarket.py orders

# Cancel a specific order
python3 {baseDir}/scripts/polymarket.py --confirm orders --cancel ORDER_ID

# Cancel all orders
python3 {baseDir}/scripts/polymarket.py --confirm orders --cancel all

# View positions
python3 {baseDir}/scripts/polymarket.py positions
python3 {baseDir}/scripts/polymarket.py positions --address 0xYOUR_WALLET

---

API 参考

Polymarket 提供 4 个不同的 API，以及一个 Gamma 便捷层。每个 API 用途各异。

1. Gamma API（gamma-api.polymarket.com）——公开，无需身份验证

用于浏览和搜索市场的高级便捷 API。所有只读命令均使用此 API。

• 基础 URL：https://gamma-api.polymarket.com
• GET /events - 列出事件（参数：order、ascending、closed、limit、tag_slug）
• GET /search - 搜索市场（参数：query、limit）
• GET /events/slug/{slug} - 根据 slug 获取事件
• GET /comments - 列出并筛选市场评论
• GET /profiles/{address} - 公开用户资料
• GET /series - 分组事件合集（例如“2028 年选举”系列）
• GET /sports - 体育赛事元数据，包括队伍、比赛和结算标准
• GraphQL：POST /query - 支持订阅的完整 GraphQL 端点

2. CLOB API（clob.polymarket.com）——交易

用于所有交易操作的中央限价订单簿 API，由 Polymarket CLI 封装。

• 基础 URL：https://clob.polymarket.com
• GET /prices-history - 历史价格（时间间隔：1m、1h、6h、1d、1w、max）
• GET /spread - 代币的买卖价差
• GET /fee-rate - 费用结构详情
• GET /rewards - 每日做市方／吃单方收益
• POST /order - 下单
• POST /orders - 批量下单（每次请求最多 15 个）
• DELETE /order/{id} - 取消订单
• 订单评分 - 下单前检查是否符合做市方返利条件
• 仅挂单（2026 年 1 月）- 只会留在订单簿上的订单，不会跨越价差
• Heartbeat API（2026 年 1 月）：
  • POST /heartbeat - 必须在 10 秒内发送，否则所有未结订单将自动取消
  • 由做市商用于维持订单状态
  • 如果心跳超时，该 API 密钥对应的所有挂单都会被取消

3. Data API（data-api.polymarket.com）——投资组合与分析

用于跟踪投资组合、交易历史和市场分析的专用 API。公开端点无需身份验证。

• 基础 URL：https://data-api.polymarket.com
• GET /positions?user={address} - 当前未平仓头寸
  • 排序方式：TOKENS、CURRENT、INITIAL、CASHPNL、PERCENTPNL
• GET /closed-positions?user={address} - 已平仓头寸历史记录
• GET /activity?user={address} - 活动动态
  • 类型：TRADE、SPLIT、MERGE、REDEEM、REWARD
• GET /value?user={address} - 以美元计价的投资组合估值
• GET /trades - 交易历史
  • 筛选条件：user、market、side
  • 每页最多 500 条结果
• GET /holders?market={conditionId} - 市场的主要代币持有者
• GET /oi - 各市场未平仓量
• GET /volume - 各市场交易量
• GET /leaderboard - 交易者排名（可配置时间段）

投资组合仪表板和分析请使用 Data API。与 CLOB API 相比，它提供更丰富的头寸数据，包括盈亏计算和活动历史。

4. RTDS WebSocket (wss://ws-live-data.polymarket.com) - 实时流式传输

通过 WebSocket 实时流式传输数据。订阅主题即可接收实时更新，无需轮询。

• URL：wss://ws-live-data.polymarket.com
• 协议：通过 WebSocket 传输 JSON 消息
• 主题：
  • comments - 实时评论活动
    • 事件：comment_created、comment_removed、reaction_created、reaction_removed
  • crypto_prices - 实时加密货币价格
    • 资产：BTC、ETH、SOL、XRP
    • 数据源：Binance + Chainlink 预言机
• 动态订阅管理 - 在单个连接中按需订阅和取消订阅主题
• 适用于构建实时仪表板、监控评论情绪，或跟踪为 5 分钟加密货币市场提供数据的加密货币价格

5. Bridge API (bridge.polymarket.com) - 跨链存款和提现

在多个链之间向 Polymarket 转入或转出资金。

• 基础 URL：https://bridge.polymarket.com
• POST /deposit - 生成存款地址
  • 支持的链：EVM（Ethereum、Polygon、Arbitrum 等）、Solana、Bitcoin
  • 返回所选链的唯一存款地址
• POST /withdraw（2026 年 1 月）- 将 USDC.e 跨链转至任意受支持的链
• GET /supported-assets - 列出所有受支持的资产和链
• GET /quote - 获取跨链桥接报价（费用、预计时间）

当用户需要在不离开终端的情况下向 Polymarket 转入或转出资金时，请使用 Bridge API。

---

新市场类型

• 5 分钟加密货币市场（2026 年 2 月）- 针对 BTC/ETH/SOL 价格波动的超短期市场。数据来自 RTDS 的 crypto_prices。
• 体育市场 - 通过 Gamma /sports 端点提供专用体育元数据，包括队伍信息、赛程和结算标准。

错误恢复

API 错误（Gamma API）

如果 Gamma API 返回错误或无法访问：

• HTTP 429（请求过多）：等待 5-10 秒后重试。Gamma API 的速率限制较宽松，但在流量较高的事件期间可能会进行限流。
• HTTP 500/502/503：API 暂时不可用。请告知用户，并建议一分钟后重试。
• 连接错误：检查互联网连接。API 端点为 https://gamma-api.polymarket.com。
• 结果为空：搜索条件可能过于具体。建议使用更宽泛的搜索词，或改为按类别浏览。

Data API 错误

• HTTP 400（错误请求）：检查 user 地址格式（必须是有效的 Ethereum 地址）或排序参数拼写。
• 持仓为空：该地址可能没有未平仓持仓，或地址格式有误。尝试使用或不使用校验和大小写格式。
• 分页：Trades 端点每页最多返回 500 条。要获取完整历史记录，请使用基于游标的分页。

CLOB API 错误

• Heartbeat 超时：如果使用 Heartbeat API 且连接中断超过 10 秒，所有订单都会自动取消。请重新连接并重新下单。
• 仅挂单拒绝：如果仅挂单订单会穿过价差，则会被拒绝，而不是成交。请调整价格，使订单留在订单簿上。
• 批量限制：每个批量请求最多 15 笔订单。较大的批次请拆分提交。

Bridge API 错误

• 不支持的链：请通过 /supported-assets 查看当前支持的链。
• 报价已过期：Bridge 报价有 TTL。执行前请获取最新报价。
• 最低金额：某些链设有最低存款或提现金额。

CLI 错误

如果 Polymarket CLI 返回错误：

• “CLI 未安装”：使用 brew install polymarket/tap/polymarket-cli 安装。
• “未找到配置”：用户需要先运行 polymarket wallet create。
• “余额不足”：显示当前余额和所需金额。
• “订单被拒绝”：价格可能超出有效范围（0-1），或市场可能已关闭／结算。
• “需要授权”：某些操作需要一次性链上授权。运行：polymarket approve set
• 超时：CLI 命令有 30 秒超时。如果命令超时，可能是网络问题，或 Polygon RPC 响应缓慢。

WebSocket 错误

• 连接断开：网络变化时，RTDS WebSocket 可能断开。重新连接并重新订阅主题。
• 主题无效：检查可用主题。目前仅支持 comments 和 crypto_prices。

未找到市场

如果未找到市场 slug 或事件：

1. 使用关键词搜索市场，而不是使用 slug
2. 检查市场是否已结算（使用 closed: true 参数）
3. 根据搜索词推荐相似市场
4. 提供 polymarket.com 链接，供用户手动浏览

身份验证问题

• 未配置钱包：指导用户完成 polymarket wallet create
• 网络错误：Polymarket 使用 Polygon。确保钱包连接到正确的网络。
• MATIC 不足：链上操作需要 MATIC 支付 Gas。引导用户跨链转入或购买 MATIC。

使用示例

示例 1：快速查看赔率

用户：“特朗普赢得 2028 年大选的赔率是多少？”

python3 {baseDir}/scripts/polymarket.py search "trump 2028 president"

输出：

Search: 'trump 2028 president'

  Trump wins 2028 Presidential Election
   Yes: 31.2% | No: 68.8%
   Volume: $4.2M
   Ends: Nov 05, 2028
   polymarket.com/event/trump-wins-2028-presidential-election

示例 2：热门市场看板

用户：“Polymarket 上现在有什么热门市场？”

运行热门市场查询，并按交易量分组展示热门市场：

Trending on Polymarket

  Fed Rate Decision - March 2026
   Markets: 3
   - Rate cut: 72.3%
   - No change: 25.1%
   - Rate hike: 2.6%
   Total Volume: $8.1M

  Bitcoin above $150K by July 2026
   Yes: 28.4% | No: 71.6%
   Volume: $3.9M

  UFC 310 Main Event Winner
   Fighter A: 62.1% | Fighter B: 37.9%
   Volume: $1.2M

示例 3：市场研究

用户：“帮我研究一下美联储利率决策市场”

该技能会获取市场数据，然后提供分析：

Market Research: Fed Rate Decision - March 2026

Current Odds:
  Rate cut:    72.3% (down from 81% last week)
  No change:   25.1% (up from 17% last week)
  Rate hike:    2.6% (stable)

Volume & Liquidity:
  Total Volume: $8.1M
  24h Volume:   $420K
  Order book depth: Deep (>$50K on both sides)

Trend: Odds of a cut have fallen ~9 points in the past week,
likely driven by stronger-than-expected jobs report on Friday.

Key Dates:
  - FOMC Meeting: March 18-19, 2026
  - Market resolves: March 19, 2026

Context: The market is pricing in a ~72% chance of a 25bp cut.
This aligns roughly with CME FedWatch tool (68%) and economist
consensus (65-75% for a cut). The slight premium on Polymarket
may reflect retail sentiment skewing more dovish.

示例 4：通过 Data API 查看投资组合

用户：“我的 Polymarket 投资组合表现如何？”

使用 Data API 获取丰富的投资组合数据：

# Portfolio value
curl -s "https://data-api.polymarket.com/value?user=0xYOUR_WALLET"

# Open positions sorted by P&L
curl -s "https://data-api.polymarket.com/positions?user=0xYOUR_WALLET&sortBy=CASHPNL"

# Recent activity
curl -s "https://data-api.polymarket.com/activity?user=0xYOUR_WALLET"

输出：

Portfolio Dashboard

Portfolio Value: $289.80

Positions (sorted by P&L):
  Fed Rate Cut (Yes)     100 shares @ $0.65    Current: $0.72    P&L: +$7.00
  BTC > $150K July (No)   50 shares @ $0.60    Current: $0.71    P&L: +$5.50

Recent Activity:
  TRADE  Bought 25 Fed Rate Cut (Yes) @ $0.68    2 hours ago
  REDEEM Claimed $12.40 from resolved market     1 day ago

USDC Balance: $142.30
Open Orders: 1 pending

示例 5：并排比较

用户：“比较一下共和党初选候选人”

Market Comparison: 2028 Republican Primary

| Candidate     | Win Primary | Win General | Volume (Primary) |
|---------------|-------------|-------------|------------------|
| Trump         | 42.1%       | 31.2%       | $2.8M            |
| DeSantis      | 22.5%       | 18.1%       | $1.4M            |
| Haley         | 11.3%       |  8.9%       | $680K            |
| Ramaswamy     |  6.8%       |  4.2%       | $320K            |

Note: Primary odds sum to ~95% (gap = long-tail candidates).
Win-general odds are conditional on winning the primary.

示例 6：预览交易成本

用户：“以 68 美分买入 50 股美联储降息的 Yes 份额”

python3 {baseDir}/scripts/polymarket.py trade buy --token TOKEN_ID --price 0.68 --size 50

输出：

Buy Limit Order (PREVIEW)
   Token: Fed Rate Decision - Rate Cut (Yes)
   Side:  BUY
   Price: $0.68
   Size:  50 shares
   Estimated Cost: $34.00
   Trading Fee: $0.00 (Polymarket CLOB has no trading fees)
   Gas Fee: ~$0.01-0.05 MATIC (only on first approval)

   Add --confirm to execute this trade.
   This involves REAL MONEY on Polygon.

示例 7：排行榜和大户持仓

用户：“Polymarket 上排名靠前的交易者有哪些？”

# Trader leaderboard
curl -s "https://data-api.polymarket.com/leaderboard"

# Top holders for a specific market
curl -s "https://data-api.polymarket.com/holders?market=CONDITION_ID"

示例 8：跨链转入资金

用户：“我想从 Ethereum 向 Polymarket 充值”

# Check supported assets
curl -s "https://bridge.polymarket.com/supported-assets"

# Get a quote
curl -s -X POST "https://bridge.polymarket.com/deposit" \
  -H "Content-Type: application/json" \
  -d '{"chain": "ethereum", "asset": "USDC"}'

示例 9：历史价格分析

用户：“显示这个市场过去一周的价格历史”

# Via CLOB API
curl -s "https://clob.polymarket.com/prices-history?tokenID=TOKEN_ID&interval=1d&fidelity=7"

# Or via CLI
polymarket price-history TOKEN_ID --interval 1d --output json

示例 10：价差和手续费查询

用户：“这个市场的价差是多少？”

# Bid-ask spread
curl -s "https://clob.polymarket.com/spread?tokenID=TOKEN_ID"

# Fee rate
curl -s "https://clob.polymarket.com/fee-rate"

安全说明

• 真实资金。 交易会在 Polygon 上使用真实 USDC 执行。务必仔细核对所有信息。
• 所有交易都需要 --confirm。 不带此参数时，只会显示预览。这一点不可妥协。
• CLI 处于实验阶段。 Polymarket 团队警告：“使用风险自负，请勿投入大量资金。”
• 私钥安全。 你的密钥存储在 ~/.config/polymarket/config.json 中。切勿分享或提交该文件。
• Gas 费用。 链上操作（授权、拆分、赎回）需要 MATIC 来支付 Polygon 上的 Gas。
• Heartbeat API。 如果你使用 heartbeat 系统做市，漏掉一次 heartbeat（>10s）会取消所有未成交订单。
• 市场结算。 市场会根据各市场指定的结算来源进行结算。交易前请查看结算标准。
• 滑点。 市价单会以当前最优价格执行；在快速波动的市场中，该价格可能与显示价格不同。
• 流动性。 低交易量市场的买卖价差可能较大。提交大额订单前，请查看订单簿。
• 跨链转入资金。 跨链桥接存在智能合约风险。确认前请核实地址和金额。

相关技能

想获取更多市场情报？试试这些 OpenClaw 技能：

• /search-x - 搜索 X/Twitter，了解任意话题的实时情绪。结合 Polymarket 赔率，判断市场走势是领先还是落后于公众舆论。
• /last30days - 利用网络和社交媒体来源，对任意话题进行深入研究。交易前可用它建立背景信息。
• /parallel - 同时运行多项研究任务，一次性结合 Polymarket 赔率、新闻、社交情绪和专家分析。