使用说明
Polymarket直播
一个由人工智能驱动的交易机器人和MCP服务器,用于分析Polymarket上的板球博彩市场。
概述
该项目提供了两个互补工具:
- MCP服务器 -Cursor/AI代理商分析Polymarket市场的只读研究工具
- 交易机器人 -使用Claude Sonnet进行决策的自主纸张交易机器人
两者共享相同的API基础客户端,并使用实时Polymarket数据。
特性
- 通过OpenRouter使用Claude Sonnet的AI驱动策略
- 来自Polymarket Gamma和CLOB API的实时市场数据
- 具有损益跟踪功能的投资组合管理
- 可插拔的策略系统,易于扩展
- 交易和投资组合状态的SQLite持久性
- 可通过YAML配置
- 仅限于纸上交易(没有真钱)
建筑
该项目遵循分层架构,关注点明确分离:
src/
├── polymarket/ # Pure API clients (domain-agnostic)
│ ├── gamma.py # Gamma API (events/markets discovery)
│ ├── clob.py # CLOB API (pricing/orderbook)
│ ├── models.py # Pydantic models
│ └── utils.py # Shared utilities
│
├── mcp/ # MCP servers for Cursor integration
│ ├── base.py # Base server with generic tools
│ └── cricket.py # Cricket-specific server
│
├── bot/ # Trading bot framework (domain-agnostic)
│ ├── base.py # Base bot with main loop
│ ├── config.py # Configuration loader
│ ├── database.py # SQLite persistence
│ └── portfolio.py # Portfolio/position management
│
├── domains/ # Domain-specific implementations
│ └── cricket/
│ ├── bot.py # Cricket bot runner
│ ├── scanner.py # Market scanner
│ └── prompts.py # LLM prompts
│
└── strategies/ # Pluggable trading strategies
├── base.py # Base strategy interface
└── llm.py # LLM-powered strategy
设计原则
- 领域无关核心 -API客户端和机器人程序框架适用于任何市场类型
- 可插拔策略 -易于添加动量、价值或套利策略
- 共享HTTP客户端 -API调用之间的高效连接重用
- 并发API调用 -用途
asyncio.gather()用于并行数据提取 - 类型安全性 -用于数据验证的Pydantic模型
- 清洁分离 -MCP服务器和交易机器人是独立的
快速开始
先决条件
- Python 3.11+
- OpenRouter API密钥(用于Claude访问)
安装
# Clone the repository
git clone https://github.com/artvandelay/polymarket-agents.git
cd polymarket-agents
# Create and activate virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install mcp httpx pydantic websockets python-dotenv pyyaml aiosqlite
配置
- 复制
.env.example到.env并添加您的OpenRouter API密钥:
cp .env.example .env
# Edit .env and set OPENROUTER_API_KEY
- 审查
config.yaml调整交易参数:
trading:
starting_capital: 1000
interval_minutes: 5
duration_hours: 2
max_position_size_pct: 30
strategies:
ai:
model: anthropic/claude-3.5-sonnet
temperature: 0.7
min_confidence: 0.6
运行Bot
快速测试(3分钟):
python -m src.domains.cricket.bot --duration 0.05 --interval 1
标准课程(2小时):
python -m src.domains.cricket.bot
在tmux中(推荐):
tmux new-session -s trading-bot
python -m src.domains.cricket.bot
# Detach: Ctrl+B, then D
# Reattach: tmux attach -t trading-bot
运行MCP服务器
MCP服务器提供10种市场研究工具:
# Start the server (typically called by Cursor)
polymarket-cricket
看 AGENTS.md 获取可用工具和工作流程的完整文档。
运作原理
交易循环
- 扫描 -在Polymarket上查找活跃的板球比赛
- 收集 -获取市场数据(赔率、交易量、流动性)
- 分析 -克劳德评估每个市场的价值
- 决定 -生成买入/卖出/持有/通过决策
- 执行 -如果决定是买入/卖出,则进行纸质交易
- 睡眠 -等待下一个间隔
人工智能决策
对于每个市场,克劳德分析:
- 当前赔率与估计真实概率
- 市场效率(交易量、流动性、价差)
- 投资组合风险和头寸规模
- 期望值和边缘计算
决策包括置信水平、推理和头寸规模建议。
输出示例
============================================================
Trading Cycle #1 @ 15:56:56
============================================================
Portfolio: $1,000.00 | Cash: $1,000.00 | Open: 0 positions | P&L: +0.00%
[SCAN] Found 2 active matches
[ANALYZE] T20 World Cup: England vs Nepal (Game 1)
Volume: $202,000 | Liquidity: $79,000
[DECISION] PASS
Reasoning: England at 95.6¢ appears efficient. Potential
return (4.4%) doesn't justify the risk. Preserving capital
for markets with clearer edges.
[ANALYZE] T20 World Cup: Afghanistan vs New Zealand (Game 1)
Volume: $437,000 | Liquidity: $73,000
[DECISION] PASS
Confidence: 90%
Reasoning: 99.9¢ offers no realistic edge. Afghanistan at
0.1¢ is too risky. Best to avoid this market.
============================================================
End of Cycle #1
Portfolio Value: $1,000.00
Cash: $1,000.00
Open Positions: 0
Total P&L: +0.00%
Next scan at 15:57:56
数据库模式
机器人将所有状态存储在SQLite中(data/trading.db):
投资组合_状态
timestamp INTEGER PRIMARY KEY
cash REAL
total_value REAL
pnl REAL
num_open_positions INTEGER
位置
id INTEGER PRIMARY KEY
token_id TEXT -- Polymarket token ID
match_slug TEXT -- Match identifier
outcome TEXT -- Team/outcome name
side TEXT -- YES or NO
entry_price REAL -- Entry price (0-1)
shares REAL -- Number of shares
cost_basis REAL -- Total cost
entry_time INTEGER -- Unix timestamp
exit_price REAL -- Exit price (if closed)
exit_time INTEGER -- Exit timestamp
pnl REAL -- Profit/loss
reasoning TEXT -- AI reasoning
status TEXT -- OPEN or CLOSED
决定
id INTEGER PRIMARY KEY
timestamp INTEGER
cycle INTEGER -- Cycle number
match_slug TEXT
action TEXT -- BUY/SELL/HOLD/PASS
reasoning TEXT -- AI reasoning
confidence REAL -- 0-1
edge REAL -- Estimated edge %
market_data TEXT -- JSON snapshot
添加新策略
机器人使用可插拔的策略系统。通过以下方式制定新战略:
- 子类
BaseStrategy在src/strategies/ - 实施
name财产和analyze()方法 - 注册于
src/domains/cricket/bot.py - 在中配置
config.yaml
例子:
from src.strategies.base import BaseStrategy, TradeDecision
class MomentumStrategy(BaseStrategy):
@property
def name(self) -> str:
return "Momentum Strategy"
async def analyze(self, snapshot, portfolio, existing_position):
momentum = self._calculate_momentum(snapshot)
if momentum > self.config["threshold"]:
return TradeDecision(
action="BUY",
outcome="Team with momentum",
position_size=100,
confidence=0.7,
reasoning=f"Strong momentum: +{momentum}% in last hour"
)
return TradeDecision(action="PASS", reasoning="No momentum")
MCP服务器工具
板球MCP服务器提供10个工具:
发现:
list_cricket_leagues-获取所有可用的板球系列list_cricket_matches-列出当前/即将进行的比赛get_match-获取特定比赛的完整细节search_events-跨事件的文本搜索get_market_types-列出有效的市场类型
定价:
get_odds-当前买入/卖出/中点价格get_orderbook-完整的买卖深度get_spread-买卖价差get_price_history-历史价格变动
分析:
analyze_odds-基于Kelly准则的期望值计算器
看 AGENTS.md 查看详细文档和示例工作流。
项目状态
版本: 0.1.0
这是一个早期版本,主要关注纸质交易和研究。核心功能已实现:
- API客户运行
- 机器人执行交易循环
- 人工智能决策集成
- 已实施投资组合跟踪
- 数据库持久性功能
尚未实施:
- 真正的MCP数据集成(目前在某些地方使用模拟数据)
- WebSocket流媒体实时更新
- 止损/止盈自动化
- 真实货币交易(故意排除)
路线图
v0.2-真实数据:
- 完全MCP集成
- WebSocket价格流
- 历史回溯测试
v0.3-高级策略:
- 动量策略
- 价值/EV战略
- 多智能体共识
v0.4-风险管理:
- 自动止损/止盈
- 位置尺寸限制
- 下拉保护
v1.0-生产:
- Web仪表板
- 高级分析
- 生产监控
没有计划提供真钱交易支持。该工具专为研究和学习而设计。
重要提示
仅限于纸品交易
该机器人不执行真实交易。它模拟交易以跟踪绩效,而无需冒险。使用案例:
- 学习投注策略
- 测试人工智能决策
- 了解市场动态
- 战略制定
API成本
OpenRouter对Claude API调用的每个令牌收费:
- 每次决策约0.002美元(500个代币)
- 2小时,间隔5分钟:约24个周期×2场比赛×0.002美元=约0.10美元/场
数据源
- API伽马 -事件/市场发现(公开,无需身份验证)
- API法规 -定价和订单数据(公开,无需身份验证)
故障排除
“找不到OPENROUTER_API_KEY”
- 确保
.env文件存在于项目根目录中 - 验证密钥格式:
OPENROUTER_API_KEY=sk-or-v1-... - 检查钥匙是否过期
“HTTP 401未经授权”
- API密钥无效-请在OpenRouter仪表板中验证
- 信用不足-向OpenRouter帐户添加资金
“数据库已锁定”
- 另一个机器人实例正在运行
- 终止进程:
pkill -f "python.*cricket.bot" - 或者在配置中使用不同的数据库路径
Bot不产生输出
- Python输出可能会被缓冲
- 运行方式:
python -u -m src.domains.cricket.bot - 或重定向到文件:
python -m src.domains.cricket.bot > bot.log 2>&1
许可证
MIT许可证-免费使用、修改和分发。
学分
- Anthropic的MCP框架
- Polymarket公共API(Gamma和CLOB)
- Claude 3.5 Sonnet通过OpenRouter
- 使用Python、httpx、aiosqlite、pydantic、pyyaml构建
v0.1.0 -专为研究而建,专为可扩展性而设计。
有关MCP工具的详细文档,请参阅 AGENTS.md.
有关快速入门示例,请参阅 docs/QUICKSTART.md.
