Binance Futures Trading Bot

A clean, production-style Python trading bot for Binance Futures Testnet (USDT-M).
Places MARKET, LIMIT, and STOP_MARKET orders via the REST API with full logging, input validation, and structured error handling.

---

Project Structure

trading_bot/
├── bot/
│   ├── __init__.py
│   ├── client.py          # Binance REST API wrapper (HMAC-SHA256 signing)
│   ├── orders.py          # Order placement logic
│   ├── validators.py      # Input validation
│   └── logging_config.py  # Rotating file + console logging
├── logs/                  # Auto-created; contains trading_bot.log
├── cli.py                 # CLI entry point
├── requirements.txt
├── .env.example           # Copy → .env and fill in your keys
└── README.md

---

Setup

1. Get Testnet API Keys

1. Go to https://testnet.binancefuture.com
2. Sign in with GitHub
3. Click your avatar → API Key → copy the key and secret

2. Install dependencies

cd trading_bot
pip install -r requirements.txt

3. Configure credentials

cp .env.example .env
# Open .env and paste your API key and secret

Your .env file:

BINANCE_API_KEY=your_actual_key_here
BINANCE_API_SECRET=your_actual_secret_here

⚠️ Never commit .env to Git. It is already in .gitignore.

---

Usage

# From inside the trading_bot/ directory:
python cli.py --symbol BTCUSDT --side BUY --type MARKET --quantity 0.001

All flags

Flag	Required	Description
--symbol	✅	Trading pair, e.g. BTCUSDT
--side	✅	BUY or SELL
--type	✅	MARKET, LIMIT, or STOP_MARKET
--quantity	✅	Amount to trade, e.g. 0.001
--price	LIMIT only	Limit price in USDT
--stop-price	STOP_MARKET only	Stop trigger price in USDT
--dry-run	❌	Validate & preview payload without placing order
--log-file	❌	Override log path (default: logs/trading_bot.log)

---

Examples

# Market BUY 0.001 BTC
python cli.py --symbol BTCUSDT --side BUY --type MARKET --quantity 0.001

# Limit SELL 0.01 ETH at $3,000
python cli.py --symbol ETHUSDT --side SELL --type LIMIT --quantity 0.01 --price 3000

# Stop-Market BUY trigger $80,000 (bonus order type)
python cli.py --symbol BTCUSDT --side BUY --type STOP_MARKET --quantity 0.001 --stop-price 80000

# Dry-run (no API call, just validate & preview)
python cli.py --symbol BTCUSDT --side BUY --type MARKET --quantity 0.001 --dry-run

---

Logging

All API requests, responses, and errors are written to logs/trading_bot.log.

• File log: DEBUG level and above (full detail, rotating 5 MB × 3 backups)
• Console: WARNING and above only (quiet by default)

2025-01-15 10:23:45 | INFO     | trading_bot.cli    | CLI invoked | symbol=BTCUSDT ...
2025-01-15 10:23:45 | DEBUG    | trading_bot.client | → POST /fapi/v1/order | params={...}
2025-01-15 10:23:46 | INFO     | trading_bot.orders | Order placed successfully | orderId=123456 ...

---

Error Handling

Scenario	Behaviour
Invalid side/type/symbol	Caught before API call, clear message printed
Missing price for LIMIT	Validation error, no network request made
Binance API error (e.g. -1121 invalid symbol)	Pretty-printed code + message
Network timeout / connection refused	Graceful error, logged to file
Unexpected Python exception	Stack trace logged to file, user sees clean error

---

Assumptions

• Only USDT-M Futures are supported (symbol must end in USDT)
• All orders use the default testnet base URL: https://testnet.binancefuture.com
• For LIMIT orders, timeInForce defaults to GTC (Good-Till-Cancelled)
• Testnet does not charge fees; avgPrice / executedQty may show 0 for unfilled orders