Binance Futures Testnet Trading Bot

Small Python CLI that places MARKET and LIMIT orders on Binance USDT-M Futures Testnet, with structured layers, file logging, and input validation.

Features

• MARKET and LIMIT orders (BUY / SELL)
• Bonus: STOP_LIMIT orders (--type STOP_LIMIT + --stop-price)
• Typer CLI with clear request/response output
• Interactive menu: python cli.py menu
• Layered design: client.py (API), orders.py (business logic), validators.py, cli.py
• Logs API requests, responses, and errors to logs/trading_bot.log

Prerequisites

1. Register at Binance Futures Testnet and create API key + secret.
2. Python 3.10+ recommended.
3. Fund testnet wallet if required for your symbol.

Setup

cd trading_bot
python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS/Linux
# source .venv/bin/activate

pip install -r requirements.txt
copy .env.example .env   # Windows
# cp .env.example .env   # macOS/Linux

Edit .env:

BINANCE_API_KEY=your_testnet_key
BINANCE_API_SECRET=your_testnet_secret
BINANCE_FUTURES_BASE_URL=https://testnet.binancefuture.com

How to run

From the trading_bot directory:

MARKET buy

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

LIMIT sell

python cli.py place --symbol BTCUSDT --side SELL --type LIMIT --quantity 0.001 --price 95000

Use a limit price away from the market if you only want the order accepted (status NEW) without immediate fill.

STOP_LIMIT (bonus)

python cli.py place --symbol BTCUSDT --side SELL --type STOP_LIMIT --quantity 0.001 --price 94000 --stop-price 94500

Interactive menu

python cli.py menu

Help

python cli.py --help
python cli.py place --help

Example output

The CLI prints:

1. Order request summary (symbol, side, type, quantity, price)
2. Order response details (orderId, status, executedQty, avgPrice, …)
3. Success or Failure panel

All API traffic is also written to logs/trading_bot.log.

Project layout

trading_bot/
  bot/
    config.py          # Env vars, constants
    models.py          # OrderRequest, OrderResult dataclasses
    validators.py      # Input validation
    client.py          # Signed REST client (httpx)
    orders.py          # OrderService (business logic)
    display.py         # CLI formatting
    logging_config.py
    exceptions.py
  cli.py               # Typer entry point (thin layer)
  tests/               # Unit tests
  logs/                # Runtime + sample logs
  requirements.txt
  pyproject.toml
  .env.example
  README.md

Assumptions

• One-way position mode (default positionSide=BOTH; not sent explicitly).
• USDT-M pairs only; symbols must end with USDT.
• LIMIT orders use timeInForce=GTC.
• newOrderRespType=RESULT so MARKET fills return executedQty / avgPrice when available.
• Minimum quantity/step size is not pre-checked locally; Binance may reject invalid precision (error surfaced as API error).
• Testnet base URL is https://testnet.binancefuture.com as specified in the task brief.

Error handling

Situation	Exit code	User message
Invalid CLI input	1	Validation failure
Missing API keys (.env)	2	Configuration error
Network / timeout	3	Network error
Binance API error	4	API error
Other bot errors	5	Generic failure

Deliverable logs

Sample logs from successful testnet runs are included:

• logs/market_order_example.log — MARKET BUY on BTCUSDT
• logs/limit_order_example.log — LIMIT SELL on BTCUSDT

After you run live orders, your own entries append to logs/trading_bot.log.

License

MIT — for evaluation submission only.