Polymarket 集成（v1 读取 + 交易）

本文档描述了 #1398 的 Polymarket 集成。

范围

该 polymarket 工具现在支持通过以下方式进行市场浏览和交易工作流：

• Gamma API（https://gamma-api.polymarket.com)

• CLOB API（https://clob.polymarket.com)

支持的读取操作：

• list_markets

• get_market

• list_events

• get_orderbook

• get_price

• get_positions

• get_balance

• get_open_orders

• get_usdc_allowance

支持的写入操作：

• place_order

• cancel_order

架构

实现位于 src/openhuman/tools/impl/network/polymarket.rs 以及辅助模块：

• clob_auth.rs：L1 证书派生 + L2 HMAC 头部

• polymarket_orders.rs：EIP-712 订单类型数据签名

关键运行时行为：

• Layer-2 API 凭证会在首次经过身份验证的调用时派生，并被缓存。

• 派生的凭证会持久化到 integrations.polymarket.derived_clob_credentials （在密钥存储迁移落地之前，使用普通配置回退）。

• 下单会先获取 GET /nonce?user=<eoa> ，然后再签名，以避免重放/nonce 不匹配。

• USDC.e 授权通过 Polygon 的 eth_call 读取，目标合约为 ERC-20 allowance(owner, spender).

身份验证与签名流程

L1 握手（一次性引导）

• 签名 CLOB ClobAuth 带有 Polygon 链 ID 的 EIP-712 负载 137.

• 操作员流程： POST /auth/api-key；如有需要，回退到 GET /auth/derive-api-key.

• 持久化返回的 { apiKey, secret, passphrase } 供 L2 使用。

L2 已认证请求

每个已认证的 CLOB 请求都会签名：

• timestamp + method + request_path（POST 时还包括 body）

头部：

• POLY_ADDRESS

• POLY_SIGNATURE

• POLY_TIMESTAMP

• POLY_NONCE: 0

• POLY_API_KEY

• POLY_PASSPHRASE

订单签名

place_order 使用以下域签名 EIP-712 订单：

• 名称： Polymarket CTF Exchange

• 版本： 1

• 链 ID： 137

• 验证合约： integrations.polymarket.clob_exchange_contract

权限

写入操作目前受一个显式的临时批准标志保护。

• place_order 以及 cancel_order 需要 approved=true.

• 如果省略或 false，工具将返回：

  • Polymarket 写入需要明确的用户批准。请在与用户确认后，使用 arguments.approved = true 重新调用。

在 #1339 中的共享批准门集成之前，这只是临时措施。

配置

配置路径： integrations.polymarket.

字段：

• 已启用 （默认 false)

• gamma_base_url （默认 https://gamma-api.polymarket.com)

• clob_base_url （默认 https://clob.polymarket.com)

• timeout_secs （默认 15)

• eoa_address （可选，默认用户地址）

• polygon_rpc_url （默认 https://polygon-rpc.com)

• usdc_contract （默认 0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174)

• clob_exchange_contract （默认 0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E)

• derived_clob_credentials （可选的缓存 L2 凭证）

USDC 授权合约

get_usdc_allowance 仅报告授权状态；不会修改链上状态。

• 代币：Polygon 上的 USDC.e（0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174)

• 花费者：Polymarket 交易所（0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E)

如果授权不足，必须单独执行授权（钱包工具 / 显式用户批准流程）。

错误与重试行为

• 4xx 错误被视为客户端错误，不会重试。

• 429 和 5xx 错误被视为临时性错误，最多重试 3 次。

• 重试之间的退避固定为 500 毫秒。

• 超时会表现为显式的截止时间错误。

测试策略

单元测试位于 src/openhuman/tools/impl/network/polymarket_tests.rs 以及辅助模块测试中。

• 现有的读取路径和重试行为测试仍然覆盖。

• 新增覆盖了已认证读取操作、写入批准门控以及 Polygon 授权读取。

• clob_auth.rs 测试覆盖 HMAC/头部 fixture 行为。

• polymarket_orders.rs 测试覆盖域和确定性签名 fixture 行为。