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: 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

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

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/
├── .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

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 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 your environment file (check platform.json -> env_file if you have one, otherwise use your platform default):

cat >> ~/.coinhunter/.env << 'EOF'
BINANCE_API_KEY=your_api_key_here
BINANCE_API_SECRET=your_api_secret_here
EOF

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

The trading logic is provided by the external coinhunter CLI. To run it automatically, deploy the platform shim and a small wrapper script.

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.

Example wrapper (run_trader.sh):

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

Make executable:

chmod +x run_trader.sh
mkdir -p logs

Step 5: Run a DRY_RUN test

DRY_RUN=true coinhunter exec

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 6: Schedule with your platform's cron system

Hermes example:

{
  "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."
}

OpenClaw example:

{
  "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:

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 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.
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 environment files. Use terminal redirection instead:

cat >> ~/.coinhunter/.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.