Binance Futures Testnet Trading Bot

A command-line trading bot for placing orders on Binance USDT-M Futures Testnet.

Overview

This project provides a Python-based trading bot that interfaces with the Binance Futures Testnet API. It supports placing market, limit, and stop-limit orders through a command-line interface with comprehensive logging.

Why Futures Testnet

The bot uses Binance Futures Testnet (https://testnet.binancefuture.com) for the following reasons:

• Provides a risk-free environment for testing trading strategies
• Uses simulated funds with no real financial exposure
• Mirrors the production Futures API behavior
• Allows validation of order placement logic before live deployment

To use the testnet, register at Binance Futures Testnet and generate API credentials.

Supported Order Types

Market Order

Executes immediately at the current market price.

Parameter	Required	Description
symbol	Yes	Trading pair (e.g., BTCUSDT)
side	Yes	BUY or SELL
quantity	Yes	Order quantity

Limit Order

Places an order at a specified price. Uses Good-Till-Canceled (GTC) time-in-force.

Parameter	Required	Description
symbol	Yes	Trading pair
side	Yes	BUY or SELL
quantity	Yes	Order quantity
price	Yes	Limit price

Stop-Limit Order

Triggers a limit order when the stop price is reached.

Parameter	Required	Description
symbol	Yes	Trading pair
side	Yes	BUY or SELL
quantity	Yes	Order quantity
price	Yes	Limit price after trigger
stop_price	Yes	Trigger price

Installation

cd trading_bot
pip install -r requirements.txt

Configuration

Create a .env file in the trading_bot directory:

BINANCE_API_KEY=your_testnet_api_key
BINANCE_API_SECRET=your_testnet_api_secret

CLI Usage

Run orders using cli.py with the following arguments:

Argument	Required	Description
--symbol	Yes	Trading pair symbol
--side	Yes	BUY or SELL
--order-type	Yes	MARKET, LIMIT, or STOP_LIMIT
--quantity	Yes	Order quantity
--price	Conditional	Required for LIMIT and STOP_LIMIT
--stop-price	Conditional	Required for STOP_LIMIT

Examples

Market Order

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

Limit Order

python cli.py --symbol BTCUSDT --side BUY --order-type LIMIT --quantity 0.001 --price 40000

Stop-Limit Order

python cli.py --symbol BTCUSDT --side SELL --order-type STOP_LIMIT --quantity 0.001 --price 39000 --stop-price 39500

Output

Successful order execution displays:

==================================================
ORDER EXECUTION RESULT
==================================================
Order ID:      123456789
Symbol:        BTCUSDT
Side:          BUY
Type:          MARKET
Status:        FILLED
Quantity:      0.001
Avg Price:     42000.00
Executed Qty:  0.001
Time:          1704844800000
==================================================

Logging

All API interactions are logged to logs/bot.log. The log file captures:

• Client initialization events
• Connection validation
• Order placement requests
• Order responses
• API errors and exceptions

Log format:

YYYY-MM-DD HH:MM:SS | LEVEL    | Message

Example log entries:

2026-01-10 14:30:00 | INFO     | Initializing Binance Futures client
2026-01-10 14:30:01 | INFO     | Connection to Binance Futures validated
2026-01-10 14:30:02 | INFO     | Placing MARKET order: BUY 0.001 BTCUSDT
2026-01-10 14:30:03 | INFO     | MARKET order placed successfully: orderId=123456789, status=FILLED

The logs directory is automatically created if it does not exist.

Project Structure

trading_bot/
├── config/
│   ├── __init__.py
│   └── settings.py          # Configuration constants
├── core/
│   ├── __init__.py
│   ├── basic_bot.py         # Main trading bot class
│   ├── client.py            # Client utilities
│   └── exceptions.py        # Custom exceptions
├── orders/
│   ├── __init__.py
│   ├── base.py              # Base order class
│   ├── market.py            # Market order implementation
│   ├── limit.py             # Limit order implementation
│   └── stop_limit.py        # Stop-limit order implementation
├── utils/
│   ├── __init__.py
│   ├── logger.py            # Centralized logging
│   └── validators.py        # Input validation utilities
├── cli/
│   ├── __init__.py
│   └── commands.py          # CLI command definitions
├── logs/
│   └── bot.log              # Application logs
├── cli.py                   # Main CLI entry point
├── main.py                  # Alternative entry point
├── requirements.txt         # Python dependencies
├── .env.example             # Environment template
└── README.md

Dependencies

• python-binance: Binance API client library
• python-dotenv: Environment variable management
• click: CLI framework support

Requirements

• Python 3.9 or higher
• Binance Futures Testnet account
• Valid API key and secret

Error Handling

The bot validates all inputs before submitting orders:

• Symbol must be a non-empty string
• Side must be BUY or SELL
• Quantity must be a positive number
• Price must be a positive number (when required)
• Stop price must be a positive number (when required)

API errors from Binance are caught, logged, and re-raised with descriptive messages.