binance-usdm-futures-tools

Files (1)

• SKILL.md

SKILL.md (first lines)

# Binance USDⓈ-M Futures — LLM Tools & MCP

Wired once in [`binance-sdk`](https://github.com/shubhamtaywade82/binance-sdk), used everywhere
(chat-ui, trading-agent-ts, any MCP-capable agent). All tool names below are stable SDK entry points; the
host (MCP server `binance-sdk-mcp`, or a chat-ui's `createFuturesToolkit(...)` output) exposes them to the model.

## Connection & Auth

- Configure once via env: `BINANCE_API_KEY`, `BINANCE_API_SECRET`, `BINANCE_TESTNET=true` (→ `testnet.binancefuture.com`).
- Public market-data tools are **unsigned**; account/trade/private tools are **signed** and require the keys above.
- Base URLs (live, 2026 USDⓈ-M WS routing — legacy `/stream` and `/ws` paths shut down April 23, 2026):
  REST `https://fapi.binance.com`, WS market streams `wss://fstream.binance.com/market/stream`,
  WS public aggregate streams `wss://fstream.binance.com/public/stream`,
  WS user data `wss://fstream.binance.com/public/ws`, WS API `wss://ws-fapi.binance.com/ws-fapi/v1`.
- Rate limits: **2400 weight/min** (REST, per IP) + **1200 orders/10s** + 300 orders/10s/uid (WS API). The SDK's
  `RateLimitTracker` parses the `X-MBX-USED-WEIGHT-*` / `X-MBX-ORDER-COUNT-*` response headers and delays queued
  requests once usage crosses the configured safety margin (`rateLimitWeightPerMinute` / `rateLimitSafetyMargin`),
  preempting `-1003` IP bans. Inspect live per-host usage via `client.getRateLimitUsage()`; a safety margin of
  80-90% of the caps above is still recommended so bursts of market-data scans stay clear of the ceiling.

## Trigger

Use these tools when the user asks about Binance **USD-M futures** (tickers, order books, trades, klines,
funding, open interest, positions, balances, orders) — whether for live data, execution, or a chat-ui /
trading-agent analysis. Do **not** use for spot, COIN-M, or Delta-Exchange contexts.

## Rules (KISS / Safety)

1. **Public-first.** Satisfy analysis questions from the market-data tools before any signed call.
2. **Symbols** are always uppercase USD-M pair form, e.g. `BTCUSDT`, `ETHUSDT`, `ETHBTC`. For index/pair
   queries (klines, basis) pass the base pair.
3. **No destructive action without `CONFIRM`.** Placing/cancelling/modifying orders requires the user to
   type `CONFIRM` (or set explicit allowance). Read-only tools never need it.
4. **Validate before trading.** Fetch `futures_exchange_info`, symbol tick, mark price, and open interest
   before sizing; confirm the symbol is TRADING.
5. **Depth + klines**: order-book snapshots come from `futures_order_book`; live updates come as deltas
   over WebSocket via `futures_ws_subscribe` + `futures_ws_events` and must be **applied to the snapshot**.
6. **Prefer a composite over a chain.** Where a composite tool exists (below), use it instead of chaining
   primitives — they exist to keep tick/step arithmetic and mode-dependent order fields out of the model.

## Composite Tools (prefer these)

Each fans out over several endpoints and returns one answer. Round-off and mode handling live here,
not in the model.

| Tool | Replaces | Why it exists |
| ------ | ---------- | --------------- |
| `futures_symbol_rules` | `futures_exchange_info` + filter parsing | Flattens the `filters` array into typed tickSize / stepSize / minQty / maxQty / minNotional. |
| `futures_quantize` | manual rounding | Rounds a price to the tick and a quantity to the step, returning **exchange-ready strings**. Off-tick values are rejected with `-1111`. |
| `futures_size_position` | exchangeInfo + markPrice + balance + arithmetic | Turns a risk budget (`riskAmount` or `riskPct`) plus a stop into a step-aligned quantity, and reports every failed constraint (min notional, lot bounds, wrong-side stop) instead of quietly adjusting risk. |
| `futures_close_position` | `futures_position_risk` + `futures_new_order` | Derives the closing side from the position sign and picks `reduceOnly` (one-way) vs `positionSide` (hedge) — Binance rejects the wrong one. Supports `portion` and `dryRun`. |
| `futures_market_snapshot` | 4 market-data calls | 24h stats + mark/funding + open interest + long/short in one call; a failing feed degrades to an `error` field. |
| `futures_account_overview` | balance + positions + open orders | Funded balances, non-flat positions, working orders, and PnL/notional totals. |
| `futures_place_bracket_order` | 3 `futures_new_order` calls | Entry + stop-loss + optional take-profit, all tick-quantized. If a protective leg fails it returns `protectionComplete: false`; the entry is **not** auto-cancelled since it may already have filled — resolve manually. |

**Never do tick/step arithmetic yourself.** `futures_quantize` or `futures_size_position` returns the
string to send. Floating-point rounding in the model is the most common source of `-1111` (precision)
and `-4164` (min notional) rejections.

## Public — Market Data Tools (unsigned)

| Tool | Purpose |
| ------ | --------- |
| `futures_ping` | Test connectivity (REST). |
| `futures_server_time` | Server time in ms. |
| `futures_exchange_info` | Symbol/metadata, contract types, filters, delivery dates. |
| `futures_ticker_price` | Latest price for one symbol (v1). |
| `futures_ticker_price_v2` | Latest price, one symbol or **all**. |
| `futures_ticker_24hr` | 24h change stats (price, volume, open interest, high/low). |
| `futures_book_ticker` | Best bid/ask for one symbol (v1). |
| `futures_book_ticker_v2` | Best bid/ask, one symbol or **all**. |
| `futures_order_book` | Order-book depth (limits 5/10/20/50/100/500/1000/5000). |
| `futures_rpi_depth` | Retail Price Improvement order-book depth. |
| `futures_recent_trades` | Most recent trades. |
| `futures_historical_trades` | Older trades by `fromId`. |
| `futures_agg_trades` | Compressed/aggregate trades. |
| `futures_klines` | Candlesticks (1m…1M; max 1500). |
| `futures_continuous_klines` | Continuous-contract klines (perpetual/current_quarter/next_quarter). |
| `futures_index_price_klines` | Index-price klines. |
| `futures_mark_price_klines` | Mark-price klines. |
| `futures_premium_index_klines` | Premium-index klines (mark price premium over index). |
| `futures_trading_day_ticker` | Trading-day rolling ticker stats. |
| `futures_mark_price` | Mark+index price, funding rate, next funding time. |
| `futures_funding_rate_history` | Historical funding rates. |
| `futures_funding_info` | Adjusted cap/floor/interval funding config. |
| `futures_open_interest` | Current open interest. |
| `futures_open_interest_hist` | Historical open-interest stats (per period). |
| `futures_top_long_short_account_ratio` | Top-trader L/S by account count. |
| `futures_top_long_short_position_ratio` | Top-trader L/S by position. |
| `futures_global_long_short_ratio` | Global L/S account ratio. |
| `futures_taker_long_short_ratio` | Taker buy/sell volume ratio. |
| `futures_basis` | Spot-futures basis (per pair/contract type). |
| `futures_asset_index` | Multi-assets-mode collateral index (one or all). |
| `futures_composite_index_info` | Composite-index constituents (e.g. DEFIUSDT). |
| `futures_insurance_balance` | Insurance-fund balance snapshots. |
| `futures_index_price_constituents` | Exchange weights for an index price. |
| `futures_delivery_price` | Historical quarterly-contract settlement/delivery prices. |
| `futures_convert_exchange_info` | Asset pairs eligible for futures Convert. |
| `futures_symbol_adl_risk` | ADL risk level for a symbol or all symbols (signed). |
| `futures_adl_quantile` | Position ADL quantile (signed). |
| `futures_force_orders` | Force orders (liquidations/ADL) (signed). |

## Real-time — WebSocket Tools (public)

Subscribe → poll buffered events → act on the parsed payloads:

| Tool | Purpose |
| ------ | --------- |
| `futures_ws_subscribe` | Subscribe to one or more topics, e.g. `btcusdt@aggTrade`, `btcusdt@kline_1m`, `btcusdt@depth20`, `btcusdt@markPrice@1s`, `btcusdt@bookTicker`, `btcusdt@ticker`, `!ticker@arr`, `!markPrice@arr`, `!forceOrder@arr`. |
| `futures_ws_unsubscribe` | Unsubscribe topics. |
| `futures_ws_subscriptions` | List active subscriptions. |
| `futures_ws_events` | Read buffered payloads for subscribed streams (depth deltas are incremental; apply to `futures_order_book`). |
| `futures_ws_clear_events` | Flush the buffer. |
| `futures_ws_start_user_stream` | Start the private user data stream (listenKey + keep-alive). |
| `futures_ws_stop_user_stream` | Stop & invalidate the user data stream. |

## Private — Account Tools (signed, USER_DATA)

| Tool | Purpose |

From shubhamtaywade82/binance-sdk, MIT.

More from shubhamtaywade82/binance-sdk