<div align="center">

# easy-binance

[![PyPI version](https://img.shields.io/pypi/v/easy-binance?color=blue&logo=pypi&logoColor=white)](https://pypi.org/project/easy-binance/)
[![Python](https://img.shields.io/pypi/pyversions/easy-binance?logo=python&logoColor=white)](https://pypi.org/project/easy-binance/)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
[![Build](https://img.shields.io/github/actions/workflow/status/ystemsrx/easy-binance/ci.yml?logo=github)](https://github.com/ystemsrx/easy-binance/actions)
[![Agent Skill](https://img.shields.io/badge/Agent_Skill-Claude_Code-blueviolet?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0xMiAyQzYuNDggMiAyIDYuNDggMiAxMnM0LjQ4IDEwIDEwIDEwIDEwLTQuNDggMTAtMTBTMTcuNTIgMiAxMiAyem0wIDE4Yy00LjQyIDAtOC0zLjU4LTgtOHMzLjU4LTggOC04IDggMy41OCA4IDgtMy41OCA4LTggOHoiLz48L3N2Zz4=)](skills/easy-binance/SKILL.md)

**An Agent Skill for Binance Derivatives Trading**

_Let your AI agent trade, query, and stream Binance futures & options — via CLI or Python_

---

</div>

> [!IMPORTANT]
> **`easy-binance` is designed as a _skill_ for AI coding agents** (e.g. Claude Code, Cursor, codex).
> It ships a `SKILL.md` manifest so agents can autonomously discover products, pick the right API, and execute trades — no manual lookup required.
> Of course, it works perfectly fine as a standalone CLI / Python library too.

## Features

| Feature               | Description                                                                     |
| --------------------- | ------------------------------------------------------------------------------- |
| **Multi-product**     | USDⓈ-M Futures, COIN-M Futures, Options, Portfolio Margin, Portfolio Margin Pro |
| **CLI**               | Installable entrypoint — `easy-binance --help`                                  |
| **REST**              | Typed REST API calls via official SDKs                                          |
| **WebSocket API**     | Request/response over WebSocket connections                                     |
| **WebSocket Streams** | Real-time market data subscriptions                                             |
| **Python Library**    | Use directly in your own scripts and projects                                   |
| **Dynamic Discovery** | Auto-discover all available methods per product                                 |
| **`.env` Support**    | Credentials from `.env` (CWD) → env vars, with smart precedence                 |

## Install

```bash
pip install easy-binance
```

<details>
<summary><b>Local development setup</b></summary>

```bash
uv venv .venv
uv pip install -e .[dev]
```

</details>

## Credentials

> [!NOTE]
> `easy-binance` resolves credentials in the following priority order:
>
> 1. Explicit CLI options or library arguments
> 2. `.env` file in the current working directory
> 3. Process environment variables

Expected variable names:

```bash
BINANCE_API_KEY=...
BINANCE_API_SECRET=...
```

> [!CAUTION]
> Never commit your `.env` file or share your API credentials. Always add `.env` to your `.gitignore`.

## CLI Examples

### List products

```bash
easy-binance products
```

### List REST methods for USDⓈ-M Futures

```bash
easy-binance methods usds-futures rest
```

### Describe a method

```bash
easy-binance describe usds-futures rest exchange_information
```

### Call a public REST endpoint

```bash
easy-binance call usds-futures rest exchange_information
```

### Call a WebSocket API endpoint

```bash
easy-binance call usds-futures websocket-api order_book --param symbol=BTCUSDT
```

### Listen to a WebSocket stream

```bash
easy-binance listen usds-futures aggregate_trade_streams --param symbol=btcusdt --duration 5
```

> [!TIP]
> If your network is slow, increase the WebSocket timeout:
>
> ```bash
> easy-binance --ws-timeout 10000 call usds-futures websocket-api order_book --param symbol=BTCUSDT
> ```

### Raw REST request via official SDK

```bash
easy-binance call usds-futures rest send_request \
  --param endpoint=/fapi/v1/exchangeInfo \
  --param method=GET
```

## Python Examples

### REST call

```python
from easy_binance import EasyBinance

client = EasyBinance()

info = client.call("usds-futures", "rest", "exchange_information")
print(info["data"]["timezone"])
```

### WebSocket API call

```python
book = client.call(
    "usds-futures",
    "websocket-api",
    "order_book",
    params={"symbol": "BTCUSDT"},
)
print(book["data"])
```

### Stream subscription

```python
from easy_binance import EasyBinance

client = EasyBinance()
messages = client.listen(
    "usds-futures",
    "aggregate_trade_streams",
    params={"symbol": "btcusdt"},
    duration=3,
    max_messages=2,
)
print(messages)
```

## Use as Agent Skill

The `skills/easy-binance/SKILL.md` file is a skill manifest that teaches AI agents how to use this tool autonomously. It covers:

- Install & verification steps
- Credential resolution
- Product / API / method discovery workflow
- CLI and Python calling conventions
- Parameter encoding rules
- Safe operating defaults (bounded streams, describe-before-call)
- Failure handling & recovery

### Supported agent platforms

| Platform         | How to register                                                                               |
| ---------------- | --------------------------------------------------------------------------------------------- |
| **Claude Code**  | Place `skills/easy-binance/` under your project root — Claude Code discovers it automatically |
| **Other agents** | Point the agent at `SKILL.md` as a system prompt or tool description                          |

## Project Structure

```
easy-binance/
├── skills/easy-binance/
│   └── SKILL.md        # Agent skill manifest
├── src/easy_binance/
│   ├── cli.py          # Typer CLI entrypoint
│   ├── core.py         # Unified facade logic
│   ├── config.py       # Credential resolution & .env loading
│   ├── products.py     # Product registry
│   ├── formatting.py   # Rich output formatting
│   ├── utils.py        # Shared helpers
│   └── errors.py       # Custom exceptions
├── tests/
├── pyproject.toml
└── README.md
```

## License

This project is licensed under the [Apache License 2.0](LICENCE).
