storyclaw-polymarket-trading

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Polymarket Trading - Self-Evolving Trading Bot

Polymarket交易——可自我进化的交易机器人

Design a trading strategy with the user, run automated paper trading (dry-run), auto-improve parameters when underperforming, and ask permission to switch to live trading when edge target met.

Supports any market type: politics, sports, crypto prices, science, entertainment, etc.

与用户协作设计交易策略，运行自动化模拟交易（dry-run），当表现不佳时自动优化参数，当达到收益目标时请求用户许可切换至实盘交易。

支持任意市场类型：政治、体育、加密货币价格、科学、娱乐等。

Critical Rules

核心规则

NEVER default to any specific market — always ask user what they want to trade
NEVER show made-up prices or signals — only real script output
DRY RUN always on by default — only switch to live after explicit user confirmation
Auto-improve silently — adjust params and notify user
NEVER create a strategy or set up crons without explicit user confirmation

绝不默认任何特定市场——始终询问用户想要交易的品类
绝不展示虚构的价格或信号——仅显示脚本的真实输出
默认始终开启模拟运行（DRY RUN）——仅在获得用户明确确认后切换至实盘
静默自动优化——调整参数并通知用户
未经用户明确确认，绝不创建策略或设置定时任务（crons）

Multi-User Support

多用户支持

Each user has their own

credentials/{USER_ID}.json

json

{
  "private_key": "0x...",
  "funder_address": "0x...",
  "dry_run": true
}

Set

USER_ID

TELEGRAM_USER_ID

env var when calling scripts.

Or set

POLYMARKET_PRIVATE_KEY

env var.

每个用户拥有独立的

credentials/{USER_ID}.json

文件：

json

{
  "private_key": "0x...",
  "funder_address": "0x...",
  "dry_run": true
}

调用脚本时设置

USER_ID

或

TELEGRAM_USER_ID

环境变量。

或设置

POLYMARKET_PRIVATE_KEY

环境变量。

First-Time User Flow

新用户使用流程

1. Check credentials

1. 检查凭证

bash

USER_ID=$TELEGRAM_USER_ID python3 {baseDir}/scripts/polymarket.py check

If not configured, run interactive setup:

bash

USER_ID=$TELEGRAM_USER_ID python3 {baseDir}/scripts/polymarket.py setup

bash

USER_ID=$TELEGRAM_USER_ID python3 {baseDir}/scripts/polymarket.py check

如果未配置，运行交互式设置：

bash

USER_ID=$TELEGRAM_USER_ID python3 {baseDir}/scripts/polymarket.py setup

2. Ask what they want to trade

2. 询问交易品类

Do NOT assume. Ask:

What market type? (politics, sports, crypto, tech, etc.)
Any specific keywords to focus on?

绝不自行假设。请询问：

想要交易的市场类型？（政治、体育、加密货币、科技等）
是否有需要重点关注的关键词？

3. Propose strategy — WAIT FOR CONFIRMATION

3. 提交策略方案——等待用户确认

Based on the conversation, derive and propose concrete values. Stop and wait for user to confirm before executing anything.

根据对话内容推导并提出具体策略参数。在执行任何操作前，必须等待用户确认。

4. Create strategy (only after confirmation)

4. 创建策略（仅在用户确认后执行）

bash

USER_ID=$TELEGRAM_USER_ID python3 {baseDir}/scripts/strategy_manager.py create --json '{
  "name": "<strategy name>",
  "market_filter": {
    "keywords": ["<keywords>"],
    "min_liquidity_usdc": 1000,
    "max_days_to_expiry": 30,
    "min_days_to_expiry": 1
  },
  "signal": {
    "method": "orderbook_imbalance",
    "params": { "threshold": 0.15, "max_entry_price": 0.60 }
  },
  "sizing": { "max_size_usdc": 5 },
  "targets": { "min_sample_size": 30, "min_edge": 0.05 }
}'

bash

USER_ID=$TELEGRAM_USER_ID python3 {baseDir}/scripts/strategy_manager.py create --json '{
  "name": "<策略名称>",
  "market_filter": {
    "keywords": ["<关键词>"],
    "min_liquidity_usdc": 1000,
    "max_days_to_expiry": 30,
    "min_days_to_expiry": 1
  },
  "signal": {
    "method": "orderbook_imbalance",
    "params": { "threshold": 0.15, "max_entry_price": 0.60 }
  },
  "sizing": { "max_size_usdc": 5 },
  "targets": { "min_sample_size": 30, "min_edge": 0.05 }
}'

5. Set up crons

5. 设置定时任务

bash

SKILL_PATH={baseDir}
STRATEGY_ID=<id from step 4>

bash

SKILL_PATH={baseDir}
STRATEGY_ID=<步骤4返回的策略ID>

Signal scan: every 15 minutes

信号扫描：每15分钟执行一次

(crontab -l 2>/dev/null; echo "*/15 * * * * USER_ID=$TELEGRAM_USER_ID python3 $SKILL_PATH/scripts/signal_cron.py $STRATEGY_ID >> $SKILL_PATH/state/$TELEGRAM_USER_ID.$STRATEGY_ID.log 2>&1") | crontab -

Performance review: daily at 09:00 UTC

绩效复盘：UTC时间每日09:00执行

(crontab -l 2>/dev/null; echo "0 9 * * * USER_ID=$TELEGRAM_USER_ID python3 $SKILL_PATH/scripts/review_cron.py $STRATEGY_ID >> $SKILL_PATH/state/$TELEGRAM_USER_ID.review.log 2>&1") | crontab -

undefined

(crontab -l 2>/dev/null; echo "0 9 * * * USER_ID=$TELEGRAM_USER_ID python3 $SKILL_PATH/scripts/review_cron.py $STRATEGY_ID >> $SKILL_PATH/state/$TELEGRAM_USER_ID.review.log 2>&1") | crontab -

undefined

Strategy Lifecycle

策略生命周期

dry_run → improving → pending_live → live

Go-live condition:

edge = win_rate - avg_entry_price >= min_edge

AND

total_pnl > 0

dry_run → improving → pending_live → live

实盘切换条件：

edge = 胜率 - 平均入场价格 >= 最低收益阈值

且

总盈利（total_pnl）> 0

Strategy Management

策略管理

bash

USER_ID=$TELEGRAM_USER_ID python3 {baseDir}/scripts/strategy_manager.py status
USER_ID=$TELEGRAM_USER_ID python3 {baseDir}/scripts/strategy_manager.py review <strategy_id>
USER_ID=$TELEGRAM_USER_ID python3 {baseDir}/scripts/strategy_manager.py activate-live <strategy_id>

bash

USER_ID=$TELEGRAM_USER_ID python3 {baseDir}/scripts/strategy_manager.py status
USER_ID=$TELEGRAM_USER_ID python3 {baseDir}/scripts/strategy_manager.py review <strategy_id>
USER_ID=$TELEGRAM_USER_ID python3 {baseDir}/scripts/strategy_manager.py activate-live <strategy_id>

Auto-Improvement Rules

自动优化规则

Condition	Action
edge < min_edge - 10%	Raise threshold (fewer but stronger signals)
edge < min_edge - 3%	Lower max_entry_price (cheaper entries)
3+ adjustments still failing	Notify user to reconsider
edge >= min_edge AND pnl > 0	Mark pending_live, notify user

条件	动作
edge < 最低收益阈值 - 10%	提高信号阈值（减少信号数量但提升信号质量）
edge < 最低收益阈值 - 3%	降低最高入场价格（以更低成本入场）
调整3次以上仍未达标	通知用户重新考虑策略
edge >= 最低收益阈值且盈利>0	标记为待实盘（pending_live）并通知用户

Signal Methods

信号生成方法

Method	Best for
orderbook_imbalance	Any liquid market with active orderbook

New methods can be added to

scripts/signals.py

方法	适用场景
orderbook_imbalance	任何拥有活跃订单簿的流动性市场

可在

scripts/signals.py

中添加新的信号生成方法。

Troubleshooting

故障排查

Error	Solution
py-clob-client not installed	`pip3 install py-clob-client`
USER_ID not set	Add `USER_ID=xxx` prefix
No config found	Run `python3 {baseDir}/scripts/polymarket.py setup`
API Error 401	Re-run setup to re-derive keys
No markets found	Broaden keywords or lower min_liquidity_usdc

错误信息	解决方法
py-clob-client未安装	执行 `pip3 install py-clob-client`
USER_ID未设置	添加 `USER_ID=xxx` 前缀
未找到配置文件	运行 `python3 {baseDir}/scripts/polymarket.py setup`
API错误401	重新运行设置脚本以重新生成密钥
未找到匹配市场	放宽关键词范围或降低最低流动性阈值（min_liquidity_usdc）

File Structure

文件结构

polymarket-trading/
├── SKILL.md
├── scripts/
│   ├── strategy_manager.py   # Lifecycle: create/review/status/activate-live
│   ├── signal_cron.py        # Cron: scan markets, run signals, record trades
│   ├── review_cron.py        # Cron: daily review + auto-improve
│   ├── signals.py            # Pluggable signal methods
│   ├── market_scanner.py     # Gamma API market discovery
│   └── polymarket.py         # CLOB API primitives
├── credentials/
│   └── {USER_ID}.json
├── strategies/
│   └── {USER_ID}/{strategy_id}.json
└── state/
    └── {USER_ID}.{strategy_id}.perf.json

polymarket-trading/
├── SKILL.md
├── scripts/
│   ├── strategy_manager.py   # 生命周期管理：创建/复盘/状态查询/激活实盘
│   ├── signal_cron.py        # 定时任务：扫描市场、生成信号、记录交易
│   ├── review_cron.py        # 定时任务：每日复盘 + 自动优化
│   ├── signals.py            # 可插拔信号生成方法
│   ├── market_scanner.py     # 通过Gamma API发现市场
│   └── polymarket.py         # CLOB API基础功能实现
├── credentials/
│   └── {USER_ID}.json
├── strategies/
│   └── {USER_ID}/{strategy_id}.json
└── state/
    └── {USER_ID}.{strategy_id}.perf.json
```",