coinhunter/references/auto-trading-guide.md

Automated Trading Guide for Coin Hunter

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.

Scope

This guide covers:

• Creating a safe Binance API key
• Installing dependencies (ccxt, pandas, numpy)
• Setting up auto_trader.py
• Testing in DRY_RUN mode
• Scheduling execution with cronjob
• Critical safety rules and troubleshooting

What the bot does

1. Monitors existing positions for stop-loss (-7%) and take-profit (+15% / +30%) levels
2. Scans the market for new meme-coin candidates (price < $1, 24h volume > $1M, 24h change > 5%)
3. Dynamically sizes orders based on the user's total USDT balance and a configurable allocation percentage
4. Runs on a schedule (default every 15 minutes) and reports actions back via Telegram

Architecture

~/.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)

Step 1: Binance API Key setup

1. Log in to Binance → API Management
2. Create a new API Key
3. Enable permissions:
   • ✅ Enable Reading
   • ✅ Enable Spot & Margin Trading
   • ❌ Disable Withdrawal (security red line)
4. Add an IP whitelist (strongly recommended):
   • 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.

Step 2: Store credentials

Append to ~/.hermes/.env:

BINANCE_API_KEY=your_api_key_here
BINANCE_API_SECRET=your_api_secret_here

Step 3: Install dependencies

The bot uses ccxt for exchange connectivity and pandas/numpy for data handling.

uv pip install ccxt pandas numpy

Or if using a venv:

source venv/bin/activate
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:

• 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

Create run_trader.sh:

#!/bin/bash
set -e
cd "$(dirname "$0")"
python3 check_api.py
source /path/to/venv/bin/activate
export DRY_RUN=${DRY_RUN:-true}
python3 auto_trader.py >> logs/trader.log 2>&1

Make executable:

chmod +x run_trader.sh check_api.py
mkdir -p logs

Step 5: Validate API connectivity

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

DRY_RUN=true python3 auto_trader.py

Expected behavior:

• Reads current positions from positions.json
• Fetches live Binance prices
• Prints PnL for each position
• Prints [DRY RUN] instead of real trades
• Does not move money

Only proceed to live trading after at least one dry-run cycle completes without errors.

Step 7: Schedule with cronjob

Use the cronjob tool to run the bot every 15 minutes:

{
  "action": "create",
  "name": "Coin Hunter Auto Trader",
  "schedule": "*/15 * * * *",
  "deliver": "telegram",
  "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 8: Switch to live trading

Once DRY_RUN validation succeeds and the user confirms:

1. Edit run_trader.sh
2. Change DRY_RUN=${DRY_RUN:-true} to DRY_RUN=${DRY_RUN:-false}
3. The next cron run will execute real orders

You must always obtain explicit user confirmation before enabling live trading.

Key safety rules

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.
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.
7. Educate the user about risks. Automated bots can and will lose money during flash crashes, API errors, or black-swan events.

Common pitfalls

Ticker symbol mismatch

ccxt returns tickers with a slash (e.g., PENGU/USDT), but positions.json may store symbols without a slash (PENGUUSDT). If the bot looks up tickers.get("PENGUUSDT"), it will get None and silently skip stop-loss/take-profit checks.

Fix: normalize symbols before lookup:

sym_ccxt = sym.replace("USDT", "/USDT") if "/" not in sym else sym
ticker = tickers.get(sym_ccxt)

.env file is protected

The patch tool may reject edits to ~/.hermes/.env. Use terminal redirection instead:

cat >> ~/.hermes/.env << 'EOF'
BINANCE_API_KEY=xxx
BINANCE_API_SECRET=yyy
EOF

Zero balance surprises

The bot reads Spot free balance. If the user holds USDT in:

• Flexible Savings / Earn
• Margin account
• Futures wallet
• Another sub-account

…it will see $0 and fail to open new positions. Ask the user to transfer funds to Spot before going live.

Customization ideas

• Chain bias: restrict candidate scanning to Solana-only or Base-only by filtering cand["base"] or integrating DexScreener chain filters.
• Social signal integration: add a Twitter/X sentiment check before opening a position.
• Tiered stops: replace fixed -7% with trailing stops using recent ATR or swing lows.
• Blacklist expansion: add recently rugged tickers to BLACKLIST based on on-chain data.