SkillPay Weather Sniper / 天气狙击机器人
Polymarket 天气事件市场自动化交易系统
📋 目录
- 项目概述
- 快速开始（5分钟）
- 准备工作
- API 密钥获取教程
- 配置文件详解 (.env)
- 代码参数详解
- 启动指南
- 安全建议
- 故障排查
- FAQ 常见问题
<a name="1"></a>
1. 项目概述 / Project Overview
1.1 这是什么？/ What is this?
这是一个自动化交易机器人，用于在 Polymarket 预测市场平台上交易天气事件合约。
核心功能：
- ✅ 实时扫描全球 33 个城市的天气市场
- ✅ 在气温预测确定窗口期（10:00-14:00）自动买入"今日高温超过阈值"的合约
- ✅ 集成 SkillPay 按次计费（每笔成功下单扣 0.01 USDT）
- ✅ 异常容错：网络重试、余额检查、滑点保护
- ✅ 完整日志和状态持久化
1.2 适合谁用？/ Who is this for?
- 对天气预测市场感兴趣的交易者
- 想要自动化策略的开发者
- 学习 Polymarket API 和预测市场的新手
1.3 核心策略 / Core Strategy
假设：每日最高温通常出现在下午14:00-15:00（气象学原理）
逻辑：
1. 上午10:00后，官方气温预报已发布，市场不确定性降低
2. 当 YES token 价格低于 0.35 时，认为市场低估了"高温"概率
3. 以固定金额（默认 $1.0）买入，等待气温确定后价格上涨
4. 可在价格上涨后卖出，或持有至结算（自动按 $1.0 或 $0.0 结算）
<a name="2"></a>
2. 快速开始（5分钟）/ Quick Start (5 min)
2.1 前置条件 / Prerequisites
- ✅ Python 3.9+（推荐 3.10-3.12）
- ✅ 已注册 Polymarket 账户
- ✅ 懂基本命令行操作
2.2 一键启动脚本 / One-Command Setup
# 1. 克隆/进入项目目录（你已经在了）
cd C:\Users\19154\Desktop\skill
# 2. 安装依赖（全程约 2 分钟）
pip install -r requirements.txt
# 3. 复制环境变量模板
copy .env.example .env
# 然后编辑 .env 文件，填入你的密钥（见第4节）
# 4. 测试运行（模拟模式，不花钱）
python sniper.py --dry-run --once
# 5. 看到扫描输出后，说明安装成功！
# 6. 真实交易（谨慎！）
python sniper.py --live --once
<a name="3"></a>
3. 准备工作 / Preparation
3.1 环境检查 / Environment Check
# 检查 Python 版本（需要 3.9+）
python --version
# 预期输出: Python 3.10.x 或 3.11.x 或 3.12.x
# 检查 pip
pip --version
3.2 创建虚拟环境（可选但推荐）/ Virtual Environment
# Windows
python -m venv venv
venv\Scripts\activate
# macOS/Linux
python3 -m venv venv
source venv/bin/activate
3.3 依赖列表 / Dependencies
创建 requirements.txt 文件（如果不存在）：
python-dotenv>=1.0.0
requests>=2.31.0
aiohttp>=3.9.0
pytz>=2024.1
eth-account>=0.11.0
py-clob-client>=0.2.0 # Polymarket 官方客户端（实盘必需）
安装：
pip install -r requirements.txt
<a name="4"></a>
4. API 密钥获取教程 / API Key Tutorial
4.1 Polymarket 凭证 / Polymarket Credentials
步骤 1：导出钱包（EOA 和 Proxy）
- 访问 Polymarket Settings
- 将metamask钱包登录到polymarket主页
- 你需要以下信息：
| 字段 | 说明 | 从哪里获取 |
|---|
PRIVATE_KEY | 你的 EOA 钱包私钥（绝密！） | MetaMask 导出私钥（注意：不是助记词） |
PROXY_WALLET | Polymarket 代理钱包地址 | Settings 页面显示的 "Wallet Address" |
POLY_API_KEY | L2 API Key | 待会儿运行命令获得 |
POLY_API_SECRET | L2 API Secret | 待会儿运行命令获得 |
POLY_API_PASSPHRASE | L2 密码 | 待会儿运行命令获得 |
步骤 2：生成私钥（MetaMask）
- 打开 MetaMask 扩展
- 选择账户 → 更多 → "Account details"
- 点击 "Export Private Key"
- 输入密码确认
- 复制以
0x 开头的 64 位十六进制字符串
⚠️ 安全警告：
- 私钥 = 完全控制权！任何人拿到私钥可以转移所有资产
- 不要将私钥上传到 GitHub、云盘
- 建议使用单独钱包专门用于交易，不要存放大额资金
步骤 3：确定 SIGNER_TYPE
- 如果
PRIVATE_KEY 属于普通 EOA 钱包→ SIGNER_TYPE = "2"
- 如果使用 Gnosis Safe 多签 →
SIGNER_TYPE = "2"（推荐）
大多数用户选择 "1"。
选择1的时候 可以不用运行命令获取L2凭证，直接用邮箱注册polymarket获得一个私钥钱包 去设置页面获取生成L2凭证并且导出私钥 然后复制代理钱包地址
Polymarket 官网看到的钱包地址（通常以 0x 开头），它持有你的 USDC.e 资金。
PRIVATE_KEY: 你的邮箱钱包私钥。你需要从官方导出页面获取。
步骤 4：确定 L2凭证
在代码所在目录下运行 python sniper.py --live --once
命令行会返回3个凭证 依次填入.env文件中
4.2 SkillPay
注意：
- 这是按次计费服务，每成功下单一次扣除 0.01 USDT
- 如果余额不足，下单会失败（系统会提示充值链接）
- 最低充值金额：8 USDT（相当于 800 次调用额度）
4.3 userId / 用户ID
SKILLPAY_USER_ID：同PROXY_WALLET的值
<a name="5"></a>
5. 配置文件详解 / Configuration
所有配置通过环境变量（.env 文件）管理。
5.1 创建 .env 文件
在项目根目录创建文件 .env，内容如下：
# ============================================
# 必填：Polymarket 认证
# ============================================
PRIVATE_KEY=0xsk_your_private_key_here_64_hex_chars
PROXY_WALLET=0x1234567890123456789012345678901234567890
POLY_API_KEY=pk_live_xxxxxxxxxxxxxxxxxxxx
POLY_API_SECRET=sk_live_xxxxxxxxxxxxxxxxxxxx
POLY_API_PASSPHRASE=your_passphrase_here
SIGNER_TYPE=1 # 1=邮箱账户, 2=metamask注册的polymarket账户
# ============================================
# 交易参数（建议保持默认）
# ============================================
TRADE_AMOUNT_USD=1.0 # 每笔下单金额（美元）
MIN_ORDERBOOK_SIZE=1.0 # 最小订单簿深度（流动性过滤）
SLIPPAGE_TOLERANCE=0.15 # 滑点容忍度（15%）
ENTRY_THRESHOLD=0.35 # 入场阈值（YES token 价格 < 0.35 才买入）
MAX_COST_PER_TRADE=1.2 # 单笔最大成本（超出则不买）
# ============================================
# 时间窗口（本地时间，UTC+8）
# ============================================
MONITOR_START_HOUR=9 # 监控开始时间（小时，小数形式）
MONITOR_END_HOUR=9.9167 # 监控结束时间（9:55 = 9 + 55/60 = 9.9167）
FALLBACK_START_HOUR=10 # Fallback 开始时间
FALLBACK_WINDOW_MINUTES=5 # Fallback 窗口长度（分钟）
# ============================================
# 执行频率（秒）
# ============================================
CHECK_INTERVAL=300 # 扫描间隔（300秒 = 5分钟）
REPORT_INTERVAL=240 # 报告间隔（240秒 = 4分钟）
# ============================================
# 缓存与重试
# ============================================
CACHE_TTL=3600 # 通用缓存时间（1小时）
GAMMA_CACHE_TTL=300 # Gamma API 缓存（5分钟）
CLOB_CACHE_TTL=30 # CLOB 订单簿缓存（30秒）
MAX_CONCURRENT_REQUESTS=50 # 最大并发请求数
REQUEST_DELAY=0.05 # 请求间延迟（秒）
MAX_RETRIES=3 # 最大重试次数（网络失败时）
RETRY_DELAY=1.0 # 重试延迟（秒）
# ============================================
# 文件路径
# ============================================
STATE_FILE=state.json # 状态文件（持仓、交易历史）
CACHE_DIR=cache # 缓存目录
5.2 参数详细说明 / Parameter Reference
5.2.1 认证参数 / Authentication
| 参数 | 类型 | 必填 | 说明 | 示例值 | 建议值 |
|---|
PRIVATE_KEY | string | ✅ | EOA 钱包私钥（ hexadecimal，带 0x 前缀） | 0xabc123... | 使用专用钱包，不要用主钱包 |
PROXY_WALLET | string | ✅ | Polynomial 代理钱包地址（从网站导出） | 0x1234... | 与 PRIVATE_KEY 对应的地址 |
POLY_API_KEY | string | ✅ | Polynomial L2 API Key（pk_ 或 sk_ 开头） | pk_live_xxx | 从 Settings → API Keys 创建 |
POLY_API_SECRET | string | ✅ | L2 API Secret | sk_live_xxx | 同上 |
POLY_API_PASSPHRASE | string | ✅ | 创建 API Key 时设置的密码 | myPass123 | 记住它，不会显示第二次 |
SIGNER_TYPE | int | ✅ | 签名器类型：1=邮箱, 2=Gnosis Safe | 0 | 普通钱包选 2 |
5.2.2 交易参数 / Trading
| 参数 | 类型 | 默认值 | 说明 | 建议值 | 风险提示 |
|---|
TRADE_AMOUNT_USD | float | 1.0 | 每笔订单目标金额（美元）。系统会自动计算 shares 数量 | 0.5 - 5.0 | 金额越大，潜在收益/损失都越高 |
MIN_ORDERBOOK_SIZE | float | 1.0 | 订单簿最小深度（需要至少有 $1.0 的流动性） | 1.0 | 太低可能滑点严重 |
SLIPPAGE_TOLERANCE | float | 0.15 (15%) | 滑点容忍度。如果 best_ask > 预期价格 × (1+滑点)，则取消订单 | 0.05 - 0.20 | 保守交易选 5%，激进选 20% |
ENTRY_THRESHOLD | float | 0.35 | 入场阈值。YES token 价格必须低于此值才买入 | 0.30 - 0.50 | 太低可能错过机会，太高可能买贵 |
MAX_COST_PER_TRADE | float | 1.2 | 单笔最大成本（USD）。实际成本 = price × shares，如果超过此值则不买 | 1.5 - 2.0 | 用于控制极端滑点损失 |
公式示例：
假设 TRADE_AMOUNT_USD = 1.0, best_ask = 0.5
目标 shares = 1.0 / 0.5 = 2.0 shares
实际 cost = 0.5 × 2.0 = $1.0 OK
假设 best_ask = 0.6, 但 max_price = 0.6 × 1.15 = 0.69
如果 0.6 < 0.69 → 仍可买入
如果 0.7 > 0.69 → 跳过（滑点过大）
5.2.3 时间窗口 / Time Windows
| 参数 | 类型 | 默认值 | 说明 | 计算方式 |
|---|
MONITOR_START_HOUR | float | 9 | 监控开始时间（小时） | 9 = 09:00 |
MONITOR_END_HOUR | float | 9.9167 | 监控结束时间 | 9 + 55/60 = 9.9167 = 09:55 |
FALLBACK_START_HOUR | float | 10 | Fallback 开始时间 | 10 = 10:00 |
FALLBACK_WINDOW_MINUTES | int | 5 | Fallback 窗口长度 | 10:00-10:04 |
时间逻辑：
- 09:00-09:55：正常扫描窗口（今日市场）
- 10:00-10:04：Fallback 强制买入窗口（为今日未持仓的城市强行下单）
- 09:55-10:00：空档期，不扫描
为什么这样设置：
- 气象局通常在早上 08:00-09:00 发布当日天气预报
- 9:00 后市场已消化信息，不确定性降低
- 10:00 是最后买入机会，离 14:00 最高温还有 4 小时
- Fallback 窗口很短，避免重复下单
5.2.4 执行频率 / Execution
| 参数 | 类型 | 默认值 | 说明 |
|---|
CHECK_INTERVAL | int | 300 | 扫描周期（秒），每 5 分钟检查一次市场 |
REPORT_INTERVAL | int | 240 | 状态报告周期（秒），每 4 分钟打印持仓/PnL |
建议：
- 测试阶段：
CHECK_INTERVAL=60（每分钟）以便快速看到效果
- 生产环境：
CHECK_INTERVAL=300（5分钟）避免 API 限流
5.2.5 缓存与重试 / Caching & Retry
| 参数 | 类型 | 默认值 | 说明 |
|---|
CACHE_TTL | int | 3600 | 通用缓存生存期（秒），1 小时 |
GAMMA_CACHE_TTL | int | 300 | Gamma Events API 缓存（5分钟） |
CLOB_CACHE_TTL | int | 30 | CLOB 订单簿缓存（30秒） |
MAX_CONCURRENT_REQUESTS | int | 50 | 最大并发请求数（异步） |
REQUEST_DELAY | float | 0.05 | 请求间最小延迟（秒），防限流 |
MAX_RETRIES | int | 3 | 网络失败最大重试次数 |
RETRY_DELAY | float | 1.0 | 重试延迟（秒），指数退避 |
5.2.6 文件路径 / Paths
| 参数 | 类型 | 默认值 | 说明 |
|---|
STATE_FILE | string | state.json | 状态文件，保存持仓、交易历史、统计 |
CACHE_DIR | string | cache | 缓存目录，存储 API 响应（自动创建） |
<a name="6"></a>
6. 代码参数详解（sniper.py 常量）
除了 .env 配置，代码中还有一些硬编码常量需要了解：
6.1 气象相关常量
# 城市列表（33个）
CITY_SLUGS = [
"taipei", "seoul", "shanghai", "shenzhen", "wuhan", "beijing", "chongqing",
"tokyo", "singapore", "hong-kong", "tel-aviv", "lucknow",
"london", "warsaw", "paris", "milan", "madrid", "munich", "ankara",
"atlanta", "nyc", "toronto", "miami", "chicago", "dallas", "seattle",
"wellington", "buenos-aires", "sao-paulo",
"denver", "houston", "austin", "san-francisco",
]
# 时区映射（自动将本地时间转为 UTC）
TIMEZONES = {
"nyc": "America/New_York",
"tokyo": "Asia/Tokyo",
"london": "Europe/London",
# ... 共 33 个时区定义
}
修改城市：如需增减城市，直接修改 CITY_SLUGS 列表。
6.2 API 端点（通常不需要改）
GAMMA_API_BASE = "https://gamma-api.polymarket.com"
CLOB_API_BASE = "https://clob.polymarket.com"
BILLING_URL = "https://skillpay.me/api/v1/billing"
<a name="7"></a>
7. 启动指南 / Launch Guide
7.1 命令行参数 / CLI Arguments
python sniper.py [OPTIONS]
选项：
--dry-run 扫描但不实际下单（默认模式）
--once 只运行一次扫描后退出（调试用）
--status 显示当前持仓和统计信息
--live 启用真实交易（需要已配置所有 API 凭证）
7.2 启动流程 / Launch Sequence
场景 1：首次测试（强烈建议）
# 1. 确保 .env 已配置
# 2. 运行模拟模式（不花钱、不下单）
python sniper.py --dry-run --once
# 预期输出：
# [AUTH] Loaded credentials...
# [SCAN] Starting scan...
# [SCAN] Tradeable in monitor window: X
# [BUY] Triggered: ... (如果触发条件满足)
# [DRY] Would buy 1 share @ $0.45 (max: $0.52)
# [OK] State saved, exiting.
验证点：
- ✅ 无报错
- ✅ 看到
[SCAN] 日志
- ✅ 如果市场条件满足，看到
[BUY] Triggered 和 [DRY] Would buy...
- ✅ 最后
[OK] State saved, exiting.
场景 2：查看当前状态
python sniper.py --status
输出示例：
Positions:
- tokyo_2026-03-26: entry_price=0.45, shares=2.22, PnL=$0.12
- london_2026-03-26: entry_price=0.52, shares=1.92, PnL=-$0.08
Stats:
Total trades: 5
Total PnL: $0.45
Billing cost: 0.05 USDT
场景 3：生产环境运行
在此之前不要忘了往polymarket网页端充值 只需点击充值按钮即可。
# 方式 A：前台运行（用于测试）
python sniper.py --live --once
# 方式 B：后台持续运行（推荐）
# Windows (使用 start)
start /B python sniper.py --live
# macOS/Linux (使用 screen/tmux)
screen -S weather_sniper
python sniper.py --live
# 按 Ctrl+A, D detached
监控日志：
# 实时查看
tail -f sniper.log # 如果配置了日志文件
# 或在代码中添加 FileHandler
<a name="8"></a>
8. 安全建议 / Security Best Practices
8.1 私钥管理 / Private Key Management
| 做法 | 推荐度 | 说明 |
|---|
| 使用硬件钱包（Ledger/Trezor）+ 代理 | ⭐⭐⭐⭐⭐ | 最安全，但配置复杂 |
| 使用单独 EOA 钱包，小额（< $100） | ⭐⭐⭐⭐ | 平衡安全与便利 |
| 主钱包直接投入 | ⭐⭐ | 风险高，不推荐 |
8.2 环境变量安全
# ✅ 正确：.env 文件加入 .gitignore
echo ".env" >> .gitignore
# ❌ 错误：不要硬编码在代码里
PRIVATE_KEY="0x..." # 不要这样！
# ✅ 正确：从环境变量读取
private_key = os.getenv('PRIVATE_KEY')
<a name="9"></a>
9. 故障排查 / Troubleshooting
9.1 常见错误 / Common Errors
错误 1：py-clob-client not available
原因：未安装依赖
解决：
pip install py-clob-client
错误 2：Invalid private key 或 Insufficient balance
原因：
- 私钥格式错误（缺
0x 前缀）
- 钱包余额不足（Polygnosis 需要支付 Gas）
解决：
- 检查
PRIVATE_KEY 是否为 64 位十六进制，带 0x 前缀
- 钱包转入至少 $5-10 等值的 USDC/ETH（Polygon 链）
- 确认网络为 Polygon Mainnet
错误 3：market not found (404)
原因：
token_id 对应的市场未开市- 城市/日期组合不存在
解决：
# 手动测试 API
curl "https://gamma-api.polymarket.com/markets?limit=10"
# 确认返回的数据中包含你感兴趣的城市和日期
错误 4：Billing failed (balance: 0.0000)
原因：SkillPay 余额耗尽
解决：
- 访问 SkillPay Dashboard 充值（最低 8 USDT）
- 或等下一轮扫描自动重试（已跳过耗尽余额的情况）
错误 5：rate limit 或 429
原因：API 调用过于频繁
解决：
- 增大
CHECK_INTERVAL（如改为 600 秒）
- 减小
MAX_CONCURRENT_REQUESTS
- 确保
REQUEST_DELAY >= 0.1
9.2 日志级别调整
如需更详细日志，在代码中添加：
import logging
logging.basicConfig(level=logging.DEBUG) # 或 INFO, WARNING
9.3 重置状态
删除 state.json 和 cache/ 目录，重启即可：
del state.json
rmdir /S /Q cache
python sniper.py --dry-run --once
<a name="10"></a>
10. FAQ 常见问题
Q1: 实盘和模拟模式有什么区别？
A：--dry-run 会调用 execute_buy_order 但：
- 不初始化真实
ClobClient
- 不发送 HTTP 请求到 Polymarket
- 不调用
billing_charge
仅打印"would buy"日志，用于验证逻辑是否正确。
Q3: 如果计费失败，订单会撤销吗？
A：不会。设计原则是"订单优先"：
- 订单上链成功后，即使计费失败，订单仍然有效
- 计费失败只记录 warning 并显示充值链接
- 这是正确的行为，因为链上订单无法撤销
Q4: 为什么我的 state.json 持仓信息不更新？
A：state.json 在每次成功下单后立即保存。如果没有更新：
- 检查文件权限（是否可写）
- 检查是否发生崩溃（查看错误日志）
- 手动重启后会自动加载
Q5: 可以同时运行多个实例吗？
A：不建议。多个实例会竞争 state.json 文件，导致数据损坏。
Q6: 如何调整交易的城市或时间？
A：编辑 CITY_SLUGS 列表（sniper.py:93-100），或修改 MONITOR_START_HOUR 等时间参数。
Q7: profit 如何计算？
A：系统未实现自动卖出，持仓会一直保留到结算：
- 如果 YES token 结算价为 $1.0 → 收益 = shares × ($1.0 - entry_price)
- 如果 NO token 结算价为 $1.0 → YES token 归零 → 损失 = - shares × entry_price
实际盈亏 = 持仓市值变化 + 已实现盈亏（如果手动平仓）
Q8: 有退订或取消订阅机制吗？
A：没有自动退订。持仓会保留在 state.json 中，直到手动删除或结算完成。
Q9: 如何设置 Telegram 通知？
A：不在当前功能范围内。建议使用外部脚本监控 sniper.log，匹配关键词（如 Billing failed、余额不足）后发送通知。
Q10: 代码中的 MIN_CHARGE_AMOUNT 有什么作用？
A：这是预检阈值。如果 billing_get_balance 返回值 < 0.01，扫描会提前退出，避免浪费 API 调用。这是保护机制，不是计费金额。
📞 支持 / Support
祝交易顺利！记住：风险管理第一，收益第二。 🎯
