easy-binance

name	easy-binance
description	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.

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:

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

If missing, install it:

python -m pip install easy-binance

Minimal verification:

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:

BINANCE_API_KEY=...
BINANCE_API_SECRET=...

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

easy-binance credentials --output yaml

If a task should use a specific env file:

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:

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

To inspect one method before calling it:

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:

easy-binance products --output table

List methods for an API:

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

Call a public REST endpoint:

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

Call a WebSocket API endpoint:

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

Listen to a stream with safe bounds:

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:

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:

--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:

from easy_binance import EasyBinance

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

WebSocket API call:

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:

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