binance-dca

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

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

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

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

Get testnet API keys at: testnet.binance.vision

3. Verify Setup

# 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 scripts/dca.sh price BTCUSDT
# Output: BTCUSDT = 95234.50

Works for any pair:

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

Example 2: Check Your Balance

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

Check any asset:

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.

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

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

# 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

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

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

# 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.

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

# 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