binance-dca

What this skill does

# Binance DCA — Professional Dollar-Cost Averaging Tool

> **Systematic crypto accumulation made simple.**  
> Plan, execute, and track DCA strategies on Binance with confidence.

## What is DCA?

**Dollar-Cost Averaging (DCA)** is an investment strategy where you buy a fixed dollar amount of an asset at regular intervals, regardless of price. This approach:

- ✅ **Reduces timing risk** — no need to predict market tops/bottoms
- ✅ **Smooths volatility** — averages out price fluctuations over time
- ✅ **Removes emotion** — systematic buying, no panic or FOMO
- ✅ **Builds discipline** — consistent accumulation, perfect for long-term holders

**This tool** helps you plan, automate, and track your DCA strategy on Binance spot markets.

---

## Features

- 📊 **DCA Plan Projections** — scenario analysis showing potential outcomes at different price levels
- 💰 **Market & Limit Orders** — flexible execution options
- 📈 **Trade History** — track your accumulation progress
- 🔒 **Secure** — credentials via environment variables only, zero hardcoded secrets
- 🧪 **Testnet Support** — practice on Binance testnet before going live
- 🤖 **OpenClaw Integration** — automate DCA buys via cron jobs with alerts
- 🛡️ **Risk Management** — conservative defaults, validation before execution

---

## Setup

### 1. Get Binance API Keys

1. Log in to [binance.com](https://www.binance.com)
2. Go to **Account** → **API Management**
3. Create a new API key:
   - **Label:** `OpenClaw-DCA` (or similar)
   - **Restrictions:** Enable **Spot & Margin Trading** only
   - **IP Whitelist:** Add your server IP for security (optional but recommended)
4. Save your **API Key** and **Secret Key** securely

⚠️ **Security tips:**
- Never share your secret key
- Enable IP whitelist if your server has a static IP
- Use a separate API key for DCA (easier to revoke if needed)
- Start with small amounts to test

### 2. Set Environment Variables

**Never hardcode credentials.** Always use environment variables:

```bash
export BINANCE_API_KEY="your-api-key-here"
export BINANCE_SECRET_KEY="your-secret-key-here"
```

**Make them permanent** (optional, add to `~/.bashrc` or `~/.zshrc`):

```bash
echo 'export BINANCE_API_KEY="your-api-key-here"' >> ~/.bashrc
echo 'export BINANCE_SECRET_KEY="your-secret-key-here"' >> ~/.bashrc
source ~/.bashrc
```

**For testnet** (recommended for first-time users):

```bash
export BINANCE_BASE_URL="https://testnet.binance.vision"
```

Get testnet API keys at: [testnet.binance.vision](https://testnet.binance.vision/)

### 3. Verify Setup

```bash
# Check balance (should not error)
bash scripts/dca.sh balance USDT

# Check BTC price
bash scripts/dca.sh price BTCUSDT
```

If you see prices/balances, you're ready!

---

## Quick Start Examples

### Example 1: Check Current Price

```bash
bash scripts/dca.sh price BTCUSDT
# Output: BTCUSDT = 95234.50
```

Works for any pair:
```bash
bash scripts/dca.sh price ETHUSDT
bash scripts/dca.sh price SOLUSDT
```

### Example 2: Check Your Balance

```bash
bash scripts/dca.sh balance USDT
# Output: USDT: free=1000.00000000, locked=0.00000000
```

Check any asset:
```bash
bash scripts/dca.sh balance BTC
bash scripts/dca.sh balance ETH
```

### Example 3: Plan a DCA Strategy

**Scenario:** You want to invest $600 over 3 months in BTC.

```bash
# $50 every week for 12 weeks
bash scripts/dca.sh plan 50 7 12 BTCUSDT
```

**Output:**
```
DCA Plan: BTCUSDT
==========================
Buy amount:  $50 per buy
Frequency:   every 7 days
Duration:    12 buys
Current:     95234.50
==========================
Total invest:  $600.00
At cur. price: 0.00630245 BTC
Time span:     84 days (~2.8 months)

Scenario Analysis (if avg price over period is):
  -30% -> avg $ 66,664.15 -> 0.00900000 BTC -> PnL: -$186.00 (-31.0%)
  -20% -> avg $ 76,187.60 -> 0.00787500 BTC -> PnL: -$126.00 (-21.0%)
  -10% -> avg $ 85,711.05 -> 0.00700000 BTC -> PnL: -$63.00 (-10.5%)
   +0% -> avg $ 95,234.50 -> 0.00630245 BTC -> PnL: +$0.00 (+0.0%)
  +10% -> avg $104,757.95 -> 0.00572727 BTC -> PnL: +$63.00 (+10.5%)
  +20% -> avg $114,281.40 -> 0.00525000 BTC -> PnL: +$126.00 (+21.0%)
  +50% -> avg $142,851.75 -> 0.00420000 BTC -> PnL: +$378.00 (+63.0%)
 +100% -> avg $190,469.00 -> 0.00315122 BTC -> PnL: +$630.00 (+105.0%)
```

**What this tells you:**
- If BTC stays flat → break even
- If BTC averages -20% during your buys → you're down ~21% (but you own more BTC)
- If BTC averages +50% → you're up ~63%

Use this to **set realistic expectations** before committing.

### Example 4: Execute Your First DCA Buy

**Market order (instant execution):**

```bash
# Buy $50 worth of BTC at current market price
bash scripts/dca.sh buy BTCUSDT 50
```

**Output:**
```
Placing MARKET buy: BTCUSDT for 50 USDT...
Order #123456789: FILLED
Filled: 0.00052500 BTC
```

**Limit order (wait for your price):**

```bash
# Only buy if BTC drops to $94,000
bash scripts/dca.sh buy BTCUSDT 50 LIMIT 94000
```

**Output:**
```
Placing LIMIT buy: BTCUSDT for 50 USDT...
Order #123456790: NEW
Filled: 0.00000000 BTC
```

(Order will fill when price hits $94,000)

### Example 5: Check Your Trade History

```bash
# Last 10 trades for BTCUSDT
bash scripts/dca.sh history BTCUSDT 10
```

**Output:**
```
Last 10 trades for BTCUSDT:
---
1738752000 | BUY | qty=0.00052500 | price=95238.10 | fee=0.00000053 BNB
1738665600 | BUY | qty=0.00051234 | price=97567.20 | fee=0.00000051 BNB
...
```

---

## Complete Action Reference

### `price [SYMBOL]`

**Get current spot price for a trading pair.**

```bash
bash scripts/dca.sh price BTCUSDT
bash scripts/dca.sh price ETHUSDT
bash scripts/dca.sh price SOLUSDT
```

**Default:** `BTCUSDT` if symbol is omitted.

---

### `balance [ASSET]`

**Check free and locked balance for an asset.**

```bash
bash scripts/dca.sh balance USDT
bash scripts/dca.sh balance BTC
bash scripts/dca.sh balance ETH
```

**Output format:** `ASSET: free=X.XXXXXXXX, locked=Y.YYYYYYYY`

**Default:** `USDT` if asset is omitted.

**Use case:** Check how much capital you have available before placing orders.

---

### `buy SYMBOL AMOUNT [TYPE] [PRICE]`

**Place a buy order.**

**Arguments:**
- `SYMBOL` — Trading pair (e.g., `BTCUSDT`, `ETHUSDT`)
- `AMOUNT` — Amount in **quote currency** (USDT). The tool calculates how much BTC/ETH you get.
- `TYPE` — `MARKET` (default) or `LIMIT`
- `PRICE` — Required for `LIMIT` orders

**Market order examples:**

```bash
# Buy $50 worth of BTC instantly
bash scripts/dca.sh buy BTCUSDT 50

# Buy $100 worth of ETH instantly
bash scripts/dca.sh buy ETHUSDT 100
```

**Limit order examples:**

```bash
# Buy $50 BTC only if price drops to $90,000
bash scripts/dca.sh buy BTCUSDT 50 LIMIT 90000

# Buy $200 ETH only if price hits $3,200
bash scripts/dca.sh buy ETHUSDT 200 LIMIT 3200
```

**Safety features:**
- Amount validation (must be a number)
- API key check before execution
- Order status confirmation in output

---

### `history [SYMBOL] [LIMIT]`

**Show recent trade history.**

```bash
# Last 10 trades for BTCUSDT
bash scripts/dca.sh history BTCUSDT 10

# Last 20 trades for ETHUSDT
bash scripts/dca.sh history ETHUSDT 20

# Last 50 trades for SOLUSDT
bash scripts/dca.sh history SOLUSDT 50
```

**Defaults:** `BTCUSDT`, limit `10`

**Output includes:**
- Timestamp (Unix seconds)
- Side (BUY/SELL)
- Quantity purchased
- Execution price
- Fees paid (and fee asset)

**Use case:** Track your DCA progress over time, calculate average entry price.

---

### `plan [AMOUNT] [FREQ_DAYS] [NUM_BUYS] [SYMBOL]`

**Project a DCA plan with scenario analysis.**

**Arguments:**
- `AMOUNT` — Dollar amount per buy (default: `50`)
- `FREQ_DAYS` — Days between buys (default: `7`)
- `NUM_BUYS` — Number of buys (default: `12`)
- `SYMBOL` — Trading pair (default: `BTCUSDT`)

**Examples:**

```bash
# Default plan: $50 every 7 days, 12 buys
bash scripts/dca.sh plan

# Aggressive: $200 every 3 days, 30 buys
bash scripts/dca.sh plan 200 3 30 BTCUSDT

# Conservative: $25 every 14 days, 24 buys
bash scripts/