1. 项目概述为AI智能体打造的零风险预测市场交易沙盒如果你正在开发一个AI智能体并且希望它能学习、测试甚至精通在Polymarket这类预测市场上的交易策略那么你很可能面临一个两难困境要么用真金白银去冒险要么只能对着静态数据纸上谈兵。polymarket-paper-trader这个开源项目就是为了解决这个痛点而生的。它不是一个简单的价格模拟器而是一个基于真实订单簿的、高保真度的交易沙盒专门为AI智能体、量化策略开发者和交易爱好者设计。简单来说它给你的AI智能体提供了一个拥有初始虚拟资金比如1万美元的“模拟账户”然后允许它接入Polymarket的实时订单簿进行买卖。所有的交易执行逻辑——包括订单匹配、手续费计算、滑点追踪——都严格模拟真实交易所的规则。这意味着你的智能体在这里获得的盈亏曲线与它在真实市场中操作的结果在剔除了网络延迟和极端流动性事件后会高度吻合。这就像给飞行员一个全动飞行模拟器而不是一个简单的游戏手柄。项目的核心价值在于“零风险真环境”。对于AI Agent开发者而言这是一个绝佳的强化学习环境对于策略研究者这是一个强大的回测与A/B测试平台对于想学习预测市场交易的新手这更是一个无压力的实战训练场。它通过标准的Model Context ProtocolMCP暴露了26个交易工具使得像Claude Code、Cursor这类AI编程助手可以直接操控它进行交易真正实现了“你的AI智能体就是一个交易员”。2. 核心设计理念为何要模拟真实订单簿市面上很多模拟交易工具其价格生成机制要么是随机漫步要么是基于简单的公式推算。这类工具对于理解基础概念有帮助但对于策略开发尤其是高频或对价格敏感的套利策略其参考价值有限。polymarket-paper-trader选择了一条更复杂但更正确的路实时抓取并模拟真实的订单簿Order Book执行。2.1 订单簿模拟 vs. 中间价模拟这是理解本项目价值的关键。假设一个市场“比特币是否会涨到10万美元”的当前订单簿如下卖单Asks YES $0.62 (100股) YES $0.63 (200股) YES $0.65 (150股)买单Bids YES $0.60 (80股) YES $0.59 (120股) YES $0.58 (100股)中间价Midpoint (0.60 0.62) / 2 $0.61一个简单的模拟器可能直接让你以$0.61的“理论价”成交。但现实中如果你的市价买单足够大你的成交过程称为“吃单”会是首先吃掉$0.62的100股。如果还没买够继续吃掉$0.63的200股。如果还不够再吃掉$0.65的150股。 你的实际成交均价会是这三笔交易的加权平均可能远高于$0.61。这个差价就是滑点Slippage是策略盈亏的重要影响因素。polymarket-paper-trader严格模拟了这个“吃单”过程。当你下一个“买入1000股YES”的市价单时引擎会从最低的卖单$0.62开始逐层消耗流动性直到你的订单被完全满足或流动性耗尽导致部分成交。这个过程会精确记录每一笔成交的价格和数量并计算出实际成交均价和滑点以基点bps表示。这种模拟的保真度使得策略对流动性的敏感性、大单对市场的影响等微观结构因素得以被真实检验。注意 滑点是双刃剑。对于小额订单滑点影响微乎其微但对于试图快速建立或平仓的大额订单滑点可能吞噬掉预期的全部利润。在模拟环境中提前暴露这个问题能让你优化策略的入场/出场方式例如改用限价单或拆分成小单。2.2 精确的费用模型Polymarket对每笔成交收取费用公式为费用 (bps / 10000) × min(价格, 1-价格) × 股数。其中bps是基点例如2.5个基点0.025%。min(价格, 1-价格)这个设计很巧妙它确保了无论你交易的是YES端还是NO端当价格越接近0.5不确定性最高时费用相对较高当价格越接近0或1确定性最高时费用较低。这反映了平台对提供流动性风险的补偿。本项目完全复现了这个费用模型。这意味着你的模拟账户的净盈亏是扣除了与真实交易完全一致的手续费后的结果。忽略费用的策略回测都是“耍流氓”而这里帮你把“流氓”因素都考虑进去了。2.3 限价单状态机除了市价单项目完整实现了限价单Limit Order的逻辑支持GTC一直有效直至取消和GTD在指定日期前有效。限价单被放入一个待执行订单池引擎会定期或手动触发检查市场价格是否触及了限价单的触发条件。例如你下一个“在$0.55买入YES”的限价单当市场的YES卖单价跌至$0.55或以下时订单才会被执行。这为实现网格交易、止损止盈等复杂策略提供了基础。3. 环境搭建与核心操作指南3.1 安装与初始化安装非常直接推荐使用pip。确保你的Python版本在3.10以上。# 安装核心库 pip install polymarket-paper-trader # 初始化一个模拟账户默认赋予10000美元虚拟资金 pm-trader init --balance 10000初始化命令会在用户目录下通常是~/.polymarket-paper-trader/创建一个SQLite数据库文件用于存储你的账户信息、持仓、订单历史和市场快照等所有数据。你可以通过--data-dir参数指定自定义的数据目录这对于多环境部署或数据隔离非常有用。3.2 探索市场与获取信息在让AI智能体下场交易前先带它熟悉一下战场环境。# 列出当前活跃的市场按流动性排序流动性越高买卖价差通常越小交易越容易 pm-trader markets list --sort liquidity --limit 10 # 搜索特定主题的市场例如所有关于“比特币”的预测 pm-trader markets search bitcoin # 查看某个具体市场的详细信息包括描述、解析时间、各结果当前价格等 pm-trader markets get will-bitcoin-hit-100k # 获取某个市场的实时订单簿深度为5显示买卖各5档 pm-trader book will-bitcoin-hit-100k --depth 5 # 监控一个或多个市场的价格实时变动每秒刷新 pm-trader watch will-bitcoin-hit-100k trump-2024 --outcome yes这些命令是你的智能体感知市场的“眼睛”。markets list和search帮助它发现交易机会book让它洞察市场的微观结构和深度watch则为它提供实时的价格流数据是开发趋势跟踪策略的基础。3.3 执行交易与管理头寸核心的交易操作非常简单直观。# 市价买入在“比特币到10万”市场中买入价值100美元的YES份额 pm-trader buy will-bitcoin-hit-100k yes 100 # 市价卖出卖出50股YES份额 pm-trader sell will-bitcoin-hit-100k yes 50 # 下限价单在价格达到0.55时买入价值200美元的YES份额 pm-trader orders place will-bitcoin-hit-100k yes buy 200 0.55 # 查看当前持仓组合包含每个头寸的当前市值、成本、浮动盈亏 pm-trader portfolio # 查看所有挂起的限价单 pm-trader orders list # 手动检查并执行已达到触发条件的限价单 pm-trader orders check # 查看完整的交易历史记录 pm-trader history --limit 20这里有一个关键细节buy和sell命令默认使用--type fakFill and Kill模式。这意味着订单会立即尝试与当前订单簿匹配能成交多少算多少未成交的部分自动取消。这模拟了现实交易中常见的“即时或取消”订单。另一种模式是fokFill or Kill要求订单必须全部立即成交否则整个订单取消。选择哪种模式取决于你的策略fak适合在流动性不确定时尝试建立部分头寸fok适合对执行价格有严格要求的策略确保全部以预期价格成交。3.4 业绩分析与数据导出交易之后复盘至关重要。# 查看关键业绩指标胜率、投资回报率(ROI)、总利润、最大回撤等 pm-trader stats # 生成一个美观的、可分享的业绩卡片Markdown格式 pm-trader stats --card # 生成针对Twitter/X平台优化过的分享文本 pm-trader stats --tweet # 将交易历史导出为CSV方便用Excel或Python进行深入分析 pm-trader export trades --format csv my_trades.csv # 将当前持仓导出为JSON pm-trader export positions --format jsonstats命令提供的最大回撤Max Drawdown是一个非常重要的风险指标。它衡量了你的账户净值从历史最高点下跌的最大幅度。一个年化收益率很高但最大回撤也巨大的策略其实际风险可能令人无法承受。在模拟阶段就密切关注这个指标有助于你构建更稳健的策略。4. 策略开发与回测实战项目内置了三个经典策略示例并提供了强大的回测框架这是将想法转化为可验证系统的核心环节。4.1 理解内置策略逻辑动量策略Momentum 核心思想是“追涨”。当YES价格突破某个阈值如0.55时认为上涨趋势确立开仓买入。同时设置止盈点如0.70和止损点如0.35。这是一种典型的趋势跟踪策略在单边市中表现良好但在震荡市中会反复挨打。均值回归策略Mean Reversion 核心思想是“高抛低吸”。它认为价格会围绕一个“公平价值”如0.50波动。当价格大幅偏离公平价值时如YES价格跌至0.38预期价格会回归于是买入。当价格回归到公平价值附近时卖出。这种策略在震荡市中表现优异但在强趋势市中会过早逆势操作导致亏损。限价网格策略Limit Grid 这是一种自动化做市策略。在现价下方间隔性地挂出一系列限价买单例如在0.45, 0.44, 0.43各挂一个买单同时在现价上方挂出对应的限价卖单。价格波动时会自动触发低买高卖。这种策略赚取的是波动性的钱但对资金利用率要求高且需要市场在一定区间内震荡。运行这些策略进行试炼pm-trader benchmark run examples.momentum.runbenchmark run命令会初始化引擎并运行你指定的策略函数。策略会开始扫描市场、做出交易决策。你可以在另一个终端用pm-trader portfolio和pm-trader stats实时观察其表现。4.2 从零编写你的第一个策略让我们写一个简单的“恐惧与贪婪指数”策略。假设我们认为当市场对某个事件极度悲观YES价格极低时可能是买入机会。# my_fear_greed_strategy.py import logging from pm_trader.engine import Engine # 设置日志方便观察策略运行过程 logging.basicConfig(levellogging.INFO) logger logging.getLogger(__name__) def run(engine: Engine) - None: 一个简单的恐惧贪婪策略 # 1. 搜索我们感兴趣的市场类别比如“选举” election_markets engine.api.search_markets(election) logger.info(fFound {len(election_markets)} election-related markets.) for market in election_markets: # 2. 过滤掉已关闭的市场 if market.closed: continue # 3. 获取当前YES价格 yes_price market.yes_price # 这是一个属性返回当前中间价 market_id market.slug # 4. 策略逻辑如果YES价格低于0.2视为市场过度恐惧买入 if yes_price 0.20: logger.info(fMarket {market_id} is fearful (YES price: {yes_price:.3f}). Buying $100 of YES.) try: # 使用引擎的buy方法买入价值100美元的YES # 注意engine.buy接收的是美元金额不是股数 engine.buy(market_id, yes, 100.0) except Exception as e: logger.error(fFailed to buy {market_id}: {e}) # 5. 如果YES价格高于0.8视为市场过度贪婪可以考虑卖出如果我们有持仓的话 # 这里需要先检查持仓逻辑略复杂作为进阶练习保存文件后运行它pm-trader --account fear_greed_demo init --balance 5000 pm-trader --account fear_greed_demo benchmark run my_fear_greed_strategy.run这个策略虽然简单但涵盖了策略开发的基本流程数据获取市场搜索 - 信号生成价格判断 - 订单执行。你可以在此基础上增加更复杂的条件如交易量过滤、持仓管理、止损逻辑等。4.3 进行历史回测用未来数据验证过去策略是无效的。回测要求使用历史某一时刻的数据快照来运行策略评估其历史表现。polymarket-paper-trader的引擎在设计时就考虑到了这一点。项目通过backtest工具支持回测但你需要提供历史价格快照数据。这些数据可以通过定期调用pm-trader book命令并保存下来构建或者寻找第三方提供的历史订单簿数据集。回测函数的结构与实时策略类似但会在每个历史时间点上被调用。# 一个回测策略的框架示例 def backtest_strategy(engine, snapshot, prices): engine: 回测引擎实例 snapshot: 某个历史时刻的市场订单簿快照 prices: 该时刻各结果的价格字典如 {yes: 0.45, no: 0.55} market_slug snapshot.market_slug yes_price prices.get(yes) # 你的回测逻辑在这里 if yes_price and yes_price 0.25: # 在历史时刻下买入订单 # 注意回测中的订单执行会基于snapshot中的订单簿模拟 engine.buy(market_slug, yes, 50.0)运行回测需要组织好历史数据文件并通过特定命令调用。这通常是量化研究更深入的阶段但框架已经为你准备好了接口。5. 高级功能多账户、MCP集成与性能分析5.1 多账户并行与A/B测试这是策略研发的利器。你可以同时运行多个策略或者用不同参数运行同一策略在完全相同的市场环境下进行对比。# 创建两个独立的账户 pm-trader --account strategy_a init --balance 10000 pm-trader --account strategy_b init --balance 10000 # 为两个账户运行不同的策略需要你提前写好strategy_a.py和strategy_b.py pm-trader --account strategy_a benchmark run strategy_a.run pm-trader --account strategy_b benchmark run strategy_b.run # 一段时间后比较两个账户的业绩 pm-trader benchmark compare strategy_a strategy_b # 或者进行一场“对决”生成对比卡片 pm-trader pk strategy_a strategy_b实操心得 在进行A/B测试时务必确保两个账户的初始资金和测试时间段完全一致这样才能公平地比较策略本身的优劣而不是运气或资金量的差异。你可以编写一个脚本同时启动多个账户的策略运行。5.2 通过MCP让AI智能体直接交易这是项目最酷的特性之一。MCPModel Context Protocol是一个让AI模型安全、结构化地使用外部工具的协议。polymarket-paper-trader启动一个MCP服务器暴露出26个交易相关的函数作为“工具”。# 启动MCP服务器标准输入输出流模式 pm-trader-mcp然后在支持MCP的AI编程助手如Claude Code配置中添加{ mcpServers: { polymarket-paper-trader: { command: pm-trader-mcp } } }配置完成后你的AI助手就“获得”了交易能力。你可以用自然语言指挥它“查看我余额最多的三个市场”“在比特币价格低于0.4时买入500美元YES”“分析我上周交易的历史找出亏损最大的三笔交易并总结原因”。AI可以调用get_balance,search_markets,buy,history等工具来执行这些任务并基于结果进行推理和决策。重要提示 虽然交易是模拟的但AI基于真实数据做出的决策逻辑是真实的。这为开发自主交易的AI Agent提供了完美的沙盒。你可以先让AI观察watch_prices然后学习分析history最后在模拟中实践buy/sell形成一个完整的强化学习闭环。5.3 业绩深度分析与常见陷阱模拟交易的目的不是创造一条永远向上的净值曲线而是暴露问题、优化策略。除了看总盈亏和ROI更应关注以下维度胜率Win Rate vs 盈亏比Profit Factor 高胜率但平均盈利小于平均亏损的策略长期可能还是亏钱的。反之胜率仅40%但盈亏比很高的策略赚大钱亏小钱可能更成功。stats命令应该结合两者来看。交易频率与夏普比率 过于频繁的交易可能会让手续费蚕食利润。评估策略时可以粗略计算一下总利润/交易次数看看平均每笔交易的净利润是否为正。更专业的指标是夏普比率需要计算收益率序列的标准差它衡量的是承担单位风险所获得的超额回报。虽然CLI未直接提供但你可以导出交易数据后自行计算。最大回撤与恢复时间 你的策略能承受多大的连续亏损净值从高点下跌20%后需要多久才能涨回来这直接关系到策略的心理承受能力和实际风险。一个回撤深且恢复时间长的策略可能在实盘中被你在最低点提前终止。市场环境适应性 你的策略在趋势市和震荡市中表现如何可以通过选择不同时期、不同类型的市场进行回测来检验。例如用“美国大选”市场测试政治事件驱动下的表现用“比特币价格”市场测试高波动性资产的表现。常见陷阱排查问题 策略一直不交易。排查 检查市场搜索条件是否太窄或市场已关闭。检查买入/卖出条件判断逻辑如价格比较是否正确。查看日志中是否有错误信息如余额不足、市场不存在。问题 策略频繁交易但持续小额亏损。排查 极有可能是手续费导致的。计算一下单笔交易的平均毛利是否能覆盖手续费。考虑降低交易频率或者转向在价差更大的市场进行套利但需注意流动性风险。问题 限价单一直不成交。排查 用pm-trader book查看当前订单簿确认你的限价单价格是否偏离市场太远例如买单价格低于所有卖单。市场价格可能从未触及你的订单价格。或者检查订单是否已过期GTD。问题 回测结果完美但模拟实盘表现差。排查 这是“过拟合”的典型症状。回测时可能无意中使用了未来函数例如用到了收盘价做信号但在实际交易中那个时刻无法知道收盘价或者参数对历史数据过度优化。确保回测逻辑与实时交易逻辑完全一致并在未知的样本外市场或时间段上测试策略。6. 项目架构与扩展开发指南对于想深入了解或参与贡献的开发者理解项目架构很有帮助。核心模块大致如下pm_trader/api.py 负责与Polymarket公共API的通信获取市场列表、订单簿等实时数据。pm_trader/engine.py 核心的模拟交易引擎。它维护账户状态处理订单市价单、限价单计算成交价、手续费、滑点更新持仓和现金。pm_trader/models.py 定义了数据模型如Account账户、Position持仓、Order订单、Trade成交记录等并使用SQLAlchemy ORM与SQLite数据库交互。pm_trader/cli.py 命令行接口的实现将用户命令解析为对引擎和API的调用。pm_trader/mcp_server.py MCP服务器的实现将引擎的功能包装成标准的MCP工具。如果你想扩展功能例如添加新的数据源 可以继承或修改api.py中的类支持从其他预测市场或数据接口获取信息。实现更复杂的订单类型 如止损单、跟踪止损单需要在engine.py的订单处理逻辑中添加新的状态和检查条件。开发可视化面板 可以基于导出的CSV/JSON数据使用Plotly、Streamlit等库构建一个Web仪表盘实时展示资金曲线、持仓分布、风险指标等。开发环境搭建# 克隆仓库 git clone https://github.com/agent-next/polymarket-paper-trader.git cd polymarket-paper-trader # 使用uv快速Python包管理器安装开发依赖 uv pip install -e .[dev] # 运行测试 pytest -m not live # 运行不依赖网络API的单元测试项目采用MIT许可证意味着你可以在商业项目中自由使用、修改和分发它这为企业和个人开发者提供了极大的灵活性。最后交易策略的开发是一场与市场和自己心态的马拉松而非冲刺。polymarket-paper-trader提供的这个高保真沙盒是你最安全的训练场。从这里开始让你的AI智能体或交易想法经历数百次模拟的牛熊转换积累经验迭代策略最终形成一套经得起考验的交易体系。记住在模拟中亏掉的所有“虚拟钱”都是为了在现实中保住和赚取真金白银所交的最划算的学费。 AI智能体预测市场交易沙盒：零风险模拟真实订单簿与策略回测
1. 项目概述为AI智能体打造的零风险预测市场交易沙盒如果你正在开发一个AI智能体并且希望它能学习、测试甚至精通在Polymarket这类预测市场上的交易策略那么你很可能面临一个两难困境要么用真金白银去冒险要么只能对着静态数据纸上谈兵。polymarket-paper-trader这个开源项目就是为了解决这个痛点而生的。它不是一个简单的价格模拟器而是一个基于真实订单簿的、高保真度的交易沙盒专门为AI智能体、量化策略开发者和交易爱好者设计。简单来说它给你的AI智能体提供了一个拥有初始虚拟资金比如1万美元的“模拟账户”然后允许它接入Polymarket的实时订单簿进行买卖。所有的交易执行逻辑——包括订单匹配、手续费计算、滑点追踪——都严格模拟真实交易所的规则。这意味着你的智能体在这里获得的盈亏曲线与它在真实市场中操作的结果在剔除了网络延迟和极端流动性事件后会高度吻合。这就像给飞行员一个全动飞行模拟器而不是一个简单的游戏手柄。项目的核心价值在于“零风险真环境”。对于AI Agent开发者而言这是一个绝佳的强化学习环境对于策略研究者这是一个强大的回测与A/B测试平台对于想学习预测市场交易的新手这更是一个无压力的实战训练场。它通过标准的Model Context ProtocolMCP暴露了26个交易工具使得像Claude Code、Cursor这类AI编程助手可以直接操控它进行交易真正实现了“你的AI智能体就是一个交易员”。2. 核心设计理念为何要模拟真实订单簿市面上很多模拟交易工具其价格生成机制要么是随机漫步要么是基于简单的公式推算。这类工具对于理解基础概念有帮助但对于策略开发尤其是高频或对价格敏感的套利策略其参考价值有限。polymarket-paper-trader选择了一条更复杂但更正确的路实时抓取并模拟真实的订单簿Order Book执行。2.1 订单簿模拟 vs. 中间价模拟这是理解本项目价值的关键。假设一个市场“比特币是否会涨到10万美元”的当前订单簿如下卖单Asks YES $0.62 (100股) YES $0.63 (200股) YES $0.65 (150股)买单Bids YES $0.60 (80股) YES $0.59 (120股) YES $0.58 (100股)中间价Midpoint (0.60 0.62) / 2 $0.61一个简单的模拟器可能直接让你以$0.61的“理论价”成交。但现实中如果你的市价买单足够大你的成交过程称为“吃单”会是首先吃掉$0.62的100股。如果还没买够继续吃掉$0.63的200股。如果还不够再吃掉$0.65的150股。 你的实际成交均价会是这三笔交易的加权平均可能远高于$0.61。这个差价就是滑点Slippage是策略盈亏的重要影响因素。polymarket-paper-trader严格模拟了这个“吃单”过程。当你下一个“买入1000股YES”的市价单时引擎会从最低的卖单$0.62开始逐层消耗流动性直到你的订单被完全满足或流动性耗尽导致部分成交。这个过程会精确记录每一笔成交的价格和数量并计算出实际成交均价和滑点以基点bps表示。这种模拟的保真度使得策略对流动性的敏感性、大单对市场的影响等微观结构因素得以被真实检验。注意 滑点是双刃剑。对于小额订单滑点影响微乎其微但对于试图快速建立或平仓的大额订单滑点可能吞噬掉预期的全部利润。在模拟环境中提前暴露这个问题能让你优化策略的入场/出场方式例如改用限价单或拆分成小单。2.2 精确的费用模型Polymarket对每笔成交收取费用公式为费用 (bps / 10000) × min(价格, 1-价格) × 股数。其中bps是基点例如2.5个基点0.025%。min(价格, 1-价格)这个设计很巧妙它确保了无论你交易的是YES端还是NO端当价格越接近0.5不确定性最高时费用相对较高当价格越接近0或1确定性最高时费用较低。这反映了平台对提供流动性风险的补偿。本项目完全复现了这个费用模型。这意味着你的模拟账户的净盈亏是扣除了与真实交易完全一致的手续费后的结果。忽略费用的策略回测都是“耍流氓”而这里帮你把“流氓”因素都考虑进去了。2.3 限价单状态机除了市价单项目完整实现了限价单Limit Order的逻辑支持GTC一直有效直至取消和GTD在指定日期前有效。限价单被放入一个待执行订单池引擎会定期或手动触发检查市场价格是否触及了限价单的触发条件。例如你下一个“在$0.55买入YES”的限价单当市场的YES卖单价跌至$0.55或以下时订单才会被执行。这为实现网格交易、止损止盈等复杂策略提供了基础。3. 环境搭建与核心操作指南3.1 安装与初始化安装非常直接推荐使用pip。确保你的Python版本在3.10以上。# 安装核心库 pip install polymarket-paper-trader # 初始化一个模拟账户默认赋予10000美元虚拟资金 pm-trader init --balance 10000初始化命令会在用户目录下通常是~/.polymarket-paper-trader/创建一个SQLite数据库文件用于存储你的账户信息、持仓、订单历史和市场快照等所有数据。你可以通过--data-dir参数指定自定义的数据目录这对于多环境部署或数据隔离非常有用。3.2 探索市场与获取信息在让AI智能体下场交易前先带它熟悉一下战场环境。# 列出当前活跃的市场按流动性排序流动性越高买卖价差通常越小交易越容易 pm-trader markets list --sort liquidity --limit 10 # 搜索特定主题的市场例如所有关于“比特币”的预测 pm-trader markets search bitcoin # 查看某个具体市场的详细信息包括描述、解析时间、各结果当前价格等 pm-trader markets get will-bitcoin-hit-100k # 获取某个市场的实时订单簿深度为5显示买卖各5档 pm-trader book will-bitcoin-hit-100k --depth 5 # 监控一个或多个市场的价格实时变动每秒刷新 pm-trader watch will-bitcoin-hit-100k trump-2024 --outcome yes这些命令是你的智能体感知市场的“眼睛”。markets list和search帮助它发现交易机会book让它洞察市场的微观结构和深度watch则为它提供实时的价格流数据是开发趋势跟踪策略的基础。3.3 执行交易与管理头寸核心的交易操作非常简单直观。# 市价买入在“比特币到10万”市场中买入价值100美元的YES份额 pm-trader buy will-bitcoin-hit-100k yes 100 # 市价卖出卖出50股YES份额 pm-trader sell will-bitcoin-hit-100k yes 50 # 下限价单在价格达到0.55时买入价值200美元的YES份额 pm-trader orders place will-bitcoin-hit-100k yes buy 200 0.55 # 查看当前持仓组合包含每个头寸的当前市值、成本、浮动盈亏 pm-trader portfolio # 查看所有挂起的限价单 pm-trader orders list # 手动检查并执行已达到触发条件的限价单 pm-trader orders check # 查看完整的交易历史记录 pm-trader history --limit 20这里有一个关键细节buy和sell命令默认使用--type fakFill and Kill模式。这意味着订单会立即尝试与当前订单簿匹配能成交多少算多少未成交的部分自动取消。这模拟了现实交易中常见的“即时或取消”订单。另一种模式是fokFill or Kill要求订单必须全部立即成交否则整个订单取消。选择哪种模式取决于你的策略fak适合在流动性不确定时尝试建立部分头寸fok适合对执行价格有严格要求的策略确保全部以预期价格成交。3.4 业绩分析与数据导出交易之后复盘至关重要。# 查看关键业绩指标胜率、投资回报率(ROI)、总利润、最大回撤等 pm-trader stats # 生成一个美观的、可分享的业绩卡片Markdown格式 pm-trader stats --card # 生成针对Twitter/X平台优化过的分享文本 pm-trader stats --tweet # 将交易历史导出为CSV方便用Excel或Python进行深入分析 pm-trader export trades --format csv my_trades.csv # 将当前持仓导出为JSON pm-trader export positions --format jsonstats命令提供的最大回撤Max Drawdown是一个非常重要的风险指标。它衡量了你的账户净值从历史最高点下跌的最大幅度。一个年化收益率很高但最大回撤也巨大的策略其实际风险可能令人无法承受。在模拟阶段就密切关注这个指标有助于你构建更稳健的策略。4. 策略开发与回测实战项目内置了三个经典策略示例并提供了强大的回测框架这是将想法转化为可验证系统的核心环节。4.1 理解内置策略逻辑动量策略Momentum 核心思想是“追涨”。当YES价格突破某个阈值如0.55时认为上涨趋势确立开仓买入。同时设置止盈点如0.70和止损点如0.35。这是一种典型的趋势跟踪策略在单边市中表现良好但在震荡市中会反复挨打。均值回归策略Mean Reversion 核心思想是“高抛低吸”。它认为价格会围绕一个“公平价值”如0.50波动。当价格大幅偏离公平价值时如YES价格跌至0.38预期价格会回归于是买入。当价格回归到公平价值附近时卖出。这种策略在震荡市中表现优异但在强趋势市中会过早逆势操作导致亏损。限价网格策略Limit Grid 这是一种自动化做市策略。在现价下方间隔性地挂出一系列限价买单例如在0.45, 0.44, 0.43各挂一个买单同时在现价上方挂出对应的限价卖单。价格波动时会自动触发低买高卖。这种策略赚取的是波动性的钱但对资金利用率要求高且需要市场在一定区间内震荡。运行这些策略进行试炼pm-trader benchmark run examples.momentum.runbenchmark run命令会初始化引擎并运行你指定的策略函数。策略会开始扫描市场、做出交易决策。你可以在另一个终端用pm-trader portfolio和pm-trader stats实时观察其表现。4.2 从零编写你的第一个策略让我们写一个简单的“恐惧与贪婪指数”策略。假设我们认为当市场对某个事件极度悲观YES价格极低时可能是买入机会。# my_fear_greed_strategy.py import logging from pm_trader.engine import Engine # 设置日志方便观察策略运行过程 logging.basicConfig(levellogging.INFO) logger logging.getLogger(__name__) def run(engine: Engine) - None: 一个简单的恐惧贪婪策略 # 1. 搜索我们感兴趣的市场类别比如“选举” election_markets engine.api.search_markets(election) logger.info(fFound {len(election_markets)} election-related markets.) for market in election_markets: # 2. 过滤掉已关闭的市场 if market.closed: continue # 3. 获取当前YES价格 yes_price market.yes_price # 这是一个属性返回当前中间价 market_id market.slug # 4. 策略逻辑如果YES价格低于0.2视为市场过度恐惧买入 if yes_price 0.20: logger.info(fMarket {market_id} is fearful (YES price: {yes_price:.3f}). Buying $100 of YES.) try: # 使用引擎的buy方法买入价值100美元的YES # 注意engine.buy接收的是美元金额不是股数 engine.buy(market_id, yes, 100.0) except Exception as e: logger.error(fFailed to buy {market_id}: {e}) # 5. 如果YES价格高于0.8视为市场过度贪婪可以考虑卖出如果我们有持仓的话 # 这里需要先检查持仓逻辑略复杂作为进阶练习保存文件后运行它pm-trader --account fear_greed_demo init --balance 5000 pm-trader --account fear_greed_demo benchmark run my_fear_greed_strategy.run这个策略虽然简单但涵盖了策略开发的基本流程数据获取市场搜索 - 信号生成价格判断 - 订单执行。你可以在此基础上增加更复杂的条件如交易量过滤、持仓管理、止损逻辑等。4.3 进行历史回测用未来数据验证过去策略是无效的。回测要求使用历史某一时刻的数据快照来运行策略评估其历史表现。polymarket-paper-trader的引擎在设计时就考虑到了这一点。项目通过backtest工具支持回测但你需要提供历史价格快照数据。这些数据可以通过定期调用pm-trader book命令并保存下来构建或者寻找第三方提供的历史订单簿数据集。回测函数的结构与实时策略类似但会在每个历史时间点上被调用。# 一个回测策略的框架示例 def backtest_strategy(engine, snapshot, prices): engine: 回测引擎实例 snapshot: 某个历史时刻的市场订单簿快照 prices: 该时刻各结果的价格字典如 {yes: 0.45, no: 0.55} market_slug snapshot.market_slug yes_price prices.get(yes) # 你的回测逻辑在这里 if yes_price and yes_price 0.25: # 在历史时刻下买入订单 # 注意回测中的订单执行会基于snapshot中的订单簿模拟 engine.buy(market_slug, yes, 50.0)运行回测需要组织好历史数据文件并通过特定命令调用。这通常是量化研究更深入的阶段但框架已经为你准备好了接口。5. 高级功能多账户、MCP集成与性能分析5.1 多账户并行与A/B测试这是策略研发的利器。你可以同时运行多个策略或者用不同参数运行同一策略在完全相同的市场环境下进行对比。# 创建两个独立的账户 pm-trader --account strategy_a init --balance 10000 pm-trader --account strategy_b init --balance 10000 # 为两个账户运行不同的策略需要你提前写好strategy_a.py和strategy_b.py pm-trader --account strategy_a benchmark run strategy_a.run pm-trader --account strategy_b benchmark run strategy_b.run # 一段时间后比较两个账户的业绩 pm-trader benchmark compare strategy_a strategy_b # 或者进行一场“对决”生成对比卡片 pm-trader pk strategy_a strategy_b实操心得 在进行A/B测试时务必确保两个账户的初始资金和测试时间段完全一致这样才能公平地比较策略本身的优劣而不是运气或资金量的差异。你可以编写一个脚本同时启动多个账户的策略运行。5.2 通过MCP让AI智能体直接交易这是项目最酷的特性之一。MCPModel Context Protocol是一个让AI模型安全、结构化地使用外部工具的协议。polymarket-paper-trader启动一个MCP服务器暴露出26个交易相关的函数作为“工具”。# 启动MCP服务器标准输入输出流模式 pm-trader-mcp然后在支持MCP的AI编程助手如Claude Code配置中添加{ mcpServers: { polymarket-paper-trader: { command: pm-trader-mcp } } }配置完成后你的AI助手就“获得”了交易能力。你可以用自然语言指挥它“查看我余额最多的三个市场”“在比特币价格低于0.4时买入500美元YES”“分析我上周交易的历史找出亏损最大的三笔交易并总结原因”。AI可以调用get_balance,search_markets,buy,history等工具来执行这些任务并基于结果进行推理和决策。重要提示 虽然交易是模拟的但AI基于真实数据做出的决策逻辑是真实的。这为开发自主交易的AI Agent提供了完美的沙盒。你可以先让AI观察watch_prices然后学习分析history最后在模拟中实践buy/sell形成一个完整的强化学习闭环。5.3 业绩深度分析与常见陷阱模拟交易的目的不是创造一条永远向上的净值曲线而是暴露问题、优化策略。除了看总盈亏和ROI更应关注以下维度胜率Win Rate vs 盈亏比Profit Factor 高胜率但平均盈利小于平均亏损的策略长期可能还是亏钱的。反之胜率仅40%但盈亏比很高的策略赚大钱亏小钱可能更成功。stats命令应该结合两者来看。交易频率与夏普比率 过于频繁的交易可能会让手续费蚕食利润。评估策略时可以粗略计算一下总利润/交易次数看看平均每笔交易的净利润是否为正。更专业的指标是夏普比率需要计算收益率序列的标准差它衡量的是承担单位风险所获得的超额回报。虽然CLI未直接提供但你可以导出交易数据后自行计算。最大回撤与恢复时间 你的策略能承受多大的连续亏损净值从高点下跌20%后需要多久才能涨回来这直接关系到策略的心理承受能力和实际风险。一个回撤深且恢复时间长的策略可能在实盘中被你在最低点提前终止。市场环境适应性 你的策略在趋势市和震荡市中表现如何可以通过选择不同时期、不同类型的市场进行回测来检验。例如用“美国大选”市场测试政治事件驱动下的表现用“比特币价格”市场测试高波动性资产的表现。常见陷阱排查问题 策略一直不交易。排查 检查市场搜索条件是否太窄或市场已关闭。检查买入/卖出条件判断逻辑如价格比较是否正确。查看日志中是否有错误信息如余额不足、市场不存在。问题 策略频繁交易但持续小额亏损。排查 极有可能是手续费导致的。计算一下单笔交易的平均毛利是否能覆盖手续费。考虑降低交易频率或者转向在价差更大的市场进行套利但需注意流动性风险。问题 限价单一直不成交。排查 用pm-trader book查看当前订单簿确认你的限价单价格是否偏离市场太远例如买单价格低于所有卖单。市场价格可能从未触及你的订单价格。或者检查订单是否已过期GTD。问题 回测结果完美但模拟实盘表现差。排查 这是“过拟合”的典型症状。回测时可能无意中使用了未来函数例如用到了收盘价做信号但在实际交易中那个时刻无法知道收盘价或者参数对历史数据过度优化。确保回测逻辑与实时交易逻辑完全一致并在未知的样本外市场或时间段上测试策略。6. 项目架构与扩展开发指南对于想深入了解或参与贡献的开发者理解项目架构很有帮助。核心模块大致如下pm_trader/api.py 负责与Polymarket公共API的通信获取市场列表、订单簿等实时数据。pm_trader/engine.py 核心的模拟交易引擎。它维护账户状态处理订单市价单、限价单计算成交价、手续费、滑点更新持仓和现金。pm_trader/models.py 定义了数据模型如Account账户、Position持仓、Order订单、Trade成交记录等并使用SQLAlchemy ORM与SQLite数据库交互。pm_trader/cli.py 命令行接口的实现将用户命令解析为对引擎和API的调用。pm_trader/mcp_server.py MCP服务器的实现将引擎的功能包装成标准的MCP工具。如果你想扩展功能例如添加新的数据源 可以继承或修改api.py中的类支持从其他预测市场或数据接口获取信息。实现更复杂的订单类型 如止损单、跟踪止损单需要在engine.py的订单处理逻辑中添加新的状态和检查条件。开发可视化面板 可以基于导出的CSV/JSON数据使用Plotly、Streamlit等库构建一个Web仪表盘实时展示资金曲线、持仓分布、风险指标等。开发环境搭建# 克隆仓库 git clone https://github.com/agent-next/polymarket-paper-trader.git cd polymarket-paper-trader # 使用uv快速Python包管理器安装开发依赖 uv pip install -e .[dev] # 运行测试 pytest -m not live # 运行不依赖网络API的单元测试项目采用MIT许可证意味着你可以在商业项目中自由使用、修改和分发它这为企业和个人开发者提供了极大的灵活性。最后交易策略的开发是一场与市场和自己心态的马拉松而非冲刺。polymarket-paper-trader提供的这个高保真沙盒是你最安全的训练场。从这里开始让你的AI智能体或交易想法经历数百次模拟的牛熊转换积累经验迭代策略最终形成一套经得起考验的交易体系。记住在模拟中亏掉的所有“虚拟钱”都是为了在现实中保住和赚取真金白银所交的最划算的学费。