1. 项目概述为AI Agent构建的Polymarket预测市场交易技能如果你正在开发一个能自主分析、决策甚至交易的AI Agent并且对加密货币、政治或体育等领域的预测市场感兴趣那么你很可能需要一套与Polymarket这类平台交互的工具。传统的API调用对AI来说过于底层和繁琐而dpro-polymarket这个项目正是为了解决这个问题而生。它是一个专为AI Agent环境如Claude Code, OpenClaw, Codex, OpenCode设计的“技能”模块将Polymarket复杂的市场搜索、行情获取、账户管理和交易下单等功能封装成一套Agent能直接理解和执行的标准化指令。简单来说它就像给你的AI Agent安装了一个“Polymarket交易终端”。Agent不再需要关心如何构造HTTP请求、处理加密签名或解析复杂的JSON响应只需要像人类用户一样输入“查一下关于比特币的预测市场”或“以0.65的价格买入10份‘特朗普会赢’的YES份额”这样的自然语言或标准化命令这个技能模块就会在背后完成所有脏活累活并返回结构清晰的结果。这极大地降低了在AI工作流中集成链上预测市场能力的门槛让开发者可以更专注于策略逻辑本身而不是基础设施的搭建。2. 核心设计思路与架构解析2.1 为什么需要为AI Agent设计专用技能在深入代码之前我们先要理解这个项目的设计哲学。Polymarket本身提供了完善的REST API和WebSocket接口那为什么还要额外封装一层核心原因在于“认知对齐”。AI Agent特别是基于大语言模型的Agent其交互模式与传统的程序调用有本质不同。首先交互的自然性。Agent擅长处理自然语言或类自然语言的指令。一个原始的API调用GET /markets?searchbitcoin对Agent是不友好的。而dpro-pm search bitcoin这样的命令或者更自然的“帮我找找和比特币相关的预测市场”则与Agent的“思考”方式匹配。dpro-polymarket的输入解析器parser.mjs核心工作就是做这种对齐它将模糊的用户意图精准地路由到具体的API功能上。其次状态与上下文的抽象。一次完整的交易涉及多个步骤登录认证、查询余额、查看订单簿、下单、确认。如果让Agent直接管理这些状态会极其复杂且容易出错。本技能模块通过store.mjs和config.mjs将账户状态私钥、API凭证、会话缓存等复杂性完全隐藏起来。Agent只需关注业务目标无需管理底层状态机。最后安全与边界的明确。让AI直接操作私钥和发起链上交易是危险的。本项目通过预定义的安全策略在SKILL.md中为每一条交易指令设置了确认环节并强制要求密码验证。这为AI的行为划定了安全边界防止其执行未经授权的危险操作。2.2 模块化架构从指令到链上交易的全链路拆解项目的目录结构清晰地反映了其“输入-处理-输出”的管道式设计。我们可以将其拆解为五个核心层次接口层Interface由scripts/entry.mjs和scripts/parser.mjs构成。这是对外的唯一入口负责接收各种格式的指令规范命令、斜杠命令、自然语言并将其解析成统一的抽象语法树AST格式。这是实现“灵活调用”的关键。路由层Routingscripts/router.mjs。它根据AST中的命令类型如searchbuy将请求分发到对应的命令处理器。这类似于一个微型的命令行路由器确保了系统的可扩展性——新增功能只需添加新的命令处理器即可。业务逻辑层Business Logicscripts/commands/目录下的各个模块。这是核心功能所在market.mjs处理所有只读的数据查询如搜索、报价、订单簿查询。它主要与无需认证的Gamma API和Data API交互。account.mjs管理账户生命周期包括添加账户、查询余额、持仓和订单。它涉及认证和非敏感数据的获取。trade.mjs处理所有写操作如下单、撤单。这是最复杂的部分需要与需要L2认证的CLOB API交互。客户端层Clientscripts/clients/。这一层是对外部Polymarket API的封装。它将HTTP请求、错误处理、数据格式化等细节隔离为上层的业务逻辑提供干净的JavaScript对象接口。特别是clob-client.mjs它封装了官方的polymarket/clob-client库并集成了自动的凭证派生和签名逻辑。支撑层Support包括存储store.mjs、加密crypto.mjs、配置config.mjs和格式化format.mjs。尤其是加密模块它使用AES-256-GCM算法对私钥进行加密存储这是整个系统安全性的基石确保敏感信息不会以明文形式泄露。这种分层架构的优点是职责清晰、耦合度低。例如如果Polymarket的API地址发生变化你只需要修改客户端层的配置如果你想增加一个数据可视化功能只需在业务逻辑层添加一个新命令并在格式化层提供新的输出模板。3. 核心功能实操与关键技术细节3.1 账户体系与自动化认证流程这是使用本技能进行交易的前提也是最容易出错的地方。Polymarket采用了两层L1/L2认证体系而dpro-polymarket巧妙地将其自动化了。第一步添加账户L1凭证准备当你执行dpro-pm account add 0xYourPrivateKey myaccount --password password时背后发生了以下事情系统使用你提供的密码通过PBKDF2等密钥派生函数生成一个加密密钥。使用这个加密密钥和AES-256-GCM算法对你的原始私钥进行加密。加密后的密文、初始化向量IV和认证标签会被安全地存储到本地配置文件中通常是~/.config/dpro-polymarket/config.json。你的明文私钥在任何时候都不会被写入磁盘。系统会尝试用这个私钥生成一个EIP-712格式的签名向Polymarket服务器“声明”这个账户。这一步是为了后续派生L2 API密钥做准备。注意私钥来源。务必从Polymarket官网polymarket.com/settings的“导出私钥”功能获取而不是直接从MetaMask导出。因为Polymarket的智能合约钱包通常是Gnosis Safe的私钥与EOA外部拥有账户如MetaMask的私钥在签名方式上不同。这也是--sig-type参数存在的意义默认的2GNOSIS_SAFE对应Polymarket账户0EOA对应原生MetaMask钱包。第二步自动化L2凭证派生这是本技能最精妙的设计之一。你不需要手动生成或配置API Key和Secret。当你第一次执行需要L2认证的操作如查询持仓positions或下单buy时技能模块会检查本地缓存中是否有有效的L2凭证。如果没有它会使用存储的L1私钥解密后自动向Polymarket的认证端点发起一个签名请求。服务器验证L1签名后会返回一对API Key和Secret。这套L2凭证会被缓存起来同样受密码保护用于后续所有需要HMAC-SHA256签名的请求主要是交易相关操作。从此以后进行交易时技能模块会自动使用缓存的L2凭证进行签名你完全感知不到这个过程。实操心得密码管理密码可以通过三种方式提供命令行参数--password、运行时上下文runtimeContext.password、环境变量DPRO_PM_PASSWORD。在AI Agent环境中最安全且自动化的方式是使用环境变量。确保在你的Agent运行环境中提前设置好DPRO_PM_PASSWORD这样技能模块在需要解密私钥或凭证时就能自动获取无需在指令流中明文传递密码。3.2 市场数据查询从模糊意图到精确结果市场查询是策略的起点。技能提供了多种维度的查询方式其底层都依赖于Gamma API。search命令这是最常用的功能。当你输入dpro-pm search bitcoin 2025模块会向https://gamma-api.polymarket.com/markets发起请求并过滤标题和描述中包含“bitcoin”和“2025”的市场。返回的结果通常包括市场ID、标题、当前YES/NO价格、交易量、流动性等关键信息。对于AI Agent来说这些结构化的数据比原始的HTML或复杂API响应更容易理解和提取。quote命令当你已经知道具体的市场标识通常是URL中的slug如will-iran-strike-israel-on-march-6时使用此命令获取该市场的深度报价。它会返回两个结果代币YES和NO的当前最佳买卖价、数量以及完整的代币ID。代币ID是后续查询订单簿和交易的关键。book命令输入一个具体的代币ID可以从quote命令获得获取该代币的完整订单簿深度。这对于分析市场微观结构和制定限价单策略至关重要。数据来自CLOB API。trending和event命令用于发现市场。trending按交易量排序返回热门市场event则聚合同一主题下的所有子市场例如“美国2024总统大选”事件下会有多个关于候选人和结果的预测市场。注意事项API速率限制与缓存虽然公开的Gamma和Data API没有严格的速率限制但在高频查询或Agent自动化扫描时仍需注意礼貌请求。技能模块本身没有内置缓存如果你的Agent需要频繁查询同一市场数据建议你在Agent逻辑层实现一个简单的内存缓存例如将quote结果缓存5-10秒以避免不必要的网络请求和延迟。3.3 交易执行订单类型与风险控制交易功能集中在trade.mjs模块它是与资金直接交互的部分因此设计上最为谨慎。订单类型解析Polymarket CLOB支持多种订单类型技能模块也相应地提供了支持限价单Limit Order指定价格和数量。例如buy will-trump-win yes 50 0.65表示以不高于0.65 USDC的价格买入50份YES份额。这是最常用的订单类型。市价单Market Order不指定价格按当前市场最优价格立即成交。例如sell will-trump-win yes 20。使用市价单需格外小心在流动性不足的市场中可能会以非常不利的价格成交。订单时间条件TIFGTCGood Till Cancel默认类型订单一直有效直到被成交或取消。GTDGood Till Date指定一个过期时间。FOKFill or Kill订单必须立即全部成交否则全部取消。FAKFill and Kill订单立即部分或全部成交未成交部分取消。在技能命令中这些通常作为可选参数实现。例如一个完整的限价单可能隐含了GTC条件。安全策略与确认机制这是SKILL.md文件中定义的核心安全规则。任何buy或sell命令在执行前必须经过一个确认环节。技能模块会打印出订单的详细信息摘要例如即将提交订单 操作买入 市场特朗普会赢得2024大选吗 份额YES 数量10 价格0.55 USDC 预估成本5.50 USDC 订单类型限价单(GTC) 请确认 (y/N)在交互式命令行中这需要手动输入y确认。在AI Agent环境中这个确认行为通常由Agent的运行框架或一个特定的“安全审批”子技能来处理。框架可能会根据预设的风险规则如单笔最大金额、禁止交易的市场列表自动批准或拒绝也可能需要人工介入。绝对不要绕过这个确认机制它是防止AI误操作的最后一道防线。实操心得代币数量与USDC金额预测市场的份额是以“代币”为单位每个代币代表一份合约。YES和NO代币的价格总和恒定为1 USDC。当你买入10个YES代币价格为0.65 USDC时你实际支付的金额是10 * 0.65 6.5 USDC。如果最终结果為“是”每个YES代币可以赎回1 USDC你获利10 * (1 - 0.65) 3.5 USDC。技能模块在订单摘要中会计算这个预估成本务必仔细核对。4. 在AI Agent环境中集成与调用4.1 与Claude Code等环境的集成项目说明中提到了Claude Code、OpenClaw等环境。以Claude Code为例集成步骤非常典型安装技能在Claude Code的工作区中技能通常安装在特定的.claude/skills/目录下。按照README的步骤克隆仓库并安装依赖本质上就是将这个Node.js模块放入技能目录。声明技能在Claude Code的配置文件如claude.code-workspace或特定的agent配置文件中通过Skills: .claude/skills/dpro-pm/SKILL.md这行声明来启用它。SKILL.md文件描述了技能的能力、命令格式和安全策略是Agent理解如何调用该技能的“说明书”。调用技能集成后你就可以在Claude Code的聊天界面或代码编辑器中直接使用dpro-pm开头的命令。Claude Code的运行时环境会捕获这些命令将其路由到本技能模块执行并将结果返回给用户界面。4.2 程序化调用runPolymarketSkill函数对于更复杂的自动化工作流或者你想在自己的Node.js脚本中直接驱动这个技能可以使用scripts/entry.mjs导出的runPolymarketSkill函数。这是最灵活的集成方式。import { runPolymarketSkill } from ./scripts/entry.mjs; // 示例1简单查询 async function searchMarkets() { const result await runPolymarketSkill(dpro-pm search ethereum ETF approval, {}); // result 是一个对象包含原始数据、格式化文本和可能的错误信息 console.log(result.output); // 格式化后的文本输出 console.log(result.data); // 结构化的JSON数据便于程序处理 } // 示例2执行交易需提供密码 async function placeTrade() { const context { password: process.env.DPRO_PM_PASSWORD }; // 从环境变量获取密码 const tradeResult await runPolymarketSkill( dpro-pm buy will-eth-etf-approve-june-2024 yes 5 0.7, context ); if (tradeResult.error) { console.error(交易失败:, tradeResult.error); } else { console.log(订单已提交:, tradeResult.data.orderId); } }关键点runPolymarketSkill的第二个参数是runtimeContext你可以在这里传入密码、指定配置文件路径、或者覆盖其他运行时配置。这使得它非常适合嵌入到更大的自动化系统中。4.3 构建一个简单的市场监控Agent结合上述功能我们可以勾勒一个简单的AI Agent应用场景一个自动监控特定主题市场并提示交易机会的Agent。数据获取层使用runPolymarketSkill定期执行dpro-pm search [关键词]和dpro-pm trending获取市场列表和价格信息。分析决策层这是你自定义的AI逻辑。你可以用大语言模型分析市场标题和描述判断其热度也可以用简单的量化规则分析价格数据例如“当YES价格低于0.3且24小时交易量超过10万USDC时认为市场被低估”。执行层当决策层产生交易信号时调用runPolymarketSkill执行buy或sell命令。务必在此处集成安全确认逻辑例如只有预期收益超过阈值、且单笔金额小于总资金2%的信号才会被自动执行否则需要人工审核。日志与风控层记录所有查询和交易操作定期执行dpro-pm portfolio检查总资产和浮动盈亏设置最大回撤警报。通过dpro-polymarket技能这个Agent的复杂度和开发时间主要集中在第2步的策略逻辑上而繁琐的API交互、账户安全和订单管理都被技能模块妥善处理了。5. 常见问题、故障排查与进阶技巧5.1 安装与初始化问题问题npm install失败提示找不到polymarket/clob-client。排查polymarket/clob-client是Polymarket官方维护的私有npm包。安装失败通常是因为没有访问权限。解决你需要拥有一个Polymarket开发者账户并在本地npm配置中设置访问令牌。通常你需要联系Polymarket团队获取包的访问权限。这是使用交易功能的必要前提。如果暂时无法获取技能的数据查询功能search, quote, book等仍然可用但交易功能会失效。问题执行任何账户相关命令都报“无效的私钥”或“签名错误”。排查首先确认私钥格式是否正确以0x开头的64位十六进制字符串。最常见的原因是签名类型不匹配。解决如果你是从Polymarket网站导出的私钥添加账户时不要使用--sig-type参数或明确指定--sig-type 2GNOSIS_SAFE。如果你使用的是MetaMask等钱包的原始私钥则必须添加--sig-type 0EOA参数。5.2 交易与账户问题问题下单时提示“Insufficient balance”余额不足但我的USDC余额显示充足。排查预测市场交易需要支付两种费用1) 购买份额所需的USDC2) Polygon链上的Gas费以MATIC计价。余额不足通常指USDC充足但MATIC不足。解决确保你的Polygon钱包地址上有少量的MATIC例如0.1-0.5 MATIC用于支付Gas费。你可以从任何加密货币交易所购买MATIC并提现到你的Polymarket账户地址。问题市价单成交价格远差于预期。排查订单簿深度不足。在流动性差的市场第一档的订单数量可能很小你的市价单会“吃”掉多档深度的订单导致平均成交价恶化。解决下单前务必使用book命令查看订单簿深度。对于大额订单优先使用限价单并考虑将大单拆分成多个小单在不同价格档位分批下单以减少对市场的冲击。问题positions命令看不到我刚成交的仓位。排查数据同步延迟。链上交易确认和索引器更新数据需要时间通常几秒到一分钟。解决稍等片刻再查询。这是区块链应用的正常特性。对于需要实时监控的策略可以考虑订阅Polymarket的WebSocket推送但本技能模块暂未集成此功能。5.3 性能与进阶使用技巧技巧批量操作与脚本化。你可以编写一个Shell脚本或Node.js脚本循环调用runPolymarketSkill来执行一系列操作。例如一个每日清算脚本先查询所有持仓然后对价格已接近1或0的仓位进行平仓。# 伪代码示例 POSITIONS$(dpro-pm positions --format json) echo $POSITIONS | jq -c .[] | while read position; do market$(echo $position | jq -r .market) price$(echo $position | jq -r .currentPrice) if (( $(echo $price 0.95 | bc -l) )); then dpro-pm sell $market YES --quantity ALL fi done技巧利用结构化输出进行策略回测。runPolymarketSkill返回的result.data包含了丰富的结构化信息。你可以定期如每小时运行dpro-pm quote获取你关注市场的价格并将这些时间序列数据存储到数据库如SQLite或InfluxDB中。积累足够数据后就可以用来回测你的交易策略逻辑。注意事项网络与环境依赖。整个技能依赖于对Polygon RPC节点和Polymarket API端点的网络访问。在服务器或云函数中部署Agent时确保网络环境稳定并考虑设置请求超时和重试机制以应对偶尔的网络抖动或API暂时不可用的情况。