Binance Futures Trading Bot

A Python CLI for trading on Binance Futures Testnet. Supports Market, Limit, and Stop-Market orders with request signing, input validation, and file logging.

Setup

Prerequisites

• Python 3.9+
• Binance Futures Testnet account (free, no KYC)

Getting Testnet Credentials

1. Go to https://testnet.binancefuture.com
2. Sign up with GitHub (no KYC required)
3. Click API Key in top navigation
4. Click Generate and copy your API Key + Secret immediately

Installation

pip install -r requirements.txt

Configuration

1. Copy .env.example to .env:

   cp .env.example .env

2. Edit .env and add your credentials:

   BINANCE_API_KEY=your_api_key_here
   BINANCE_API_SECRET=your_api_secret_here
   

⚠️ Important: .env is in .gitignore — never commit it with real credentials

Usage

Test connectivity:

python cli.py --ping

Check account balance:

python cli.py --account

Place a market order:

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

Place a limit order:

python cli.py --symbol ETHUSDT --side SELL --type LIMIT --quantity 0.01 --price 3000

Place a stop-market order:

python cli.py --symbol BTCUSDT --side BUY --type STOP_MARKET --quantity 0.001 --stop-price 70000

Project Structure

bot/
├── client.py          # Binance API client (HTTP, signing, error handling)
├── orders.py          # Order builders and response formatting
├── validators.py      # Input validation
└── logging_config.py  # File and console logging

cli.py                 # CLI entry point
logs/                  # Log files (auto-created)
  Side       : BUY
  Type       : MARKET
  Quantity   : 0.001
──────────────────────────────────────────────────
──────────────────────────────────────────────────
  ORDER RESPONSE
──────────────────────────────────────────────────
  Order ID       : 8389765432
  Client Order ID: x-abc123
  Status         : FILLED
  Executed Qty   : 0.001
  Avg Price      : 67432.10
  Cum Quote      : 67.43210
  Update Time    : 1717200001234
──────────────────────────────────────────────────

  ✓ Order placed successfully  (status: FILLED)

Place a Limit SELL Order

python cli.py --symbol ETHUSDT --side SELL --type LIMIT --quantity 0.05 --price 3200

Place a Limit BUY with IOC time-in-force

python cli.py --symbol BTCUSDT --side BUY --type LIMIT --quantity 0.002 --price 60000 --tif IOC

Place a Stop-Market BUY Order (Bonus)

Triggers a market BUY when BTC price hits 70,000:

python cli.py --symbol BTCUSDT --side BUY --type STOP_MARKET --quantity 0.001 --stop-price 70000

---

CLI Reference

Flag	Required	Description
--symbol	For orders	Trading pair, e.g. BTCUSDT
--side	For orders	BUY or SELL
--type	For orders	MARKET, LIMIT, or STOP_MARKET
--quantity	For orders	Order size (e.g. 0.001)
--price	LIMIT only	Limit price
--stop-price	STOP_MARKET only	Trigger price
--tif	LIMIT only	GTC (default), IOC, FOK
--ping	—	Test connectivity
--account	—	Show account balances
--api-key	If not set in env	Testnet API key
--api-secret	If not set in env	Testnet API secret
--log-dir	—	Log directory (default: logs/)
--log-level	—	DEBUG (default), INFO, WARNING, ERROR

---

Logging

Log files are written to logs/trading_bot_YYYYMMDD.log automatically.

• File handler captures DEBUG and above — includes raw request params and response bodies
• Console handler shows INFO and above — clean summary only
• API signatures are redacted from logs for security

Sample log entry:

2026-06-01 10:10:28 | INFO     | trading_bot.orders | Placing order: symbol=BTCUSDT side=BUY type=MARKET qty=0.001 price=N/A
2026-06-01 10:10:28 | DEBUG    | trading_bot.client | → POST /fapi/v1/order  params={...}
2026-06-01 10:10:28 | DEBUG    | trading_bot.client | ← HTTP 200  body={...}
2026-06-01 10:10:28 | INFO     | trading_bot.orders | Order response: {...}

---

Error Handling

The bot handles three categories of failures gracefully:

Error Type	Example	Handling
Validation errors	Invalid side, missing price	Printed + logged, exit code 1
Binance API errors	Invalid symbol, insufficient margin	BinanceAPIError raised, details printed
Network failures	Timeout, DNS failure	requests.RequestException caught and logged

---

Assumptions

• Testnet only: The base URL is hardcoded to https://testnet.binancefuture.com. Do not use real API keys.
• USDT-M Futures: All orders target the USDT-M futures market (perpetual contracts).
• Quantity precision: The bot passes quantities as-is. If the exchange rejects due to precision/filter errors (e.g. LOT_SIZE), adjust your quantity to match the symbol's step size shown in GET /fapi/v1/exchangeInfo.
• No dependency on python-binance: Uses only requests for full transparency and testnet compatibility.
• Python ≥ 3.9 is assumed for dict merge operators and type annotations.

---

Running Tests

The modules include inline validation that can be run directly:

# Run all validators
python -c "from bot.validators import *; print('Validators OK')"

# Check client signing logic
python -c "from bot.client import BinanceClient; c = BinanceClient('k', 's'); print('Client OK')"

---

Deliverables Checklist

• Market orders (BUY + SELL)
• Limit orders (BUY + SELL) with timeInForce
• Stop-Market orders (bonus order type)
• Full input validation with clear error messages
• Structured code: client.py / orders.py / validators.py / logging_config.py
• Logging to file (DEBUG) and console (INFO)
• Exception handling: validation, API, network
• requirements.txt
• Log files from MARKET and LIMIT orders in logs/