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

```bash
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.

```bash
uv pip install ccxt pandas numpy
```

Or if using a venv:

```bash
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`):

```bash
#!/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:

```bash
chmod +x run_trader.sh
mkdir -p logs
```

## Step 5: Run a DRY_RUN test

```bash
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:**

```json
{
  "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:**

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

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:

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

```bash
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.