# Binance Futures Testnet Trading Bot

## 📌 Overview

This project is a simple Python-based trading bot built for the Binance Futures Testnet (USDT-M). The main purpose of this application is to place Market and Limit orders using a clean and structured approach.

The bot takes input from the command line, validates it, and places an order using Binance APIs. It also handles common issues like minimum order size and invalid price ranges by automatically adjusting values when required. All activities are logged into a file for better tracking and debugging.

---

## 🚀 Features

* Supports **Market Orders** and **Limit Orders**
* Allows both **BUY** and **SELL** operations
* CLI-based input using `argparse`
* Automatic handling of Binance constraints:

  * Minimum notional value (≥ 100 USDT)
  * Valid price range for limit orders
* Logging of API requests, responses, and errors
* Clean and modular code structure
* Basic error handling for invalid inputs and API failures

---

## 📁 Project Structure

```
trading_bot/
│
├── bot/
│   ├── client.py          # Binance API client setup
│   ├── orders.py          # Order execution logic
│   ├── validators.py      # Input validation
│   ├── logging_config.py  # Logging setup
│
├── cli.py                 # Command-line interface
├── .env                   # API credentials (not shared)
├── requirements.txt
├── README.md
├── trading.log            # Log file (generated after running)
```

---

## ⚙️ Setup Instructions

### 1. Clone the Repository

```
git clone <your-repo-link>
cd trading_bot
```

---

### 2. Create Virtual Environment (Recommended)

```
python -m venv venv
```

Activate it:

**Windows:**

```
venv\Scripts\activate
```

**Mac/Linux:**

```
source venv/bin/activate
```

---

### 3. Install Dependencies

```
pip install -r requirements.txt
```

---

### 4. Setup Environment Variables

Create a `.env` file in the root directory:

```
API_KEY=your_testnet_api_key
API_SECRET=your_testnet_secret_key
```

Make sure these keys are generated from Binance Futures Testnet.

---

### 5. Testnet API URL

The application uses the Binance Futures Testnet:

```
https://testnet.binancefuture.com
```

---

## ▶️ How to Run

### ✅ Market Order Example

```
python cli.py --symbol BTCUSDT --side BUY --type MARKET --quantity 0.002
```

---

### ✅ Limit Order Example

```
python cli.py --symbol BTCUSDT --side SELL --type LIMIT --quantity 0.002 --price 60000
```

Even if the input values are not perfect, the bot will automatically adjust them based on market conditions.

---

## 📊 Output Explanation

After running a command, the bot shows:

* Order Summary (input values)
* Market adjustment message (if any)
* Order Response:

  * Order ID
  * Status
  * Executed Quantity
  * Average Price

Note:
If the status is `NEW`, it means the order is placed but not executed yet.

---

## 📝 Logging

All logs are stored in:

```
trading.log
```

Logs include:

* Order requests
* API responses
* Adjustments (price/quantity)
* Errors

This helps in debugging and understanding system behavior.

---

## ⚠️ Error Handling

The bot handles:

* Invalid BUY/SELL inputs
* Missing price for LIMIT orders
* Binance API errors
* Minimum order size issues
* Price range violations

Instead of failing, the bot tries to correct inputs automatically whenever possible.

---

## 🧪 Testing

The following tests were performed:

* One Market Order (BUY) → successfully placed
* One Limit Order (SELL) → successfully placed

Both orders were logged in `trading.log`.

---

## 📌 Assumptions

* User has a valid Binance Futures Testnet account
* API keys are correct and active
* Internet connection is stable
* Trading symbol exists on Binance

---

## 🔧 Future Improvements

* Add Stop-Limit or advanced order types
* Improve CLI with interactive prompts
* Add a simple UI (Streamlit or web-based)
* Real-time price display before placing order

---

## 👨‍💻 Author

This project was developed as part of an internship application task for a Python Developer role.

---

Note: On Binance Testnet, some orders may show status as "NEW" instead of "FILLED". This means the order is successfully placed but not yet executed due to testnet behavior or market conditions.