Binance Futures Testnet Trading Bot

A Python CLI application to place orders on Binance Futures Testnet (USDT-M) using direct REST calls.

---

Project Structure

Trading_bot/
├── bot/
│   ├── __init__.py
│   ├── client.py          # Binance API wrapper (auth, signing, HTTP)
│   ├── orders.py          # Order placement logic
│   ├── validators.py      # Input validation
│   └── logging_config.py  # File + console logging setup
├── cli.py                 # CLI entry point
├── .env                   # API credentials (commited as .env.example)
├── requirements.txt
├── logs/
│   └── trading_bot.log    # Generated on first run
└── README.md

---

Setup

1. Get Testnet API Credentials

• Register at Binance Futures Testnet
• Go to API Management and generate your API Key and Secret
• Enable: Reading, Spot & Margin Trading, Futures

2. Navigate to Project

cd Trading_bot

3. Create and Activate Virtual Environment

python3 -m venv venv
source venv/bin/activate        # Linux/macOS
venv\Scripts\activate           # Windows

4. Install Dependencies

pip install -r requirements.txt

5. Configure API Credentials

Edit the .env file in the project root:

API_KEY=your_api_key_here
API_SECRET=your_api_secret_here

---

Supported Order Types

Order Type	Description
MARKET	Executes immediately at current market price
LIMIT	Executes at a specified price or better
TWAP	Splits a large order into equal chunks over a time period
GRID	Places multiple LIMIT orders at evenly spaced price levels

---

How to Run

MARKET Order

# BUY 0.01 BTC at market price
python cli.py --symbol BTCUSDT --side BUY --type MARKET --quantity 0.01

# SELL 0.01 BTC at market price
python cli.py --symbol BTCUSDT --side SELL --type MARKET --quantity 0.01

LIMIT Order

# BUY 0.01 BTC at 78000 USDT (below market - stays open)
python cli.py --symbol BTCUSDT --side BUY --type LIMIT --quantity 0.01 --price 78000

# SELL 0.01 BTC at 85000 USDT (above market - stays open)
python cli.py --symbol BTCUSDT --side SELL --type LIMIT --quantity 0.01 --price 85000

TWAP Order

Splits total quantity into equal chunks executed over a duration.

# BUY 0.03 BTC split into 3 chunks over 60 seconds
python cli.py --symbol BTCUSDT --side BUY --type TWAP --quantity 0.03 --duration 60 --intervals 3

# SELL 0.04 BTC split into 4 chunks over 120 seconds
python cli.py --symbol BTCUSDT --side SELL --type TWAP --quantity 0.04 --duration 120 --intervals 4

GRID Order

Places multiple LIMIT orders at evenly spaced price levels between a range.

# BUY grid with 4 levels between 78000 and 82000
python cli.py --symbol BTCUSDT --side BUY --type GRID --quantity 0.01 --lower-price 78000 --upper-price 82000 --grid-levels 4

# SELL grid with 5 levels between 83000 and 87000
python cli.py --symbol BTCUSDT --side SELL --type GRID --quantity 0.01 --lower-price 83000 --upper-price 87000 --grid-levels 5

---

CLI Arguments

Argument	Required	Description
--symbol	Always	Trading pair (e.g. BTCUSDT)
--side	Always	BUY or SELL
--type	Always	MARKET, LIMIT, TWAP, or GRID
--quantity	Always	Order quantity
--price	LIMIT only	Limit price
--duration	TWAP only	Total duration in seconds
--intervals	TWAP only	Number of chunks to split into
--lower-price	GRID only	Lower bound of price range
--upper-price	GRID only	Upper bound of price range
--grid-levels	GRID only	Number of grid levels (min 2)

---

Example Output

=============================================
  ORDER SUMMARY
=============================================
  Symbol        : BTCUSDT
  Side          : BUY
  Type          : MARKET
  Quantity      : 0.01
=============================================

=============================================
  ORDER RESPONSE
=============================================
  Order ID   : 123456789
  Symbol     : BTCUSDT
  Side       : BUY
  Type       : MARKET
  Status     : FILLED
  Executed   : 0.01
  Avg Price  : 81250.30
=============================================

[Success] Order placed successfully. Order ID: 123456789

---

Viewing Logs

All logs are written to logs/trading_bot.log:

cat logs/trading_bot.log

• Console shows INFO level and above (clean output)
• Log file contains full DEBUG detail (requests, responses, errors)

---

Validation Rules

Field	Rule
--symbol	Must end with USDT (e.g. BTCUSDT)
--side	Must be BUY or SELL
--type	Must be MARKET, LIMIT, TWAP, or GRID
--quantity	Must be a positive number
--price	Required for LIMIT, must be positive
--duration	Required for TWAP, must be a positive integer (seconds)
--intervals	Required for TWAP, must be ≤ duration
--lower-price	Required for GRID, must be positive
--upper-price	Required for GRID, must be greater than --lower-price
--grid-levels	Required for GRID, must be integer ≥ 2

---

Assumptions

• Only USDT-M Futures pairs are supported (symbols must end in USDT)
• LIMIT orders use timeInForce=GTC (Good Till Cancelled) by default
• TWAP executes equal-sized MARKET orders at evenly spaced time intervals
• GRID places LIMIT orders at evenly spaced price levels — prices are rounded to BTCUSDT tick size (0.1)
• API credentials are stored in .env and never hardcoded
• Testnet base URL is hardcoded as https://testnet.binancefuture.com
• STOP_LIMIT and OCO order types are not supported on Binance Futures Testnet and have been excluded
• Minimum notional value for BTCUSDT is $100 — ensure quantity × price ≥ 100