Skip to content

README.md

Latest commit

 

History

History
189 lines (139 loc) · 5.11 KB

README.md

File metadata and controls

189 lines (139 loc) · 5.11 KB

🤖 Binance Futures Testnet Trading Bot

A clean, production-grade Python CLI application for placing orders on the Binance Futures Testnet (USDT-M). Built with structured architecture, rich terminal output, and full logging.

✨ Features

  • ✅ Market Orders — execute instantly at current market price
  • ✅ Limit Orders — set your own price to buy or sell
  • ✅ Stop-Limit Orders — trigger an order when price hits a threshold (bonus)
  • ✅ BUY & SELL support on any futures pair
  • ✅ Input validation with clear error messages
  • ✅ Structured logging — all requests, responses and errors saved to logs/trading_bot.log
  • ✅ API key security — keys are always redacted in logs
  • ✅ Rich terminal output — formatted tables for every order

🗂️ Project Structure

trading_bot/
├── bot/
│   ├── __init__.py          # version info
│   ├── client.py            # Binance API client (auth, signing, requests)
│   ├── orders.py            # order placement logic
│   ├── validators.py        # input validation
│   └── logging_config.py   # logging setup (file + console)
├── logs/                    # log files written here (auto-created)
├── cli.py                   # CLI entry point (Typer)
├── .env.example             # credentials template
├── .gitignore
├── requirements.txt
└── README.md

⚙️ Setup

1. Clone the repository

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

2. Create a virtual environment

python -m venv venv

# Windows
venv\Scripts\activate

# Mac / Linux
source venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

4. Get Testnet API credentials

  1. Go to https://testnet.binancefuture.com
  2. Click "Login with GitHub"
  3. On the dashboard, click "API Key" → "Generate"
  4. Copy both keys — the secret is shown only once

5. Configure credentials

# Windows
copy .env.example .env

# Mac / Linux
cp .env.example .env

Open .env and fill in your keys:

BINANCE_API_KEY=your_testnet_api_key_here
BINANCE_SECRET_KEY=your_testnet_secret_key_here

🚀 How to Run

Market Order

python cli.py market BTCUSDT BUY 0.001
python cli.py market ETHUSDT SELL 0.01

Limit Order

python cli.py limit BTCUSDT BUY 0.001 --price 50000
python cli.py limit BTCUSDT SELL 0.001 --price 75000 --tif IOC

Stop-Limit Order (bonus)

python cli.py stop-limit BTCUSDT BUY 0.001 --stop-price 65000 --price 64900
python cli.py stop-limit BTCUSDT SELL 0.001 --stop-price 60000 --price 60100

Help

python cli.py --help
python cli.py market --help
python cli.py limit --help
python cli.py stop-limit --help

📋 Example Output

╭──────── Order Request ─────────╮
│ Symbol    │ BTCUSDT             │
│ Side      │ BUY                 │
│ Type      │ MARKET              │
│ Quantity  │ 0.001               │
╰────────────────────────────────╯

Placing order...

╭──────── Order Response ────────╮
│ Order ID     │ 3842910          │
│ Symbol       │ BTCUSDT          │
│ Side         │ BUY              │
│ Type         │ MARKET           │
│ Status       │ FILLED           │
│ Orig Qty     │ 0.001            │
│ Executed Qty │ 0.001            │
│ Avg Price    │ 64823.50         │
╰────────────────────────────────╯

✅  Order placed successfully!

📄 Log File

All API activity is logged to logs/trading_bot.log:

2024-01-15 10:23:01 | DEBUG | REQUEST  | method=POST endpoint=/fapi/v1/order params={symbol: BTCUSDT, ...}
2024-01-15 10:23:01 | DEBUG | RESPONSE | status=200 body={orderId: 3842910, status: FILLED, ...}
2024-01-15 10:23:01 | INFO  | MARKET_ORDER_RESULT | {orderId: 3842910, executedQty: 0.001, avgPrice: 64823.50}

API keys are always redacted in logs: X-MBX-APIKEY: ***REDACTED***

🛠️ Tech Stack

Library Purpose
httpx HTTP client for REST API calls
typer CLI framework
rich Terminal tables and colored output
python-dotenv Load credentials from .env file

📝 Assumptions

  • All orders are placed on Binance Futures Testnet (USDT-M) — not the live exchange
  • Base URL: https://testnet.binancefuture.com
  • Credentials are loaded from a .env file in the project root
  • Stop-Limit orders use Binance's STOP type with both price and stopPrice parameters
  • timeInForce defaults to GTC (Good Till Cancelled) for Limit and Stop-Limit orders
  • Log files rotate at 5 MB, keeping the last 3 backups

⚠️ Important

This bot connects to the Testnet only — no real funds are involved. Never use testnet API keys on the real Binance exchange or vice versa.