OpenHuman 的 Polymarket 集成指南Gamma/CLOB 双 API 的市场查询与 EIP-712 交易签名实现【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman导读本文以 OpenHuman 仓库中的 Polymarket 集成文档对应 issue #1398为骨架完整讲解其如何让 AI 代理同时具备 Polymarket 预测市场的只读查询市场、事件、订单簿、价格、持仓、余额与链上交易下单、撤单能力。你将掌握该集成的架构模块划分、L1/L2 两级认证签名流程、EIP-712 订单签署细节、integrations.polymarket配置项的每个字段含义以及可复用的测试策略与重试语义并可通过仓库内 tests/fixtures/polymarket/ 的夹具数据直接验证 API 响应结构。集成范围读取与交易双模式Polymarket 集成同时面向两类使用场景分别对接两条官方 API 域Gamma APIhttps://gamma-api.polymarket.com市场、事件等元数据查询CLOB APIhttps://clob.polymarket.com订单簿、价格、持仓、余额以及下单/撤单等交易类操作。支持的读取动作9 个动作说明list_markets拉取市场列表按 slug/ID 筛选get_market获取单个市场详情list_events拉取事件列表get_orderbook读取指定 token 的买卖盘深度get_price读取指定 token 的最新买卖价格get_positions查询当前持仓get_balance查询账户余额get_open_orders查询未成交订单get_usdc_allowance查询 USDC.e 对交易合约的授权额度支持的写入动作2 个place_order放置限价买单/卖单cancel_order撤销未成交订单。从 tests/fixtures/polymarket/ 的夹具可以反推这些动作对应的响应结构。例如list_markets返回的市场对象包含id、slug、question、active、closed字段见 markets_list.json[ { id: 12345, slug: will-eth-hit-10k, question: Will ETH hit $10k by Dec 31, 2026?, active: true, closed: false } ]get_orderbook返回带token_id、bids、asks的深度结构每个档位由price与size十进制字符串非整数字节构成见 orderbook.json{ token_id: 1001, bids: [{ price: 0.46, size: 1200 }], asks: [{ price: 0.48, size: 900 }] }get_price则返回token_id、sidebuy/sell与price见 price.json{ token_id: 1001, side: buy, price: 0.47 }架构与模块划分按集成文档描述实现主体位于src/openhuman/tools/impl/network/polymarket.rs并拆分为两个职责单一的辅助模块clob_auth.rs负责L1 凭据派生用 Polygon 私钥换取 CLOB API Key与L2 HMAC 请求头的构造polymarket_orders.rs负责EIP-712 订单类型化数据签名。这种拆分让认证凭据与业务请求签名两条链路的关注点完全隔离也便于各自独立做单元测试详见后文测试策略。关键运行时行为凭据懒加载与缓存L2 API 凭据apiKey、secret、passphrase在第一次需要认证的调用时才派生并缓存在内存中避免每次请求都重复握手凭据持久化派生出的凭据会持久化到integrations.polymarket.derived_clob_credentials。按文档说明在 secret-store 迁移落地之前该字段暂时以明文配置回退方式存储使用时应意识到这一安全边界下单前获取 nonceplace_order在签名前先请求GET /nonce?usereoa以规避重放攻击与 nonce 不匹配问题链上额度读取USDC.e 授权额度通过 Polygoneth_call调用 ERC-20 标准接口allowance(owner, spender)获取不改变链上状态。认证与签名流程Polymarket CLOB 采用两级凭据体系集成文档将其描述为 L1 一次性引导 L2 常态化认证。L1 握手一次性引导使用 Polygon 链 ID137对 CLOB 的ClobAuthEIP-712 载荷进行签名这相当于用主钱包私钥证明身份调用POST /auth/api-key换取 API 凭据若该端点不可用则回退到GET /auth/derive-api-key将返回的{ apiKey, secret, passphrase }持久化供后续 L2 请求使用。L2 认证请求每个需要认证的 CLOB 请求都会对以下内容做签名timestamp method request_pathPOST 请求额外拼接 body签名的结果通过以下请求头携带即文档所述 HMAC 头行为POLY_ADDRESS签名地址POLY_SIGNATURE请求签名POLY_TIMESTAMP时间戳POLY_NONCE: 0固定为 0一次性 nonce 机制下无需自增计数POLY_API_KEYL1 阶段派生的 API KeyPOLY_PASSPHRASEL1 阶段派生的口令这种设计将身份凭据API Key/Passphrase与请求级防篡改签名Signature分离即使凭据被泄露攻击者也无法伪造任意时间戳下的合法请求。订单签名EIP-712place_order在提交前会按 EIP-712 标准对订单进行类型化数据签名签名域Domain参数如下namePolymarket CTF Exchangeversion1chain id137PolygonverifyingContractintegrations.polymarket.clob_exchange_contract默认0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982Everifying contract 不是硬编码而是配置项意味着在测试网或其他部署环境可以替换为对应合约地址保证签名的可验证性。权限与审批保护写入动作place_order、cancel_order当前由显式的兜底审批标志保护调用时必须携带approvedtrue若省略或为false工具将直接返回Polymarket write requires explicit user approval. Re-invoke with arguments.approved true after confirming with the user.这是一项临时机制在共享审批门shared approval gateissue #1339集成到运行时之前用它确保 AI 代理不会在未经用户确认的情况下擅自发起链上交易。它体现了默认拒绝、显式放行的权限设计原则代理在对话中先向用户说明意图用户确认后再以approvedtrue重新调用。配置详解配置路径为integrations.polymarket各字段如下字段默认值说明enabledfalse是否启用该集成默认关闭需显式开启gamma_base_urlhttps://gamma-api.polymarket.comGamma 元数据 API 基地址clob_base_urlhttps://clob.polymarket.comCLOB 交易 API 基地址timeout_secs15请求超时秒eoa_address无可选默认用户地址用于 nonce 查询与 allowance 读取polygon_rpc_urlhttps://polygon-rpc.comPolygon RPC用于eth_call读取链上额度usdc_contract0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174USDC.ePolygon 上的桥接 USDC合约地址clob_exchange_contract0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982EPolymarket CTF Exchange 合约地址订单签名 verifyingContractderived_clob_credentials无可选缓存派生的 L2 凭据apiKey/secret/passphrase明文回退存储配置实践要点enabled默认false启用前请确认eoa_address已配置否则 nonce 与 allowance 查询无明确归属地址timeout_secs直接影响错误处理章节中的显式超时错误行为过小易在慢网络下频繁触发 deadline若使用自定义 RPC如自建节点修改polygon_rpc_url即可不影响其余配置derived_clob_credentials由系统在首次 L1 握手后写入不建议手工填写除非需要跨会话恢复凭据。USDC.e 授权Allowance检查get_usdc_allowance只报告授权状态不修改链上状态TokenPolygon 上的 USDC.e0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174SpenderPolymarket 交易合约0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E。这是读取动作与写入动作之间的关键衔接点下单前应先用get_usdc_allowance确认授权额度充足。若额度不足批准approve必须单独执行——通过钱包工具或显式用户批准流程完成而不是由本集成隐式代批。这种查询只读、批准另行授权的职责划分避免工具在无感知情况下代用户签署approve交易。错误与重试策略集成对 HTTP 错误的分类与重试语义定义明确4xx视为客户端错误参数错误、未授权、token 不存在等不重试直接返回429 / 5xx视为瞬时性错误限流、上游服务不可用最多重试 3 次退避策略固定 500ms 间隔不采用指数退避超时以显式的 deadline 错误呈现给调用方而非静默吞掉。仓库中的错误夹具印证了该分类error_client.json{error: unknown token_id}4xx 类与 error_server.json{error: upstream unavailable}5xx 类分别对应不重试与重试至多 3 次两类路径。测试策略与夹具数据按集成文档说明单元测试位于src/openhuman/tools/impl/network/polymarket_tests.rs及两个辅助模块的测试中覆盖维度包括既有只读路径与重试行为的回归测试新增的认证只读动作、写入审批门控、Polygon 授权额度读取三类测试clob_auth.rs测试HMAC/请求头构造的夹具行为验证即上文 L2 头字段polymarket_orders.rs测试EIP-712 域参数与确定性签名夹具行为验证相同输入必须产出相同签名。测试夹具目录 tests/fixtures/polymarket/ 共 8 个 JSON 文件覆盖市场查询markets_list.json列表、market_by_id.json按 ID、market_by_slug.json按 slug事件查询events_list.json含id、title、slug行情数据orderbook.json、price.json错误分支error_client.json、error_server.json。这套夹具同时服务两个目的一是让测试不依赖真实网络保证 CI 的确定性与速度二是作为 API 契约文档让后续接入其他语言或客户端的开发者能够直接对照响应结构。小结OpenHuman 的 Polymarket 集成把市场研究与链上执行合并到了同一个代理工具面通过 Gamma/CLOB 双 API 覆盖从list_markets到place_order的完整链路用 L1 握手 L2 签名头 EIP-712 订单签名构建三层安全模型用approvedtrue审批门控守住写入边界用查询只读 单独批准的职责划分保护用户资产并用明确的 4xx/5xx 重试语义保证调用方行为可预期。若你需要在自有代理中接入预测市场交易本文的配置表、签名流程与夹具结构可以直接作为落地参考。【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考