easy-binance 0.1.0

Unified CLI and Python facade for Binance derivatives APIs built on the official Binance SDKs.

easy-binance

An Agent Skill for Binance Derivatives Trading

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

---

[!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

pip install easy-binance

Local development setup

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

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:

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

easy-binance products

List REST methods for USDⓈ-M Futures

easy-binance methods usds-futures rest

Describe a method

easy-binance describe usds-futures rest exchange_information

Call a public REST endpoint

easy-binance call usds-futures rest exchange_information

Call a WebSocket API endpoint

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

Listen to a WebSocket stream

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

[!TIP] If your network is slow, increase the WebSocket timeout:

easy-binance --ws-timeout 10000 call usds-futures websocket-api order_book --param symbol=BTCUSDT

Raw REST request via official SDK

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

Python Examples

REST call

from easy_binance import EasyBinance

client = EasyBinance()

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

WebSocket API call

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

Stream subscription

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.