# Easy Binance

> Use this skill when you need to inspect or operate Binance derivatives products through the easy-binance CLI or Python facade, including futures, coin-m futures, options, portfolio margin, order placement and cancellation, position and account queries, leverage changes, method discovery, REST calls, WebSocket API calls, and WebSocket stream subscriptions.

- Skill: `ystemsrx/easy-binance` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ystemsrx/easy-binance`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ystemsrx/easy-binance/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: ystemsrx (https://skillmd.com/u/ystemsrx)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ystemsrx/easy-binance

---


# easy-binance

Use this skill for tasks involving the `easy-binance` package.

Default approach:

1. Check whether `easy-binance` is already available in the current Python environment.
2. If missing, install it with `pip`.
3. Verify credentials before private calls.
4. Discover the exact product, API kind, and method before calling anything non-trivial.
5. Prefer short, bounded calls for validation before longer-running streams.

## Install and verify

Use the same interpreter for checking, installing, and running.

Check whether the package is installed:

```bash
python - <<'PY'
import importlib.metadata as md
try:
    print(md.version("easy-binance"))
except md.PackageNotFoundError:
    raise SystemExit(1)
PY
```

If missing, install it:

```bash
python -m pip install easy-binance
```

Minimal verification:

```bash
easy-binance --help
```

## Credentials

The package resolves credentials in this order:

1. Explicit CLI flags or library arguments
2. `.env` in the current working directory
3. Process environment variables

Expected names:

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

Before making authenticated calls, verify credential presence without printing secrets:

```bash
easy-binance credentials --output yaml
```

If a task should use a specific env file:

```bash
easy-binance --env-file /abs/path/.env credentials
```

## Product and API selection

Canonical products:

| Product | Aliases | APIs |
| --- | --- | --- |
| `usds-futures` | `usdm`, `usds`, `usd-m` | `rest`, `websocket-api`, `websocket-streams` |
| `coin-futures` | `coinm`, `coin`, `coin-m` | `rest`, `websocket-api`, `websocket-streams` |
| `options` | `option` | `rest`, `websocket-streams` |
| `portfolio-margin` | `pm` | `rest`, `websocket-streams` |
| `portfolio-margin-pro` | `pm-pro`, `pmp` | `rest`, `websocket-streams` |

Rules:

- Use `websocket-api` only for products that support it.
- Use `listen` only for `websocket-streams`.
- For unknown endpoints, always discover first instead of guessing method names.

## Discovery workflow

Start with:

```bash
easy-binance products
easy-binance apis usds-futures
easy-binance methods usds-futures rest --output json
```

To inspect one method before calling it:

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

Recommended agent workflow for an unfamiliar request:

1. Map the user request to a product.
2. List APIs for that product.
3. List methods for the target API.
4. Describe the candidate method.
5. Make the call with explicit params.

## CLI usage

List products:

```bash
easy-binance products --output table
```

List methods for an API:

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

Call a public REST endpoint:

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

Call a WebSocket API endpoint:

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

Listen to a stream with safe bounds:

```bash
easy-binance listen usds-futures aggregate_trade_streams \
  --param symbol=btcusdt \
  --duration 5 \
  --max-messages 2 \
  --output json
```

Use a JSON file for complex params:

```bash
easy-binance call usds-futures rest new_order \
  --params-file /abs/path/params.json \
  --output json
```

Global flags that matter in agent runs:

- `--testnet` for testnet endpoints where supported
- `--rest-timeout` for slow REST responses
- `--ws-timeout` for slow WebSocket API responses
- `--api-key` and `--api-secret` for explicit credentials
- `--env-file` for task-specific credentials
- `--rest-url`, `--ws-api-url`, `--ws-stream-url` only when the task explicitly requires overrides

## Parameter rules

`--param KEY=VALUE` attempts JSON parsing first, then falls back to booleans, `null`, numbers, and finally strings.

Examples:

```bash
--param symbol=BTCUSDT
--param limit=5
--param recvWindow=5000
--param price=\"95000.5\"
--param side='\"BUY\"'
--param reduceOnly=true
--param ids='[1,2,3]'
```

Use `--params-file` when quoting would be fragile.

## Python usage

Prefer Python when the user needs multi-step logic, post-processing, or repeated calls in one process.

Basic call:

```python
from easy_binance import EasyBinance

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

WebSocket API call:

```python
from easy_binance import EasyBinance

client = EasyBinance(ws_timeout=10000)
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)
```

Config overrides can be passed to `EasyBinance(...)`, including:

- `api_key`
- `api_secret`
- `env_file`
- `testnet`
- `rest_timeout`
- `ws_timeout`
- `reconnect_delay`
- `pool_size`
- `retries`
- `backoff`
- `keep_alive`
- `proxy`
- `time_unit`
- `return_rate_limits`
- `rest_url`
- `ws_api_url`
- `ws_stream_url`

## Safe operating defaults for agents

- Prefer public endpoints first when validating connectivity.
- Run `describe` before a private or write operation if the method signature is not already known.
- Keep stream runs bounded with `duration` or `max_messages` unless the user explicitly asks for a long-running listener.
- For a likely slow WebSocket API call, increase `--ws-timeout` or `ws_timeout`.
- Use `credentials` to confirm whether auth material is present before diagnosing method failures.

## Failure handling

If you see an unsupported product or API error:

1. Run `easy-binance products`
2. Run `easy-binance apis <product>`
3. Retry with the canonical product and API name

If a method name is rejected:

1. Run `easy-binance methods <product> <api>`
2. Run `easy-binance describe <product> <api> <method>`
3. Update params to match the discovered signature

If import of an official Binance SDK fails, install or repair the current environment and retry the same command.

If a private call fails, verify:

1. Credentials are loaded from the expected source
2. The selected product supports that endpoint
3. The request should use `--testnet` or production