Trading Bot — Binance Futures Testnet (USDT-M)

A clean Python CLI application that places Market, Limit, and Stop-Market orders on the Binance Futures Testnet. Built with a layered architecture, structured logging, and proper error handling.

---

Project Structure

trading_bot/
├── bot/
│   ├── __init__.py
│   ├── client.py          # Binance API wrapper (signing, HTTP)
│   ├── orders.py          # Order placement logic
│   ├── validators.py      # Input validation
│   └── logging_config.py  # Rotating file + console logger
├── logs/
│   └── bot.log            # All requests, responses, errors
├── cli.py                 # CLI entry point (argparse)
├── .env.example           # Credential template
├── .gitignore
├── requirements.txt
└── README.md

---

Setup

1. Get Testnet API Credentials

1. Go to https://testnet.binancefuture.com
2. Register or log in
3. Navigate to API Management → click Generate
4. Copy your API Key and Secret Key

2. Clone & Install

git clone https://github.com/YOUR_USERNAME/trading-bot.git
cd trading-bot

# Create a virtual environment (recommended)
python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate

pip install -r requirements.txt

3. Configure Credentials

cp .env.example .env

Open .env and fill in your keys:

BINANCE_API_KEY=your_testnet_api_key_here
BINANCE_API_SECRET=your_testnet_api_secret_here

⚠️ Never commit your .env file. It is already in .gitignore.

---

How to Run

Place a Market Order

python cli.py --symbol BTCUSDT --side BUY --type MARKET --qty 0.01

Place a Limit Order

python cli.py --symbol BTCUSDT --side SELL --type LIMIT --qty 0.01 --price 87000

Place a Stop-Market Order (Bonus)

python cli.py --symbol ETHUSDT --side SELL --type STOP_MARKET --qty 0.1 --price 2000

See All Options

python cli.py --help

---

Example Output

─── Order Request Summary ───────────────────────
  Symbol    : BTCUSDT
  Side      : BUY
  Type      : MARKET
  Quantity  : 0.01
─────────────────────────────────────────────────

─── Order Response ───────────────────────────────
  Order ID     : 4799218156
  Status       : FILLED
  Executed Qty : 0.010
  Avg Price    : 84321.10
  Client Order : web_a1b2c3d4
─────────────────────────────────────────────────

✓ Order placed successfully!

---

Logging

All activity is logged to logs/bot.log:

• DEBUG — full request params and raw API response body
• INFO — order intent and outcome (orderId, status, executedQty)
• ERROR — API errors, network failures, validation failures

The console shows INFO and above. The log file captures everything (DEBUG+). Log files rotate at 5 MB and keep 3 backups.

---

Error Handling

Scenario	Behaviour
Missing --price on LIMIT order	Clear validation error, exits with code 1
Invalid symbol / negative quantity	Validation error before any API call
API key missing or wrong	Friendly message + logged error
Binance API error (e.g. insufficient margin)	Error code + message shown and logged
Network timeout / no internet	Friendly timeout message + logged

---

Assumptions

• All trades use the USDT-M Futures Testnet (testnet.binancefuture.com)
• Quantity precision is passed as-is — Binance will reject if it violates the symbol's lot size filter on the testnet
• timeInForce defaults to GTC (Good Till Cancelled) for LIMIT orders
• For STOP_MARKET orders, --price is used as the stopPrice
• Credentials are loaded from .env via python-dotenv

---

Requirements

• Python 3.8+
• requests — HTTP client
• python-dotenv — loads .env file

See requirements.txt for pinned versions.