refactor: decouple Coin Hunter from Hermes for cross-platform usage
- Add unified coinhunter_shim.py that accepts subcommands (pre/gate/review/rotate-log) - Update SKILL.md gate pseudocode to read optional ~/.coinhunter/platform.json - Split cron/setup examples into Hermes and OpenClaw variants across docs - Introduce platform.json schema in user-data-layout.md - Remove stale auto_trader.py/run_trader.sh references from auto-trading-guide.md - Keep legacy shims as backward-compatible wrappers
This commit is contained in:
@@ -2,7 +2,7 @@
|
||||
|
||||
Complete guide for building and running a hands-off meme-coin trading bot using the Binance Spot API.
|
||||
|
||||
> Note: CoinHunter code now lives in `~/.hermes/skills/coinhunter/scripts/` and is preferably invoked via `coinhunter_cli.py`. Treat any references in this guide to runtime copies under `~/.coinhunter/` or shell wrappers like `run_trader.sh` as legacy structure notes unless explicitly updated below.
|
||||
> Note: The CoinHunter CLI is an external PyPI package (`pipx install coinhunter`). All execution goes through the `coinhunter` command. Treat any references in this guide to local source directories, `coinhunter_cli.py`, or shell wrappers like `run_trader.sh` as legacy structure notes unless explicitly updated below.
|
||||
|
||||
## Scope
|
||||
|
||||
@@ -23,13 +23,15 @@ This guide covers:
|
||||
|
||||
## Architecture
|
||||
|
||||
> **Note:** The current architecture uses the external `coinhunter` CLI (installed from PyPI) plus thin platform shims. The legacy local files (`auto_trader.py`, `run_trader.sh`) noted below are historical references only.
|
||||
|
||||
```
|
||||
~/.coinhunter/
|
||||
├── auto_trader.py # Main trading logic
|
||||
├── run_trader.sh # Shell wrapper (venv + env vars + logging)
|
||||
├── check_api.py # Quick API connectivity validator
|
||||
├── logs/trader.log # Execution logs
|
||||
└── positions.json # Portfolio state (shared with coinhunter)
|
||||
├── .env # API keys and secrets
|
||||
├── positions.json # Portfolio state (shared with coinhunter)
|
||||
├── state/ # Gate state and locks
|
||||
├── logs/ # Execution logs
|
||||
└── reviews/ # Hourly review reports
|
||||
```
|
||||
|
||||
## Step 1: Binance API Key setup
|
||||
@@ -44,15 +46,17 @@ This guide covers:
|
||||
- Use the public IP of the machine that will run the bot
|
||||
- This prevents key reuse if the credential is ever leaked
|
||||
|
||||
**Security reminder:** never paste API keys into chat messages. Write them directly into `~/.hermes/.env`.
|
||||
**Security reminder:** never paste API keys into chat messages. Write them into your platform's environment file (e.g. `~/.hermes/.env` or `~/.openclaw/.env`). You can also store them under `~/.coinhunter/.env` and source that file in your wrapper script.
|
||||
|
||||
## Step 2: Store credentials
|
||||
|
||||
Append to `~/.hermes/.env`:
|
||||
Append to your environment file (check `platform.json` -> `env_file` if you have one, otherwise use your platform default):
|
||||
|
||||
```env
|
||||
```bash
|
||||
cat >> ~/.coinhunter/.env << 'EOF'
|
||||
BINANCE_API_KEY=your_api_key_here
|
||||
BINANCE_API_SECRET=your_api_secret_here
|
||||
EOF
|
||||
```
|
||||
|
||||
## Step 3: Install dependencies
|
||||
@@ -72,46 +76,33 @@ pip install ccxt pandas numpy
|
||||
|
||||
## Step 4: Deploy the bot
|
||||
|
||||
Use `scripts/auto_trader.py` from the coinhunter skill as the template. Copy it into the user's `~/.coinhunter/` directory and customize:
|
||||
The trading logic is provided by the external `coinhunter` CLI. To run it automatically, deploy the platform shim and a small wrapper script.
|
||||
|
||||
- `MAX_POSITIONS` — max concurrent meme-coin positions (default 2)
|
||||
- `CAPITAL_ALLOCATION_PCT` — fraction of total USDT to use (default 0.95; leave ~5% buffer for fees/slippage)
|
||||
- `MIN_POSITION_USDT` — minimum single order size (default 50)
|
||||
- `STOP_LOSS_PCT` / `TAKE_PROFIT_1_PCT` / `TAKE_PROFIT_2_PCT` — risk levels
|
||||
If you need custom parameters (max positions, allocation percentage, stop-loss levels), configure them in `~/.coinhunter/config.json` and reference them from your wrapper script, or pass them as flags to `coinhunter exec`.
|
||||
|
||||
Create `run_trader.sh`:
|
||||
Example wrapper (`run_trader.sh`):
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -e
|
||||
cd "$(dirname "$0")"
|
||||
python3 check_api.py
|
||||
source ~/.coinhunter/.env
|
||||
source /path/to/venv/bin/activate
|
||||
export DRY_RUN=${DRY_RUN:-true}
|
||||
python3 auto_trader.py >> logs/trader.log 2>&1
|
||||
coinhunter exec >> logs/trader.log 2>&1
|
||||
```
|
||||
|
||||
Make executable:
|
||||
|
||||
```bash
|
||||
chmod +x run_trader.sh check_api.py
|
||||
chmod +x run_trader.sh
|
||||
mkdir -p logs
|
||||
```
|
||||
|
||||
## Step 5: Validate API connectivity
|
||||
## Step 5: Run a DRY_RUN test
|
||||
|
||||
```bash
|
||||
python3 check_api.py
|
||||
```
|
||||
|
||||
Expected output: `✅ API 配置正常`
|
||||
|
||||
If this fails, the bot will exit immediately on each run.
|
||||
|
||||
## Step 6: Run a DRY_RUN test
|
||||
|
||||
```bash
|
||||
DRY_RUN=true python3 auto_trader.py
|
||||
DRY_RUN=true coinhunter exec
|
||||
```
|
||||
|
||||
Expected behavior:
|
||||
@@ -123,9 +114,9 @@ Expected behavior:
|
||||
|
||||
Only proceed to live trading after at least one dry-run cycle completes without errors.
|
||||
|
||||
## Step 7: Schedule with cronjob
|
||||
## Step 6: Schedule with your platform's cron system
|
||||
|
||||
Use the `cronjob` tool to run the bot every 15 minutes:
|
||||
**Hermes example:**
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -137,7 +128,19 @@ Use the `cronjob` tool to run the bot every 15 minutes:
|
||||
}
|
||||
```
|
||||
|
||||
## Step 8: Switch to live trading
|
||||
**OpenClaw example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"name": "Coin Hunter Auto Trader",
|
||||
"schedule": "*/15 * * * *",
|
||||
"deliver": "webhook",
|
||||
"prompt": "Run the Coin Hunter automatic meme-coin trading bot.\n1. cd /home/<user>/.coinhunter\n2. ./run_trader.sh\n3. Summarize actions and report back."
|
||||
}
|
||||
```
|
||||
|
||||
## Step 7: Switch to live trading
|
||||
|
||||
Once DRY_RUN validation succeeds and the user confirms:
|
||||
|
||||
@@ -151,7 +154,7 @@ Once DRY_RUN validation succeeds and the user confirms:
|
||||
|
||||
1. **Never enable Withdrawal permission** on the API key.
|
||||
2. **Always bind an IP whitelist** if possible.
|
||||
3. **Never accept API keys in plaintext chat.** Ask the user to write them into `~/.hermes/.env`.
|
||||
3. **Never accept API keys in plaintext chat.** Ask the user to write them into their platform environment file (e.g. `~/.hermes/.env` or `~/.openclaw/.env`) or `~/.coinhunter/.env`.
|
||||
4. **Do not set allocation to exactly 100%.** Leave at least 3–5% buffer for fees and slippage.
|
||||
5. **Start with DRY_RUN.** Run at least one full cycle before going live.
|
||||
6. **Check the account balance first.** If USDT is 0 (or held in Earn/Margin/Futures), the bot cannot trade.
|
||||
@@ -172,10 +175,10 @@ ticker = tickers.get(sym_ccxt)
|
||||
|
||||
### .env file is protected
|
||||
|
||||
The `patch` tool may reject edits to `~/.hermes/.env`. Use terminal redirection instead:
|
||||
The `patch` tool may reject edits to environment files. Use terminal redirection instead:
|
||||
|
||||
```bash
|
||||
cat >> ~/.hermes/.env << 'EOF'
|
||||
cat >> ~/.coinhunter/.env << 'EOF'
|
||||
BINANCE_API_KEY=xxx
|
||||
BINANCE_API_SECRET=yyy
|
||||
EOF
|
||||
|
||||
@@ -1,16 +1,33 @@
|
||||
# CoinHunter shim templates
|
||||
|
||||
These files are tiny compatibility shims for Hermes platform features that currently expect scripts under `~/.hermes/scripts/`.
|
||||
These files are tiny compatibility shims for cron-based platforms (Hermes, OpenClaw, etc.) that expect scripts under a scripts directory such as `~/.hermes/scripts/` or `~/.openclaw/scripts/`.
|
||||
|
||||
When needed, copy them like this:
|
||||
## Unified shim (recommended)
|
||||
|
||||
`templates/coinhunter_shim.py` is the cross-platform wrapper. It takes the subcommand as its first argument and delegates to the installed `coinhunter` CLI:
|
||||
|
||||
```bash
|
||||
cp templates/coinhunter_shim.py ~/.hermes/scripts/coinhunter_shim.py
|
||||
# or
|
||||
cp templates/coinhunter_shim.py ~/.openclaw/scripts/coinhunter_shim.py
|
||||
```
|
||||
|
||||
Usage examples:
|
||||
- `coinhunter_shim.py pre`
|
||||
- `coinhunter_shim.py gate`
|
||||
- `coinhunter_shim.py review`
|
||||
- `coinhunter_shim.py rotate-log`
|
||||
|
||||
## Legacy shims (backward compatibility)
|
||||
|
||||
The original individual shims are still provided for existing Hermes users who already have them deployed. Their behavior is unchanged:
|
||||
|
||||
- `templates/coinhunter_precheck_shim.py` -> `~/.hermes/scripts/coinhunter_precheck.py`
|
||||
- `templates/coinhunter_external_gate_shim.py` -> `~/.hermes/scripts/coinhunter_external_gate.py`
|
||||
- `templates/coinhunter_review_context_shim.py` -> `~/.hermes/scripts/coinhunter_review_context.py`
|
||||
- `templates/rotate_external_gate_log_shim.sh` -> `~/.hermes/scripts/rotate_external_gate_log.sh`
|
||||
- `templates/rotate_external_gate_log_shim.py` -> `~/.hermes/scripts/rotate_external_gate_log.py`
|
||||
|
||||
The real business logic stays inside the skill under:
|
||||
- `~/.hermes/skills/coinhunter/scripts/`
|
||||
The real business logic lives in the external `coinhunter` CLI package (installed from PyPI). These shims only delegate to it.
|
||||
|
||||
The user runtime data stays under:
|
||||
- `~/.coinhunter/`
|
||||
|
||||
@@ -17,6 +17,7 @@ This keeps personal accounts, positions, and watchlists out of packaged skill ar
|
||||
```text
|
||||
~/.coinhunter/
|
||||
├── config.json
|
||||
├── platform.json
|
||||
├── accounts.json
|
||||
├── positions.json
|
||||
├── watchlist.json
|
||||
@@ -46,6 +47,28 @@ Example:
|
||||
}
|
||||
```
|
||||
|
||||
### platform.json
|
||||
Optional cross-platform runtime configuration. When absent, the framework defaults to Hermes behavior.
|
||||
|
||||
Suggested fields:
|
||||
- `platform` — runtime name (`"hermes"` or `"openclaw"`)
|
||||
- `scripts_dir` — where platform shims are deployed
|
||||
- `env_file` — path to the environment file for secrets
|
||||
- `cron_command` — command array used by the external gate to trigger a job
|
||||
- `delivery` — default delivery channel (`"telegram"`, `"webhook"`, etc.)
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"platform": "openclaw",
|
||||
"scripts_dir": "~/.openclaw/scripts",
|
||||
"env_file": "~/.openclaw/.env",
|
||||
"cron_command": ["openclaw", "trigger"],
|
||||
"delivery": "webhook"
|
||||
}
|
||||
```
|
||||
|
||||
### accounts.json
|
||||
Store exchange accounts and balances.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user