Milo

A Python Terminal UI (TUI) trading bot for Binance Futures Testnet that allows you to place and manage futures orders with an interactive interface.

Features

• Beautiful Terminal UI: Interactive terminal interface built with Textual
• Multiple Order Types: Support for MARKET, LIMIT, and STOP_LIMIT orders
• Real-time Feedback: Instant order validation and execution results
• Order History Log: Live order history and status updates in the interface
• Futures Trading: USDT-margined futures contracts on Binance testnet
• Input Validation: Robust parameter validation for symbols, quantities, and prices
• Logging: Comprehensive logging for debugging and monitoring
• Testnet Ready: Configured for Binance Futures Testnet environment

Screenshots

The TUI features:

• Split-panel layout with order form on the left and order log on the right
• Dropdown menus for side and order type selection
• Real-time input validation
• Color-coded success/error messages
• Keyboard shortcuts for quick navigation

Installation

Prerequisites

• Python 3.12
• Binance Futures Testnet API credentials

Setup

1. Clone the repository:

git clone <repository-url>
cd Milo

2. Create a virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Linux/Mac
# or
.venv\Scripts\activate  # On Windows

3. Install dependencies:

pip install -e .

4. Create a .env file in the project root:

BINANCE_API_KEY=your_testnet_api_key
BINANCE_API_SECRET=your_testnet_api_secret

Getting Testnet API Keys

1. Visit Binance Futures Testnet
2. Log in or create an account
3. Generate API keys from the account settings
4. Add the keys to your .env file

Usage

Starting the TUI

Launch the interactive terminal interface:

python main.py

Using the Interface

1. Fill in the Order Form (left panel):

   • Enter the trading symbol (e.g., BTCUSDT)
   • Select the side (BUY or SELL) from the dropdown
   • Choose order type (MARKET, LIMIT, or STOP_LIMIT)
   • Enter the quantity
   • For LIMIT/STOP_LIMIT orders, enter the price
   • For STOP_LIMIT orders, enter the stop price

2. Submit the Order:

   • Click "Place Order" button or press Enter
   • View the results in the Order History panel (right side)

3. Keyboard Shortcuts:

   • q - Quit the application
   • c - Clear the form
   • Tab - Navigate between fields
   • Enter - Submit when focused on a button

Order Examples

Market Order

1. Symbol: BTCUSDT
2. Side: BUY
3. Order Type: MARKET
4. Quantity: 0.01
5. Click "Place Order"

Limit Order

1. Symbol: BTCUSDT
2. Side: SELL
3. Order Type: LIMIT
4. Quantity: 0.01
5. Price: 30000
6. Click "Place Order"

Stop-Limit Order

1. Symbol: BTCUSDT
2. Side: BUY
3. Order Type: STOP_LIMIT
4. Quantity: 0.01
5. Price: 31000
6. Stop Price: 30500
7. Click "Place Order"

Project Structure

Milo/
├── bot/
│   ├── __init__.py
│   ├── client.py          # Binance API client wrapper
│   ├── orders.py          # Order placement logic
│   └── logging_config.py  # Logging configuration
├── tui/
│   ├── __init__.py
│   └── app.py             # Textual TUI application
├── cli/                   # Legacy CLI (kept for reference)
│   ├── cmd.py
│   └── validate.py
├── logs/
│   └── bot.log            # Application logs
├── main.py                # Application entry point
├── pyproject.toml         # Project dependencies
├── .env                   # API credentials (not in repo)
└── README.md              # This file

Logging

All operations are logged to logs/bot.log with the following information:

• Order placement attempts
• API requests and responses
• Errors and exceptions

View logs in real-time:

tail -f logs/bot.log

Development

Adding New Order Types

1. Update the order type dropdown in tui/app.py in the OrderForm class
2. Add validation logic in the place_order method of MiloTUI class
3. Update order logic in bot/client.py in the place_order method
4. Update this README with usage examples

Customizing the TUI

The TUI appearance can be customized by modifying the CSS in tui/app.py:

• Colors and themes
• Layout and spacing
• Widget styles
• Border styles

Running in Development Mode

# Run the TUI
python main.py

# View logs in another terminal
tail -f logs/bot.log

Known Issues

• Empty API Responses: The Binance Futures Testnet sometimes returns empty order responses ({}), even when orders are successfully placed. This is a limitation of the testnet environment, not a bug in the code.
• Testnet Stability: The testnet may have different behavior compared to production.

Important Notes

• Testnet Only: This bot is configured for testnet only. Do not use with production API keys.
• No Real Money: All trades on testnet use fake funds.
• API Security: Never commit your .env file or expose your API keys.
• Limitations: Testnet may have limited liquidity and different order book behavior.
• Terminal Requirements: Works best in modern terminals with good Unicode support.

Troubleshooting

"Missing BINANCE_API_KEY or BINANCE_API_SECRET"

Ensure your .env file exists and contains valid testnet API credentials.

"Invalid API-key, IP, or permissions for action"

You're using mainnet API keys with testnet. Get proper testnet keys from https://testnet.binancefuture.com

Orders show empty response

This is normal for testnet. Check the logs to confirm the order was sent successfully. Verify orders in the testnet web interface.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is for educational purposes.

Disclaimer

This software is for educational and testing purposes only. Cryptocurrency trading carries significant risk. Always practice with testnet before considering real trading. The authors are not responsible for any financial losses.