Binance

Founded in 2017, Binance is one of the largest cryptocurrency exchanges in terms of daily trading volume, and open interest of crypto assets and crypto derivative products.

NautilusTrader provides Binance integration in both Python and Rust. The Rust adapter supports all product types listed below and includes additional features (noted inline). The Python adapter supports the same product types but will not receive new features as development moves to v2.

Supported products:

• Binance Spot (including Binance US)
• Binance USDT-Margined Futures (perpetuals and delivery contracts)
• Binance Coin-Margined Futures (perpetuals and delivery contracts)

Examples

• Python live examples
• Rust spot examples
• Rust futures examples

Overview

The Binance adapter includes multiple components that can be used together or separately:

• BinanceHttpClient: Low-level HTTP API connectivity.
• BinanceWebSocketClient: Low-level WebSocket API connectivity.
• BinanceInstrumentProvider: Instrument parsing and loading.
• BinanceSpotDataClient / BinanceFuturesDataClient: Market data feed manager.
• BinanceSpotExecutionClient / BinanceFuturesExecutionClient: Account management and trade execution gateway.
• BinanceLiveDataClientFactory: Factory for Binance data clients (used by the trading node builder).
• BinanceLiveExecClientFactory: Factory for Binance execution clients (used by the trading node builder).

Product support

Data types

The integration includes several custom data types:

• BinanceTicker: 24-hour ticker data including price and statistical information.
• BinanceBar: Bar data with additional volume metrics for historical and real-time use.
• BinanceFuturesMarkPriceUpdate: Mark price updates for Binance Futures.

See the Binance API Reference for full definitions.

Symbology

Native Binance symbols are used where possible for spot and futures contracts. Because NautilusTrader supports multi-venue trading, it must distinguish between BTCUSDT the spot pair and BTCUSDT the perpetual futures contract (Binance uses the same symbol for both).

Nautilus appends the -PERP suffix to all perpetual symbols. For example, the Binance Futures BTCUSDT perpetual contract becomes BTCUSDT-PERP within Nautilus.

Order capability

The following tables detail order types, execution instructions, and time-in-force options across Binance account types.

Order types

Execution instructions

Post-only restrictions

Only limit order types support post_only.

Time in force

Advanced order features

Batch operations

Cancel all orders behavior

When calling cancel_all_orders() from a strategy, the adapter includes orders in both open and inflight (SUBMITTED) states so that orders not yet acknowledged by Binance are also canceled.

Multi-strategy safety: When multiple strategies trade the same instrument, the adapter compares orders owned by the requesting strategy against all orders for that instrument. If the strategy owns all orders, a single cancel-all API call is used. Otherwise, per-strategy cancels are sent (batch for regular orders, individual for algo orders) to avoid affecting other strategies.

Futures algo orders: Conditional order types (STOP_MARKET, STOP_LIMIT, TAKE_PROFIT, TAKE_PROFIT_MARKET, TRAILING_STOP_MARKET) require a different cancel endpoint. The adapter routes these through the correct endpoint automatically. Once an algo order triggers and becomes a regular order, it uses the standard cancel endpoint.

Endpoints used:

Position management

Risk events

Binance Futures can trigger exchange-generated orders in response to risk events:

• Liquidations: When insufficient margin exists to maintain a position, Binance forcibly closes it at the bankruptcy price. These orders have client IDs starting with autoclose-.
• ADL (Auto-Deleveraging): When the insurance fund is depleted, Binance closes profitable positions to cover losses. These orders use client ID adl_autoclose.
• Settlements: Quarterly contract deliveries use client IDs starting with settlement_autoclose-.

The adapter detects these special order types via their client ID patterns (checked before the execution type), then:

1. Logs a warning with order details for monitoring.
2. Generates a FillReport with correct fill details and TAKER liquidity side.
3. Generates an OrderStatusReport for reconciliation.

The execution engine creates external orders from runtime status reports when the order is not already in cache. This covers first-seen exchange-generated orders (the typical case for a live liquidation or ADL event). The engine assigns the order to any strategy that has claimed the instrument via external_order_claims, or to the EXTERNAL strategy by default.

Commission estimation

When Binance omits the commission fields (N/n) from the fill event, the Rust adapter estimates commission as default_taker_fee * qty * price using the quote currency. This applies to USD-M linear contracts only. COIN-M inverse contracts use zero commission as a fallback because the linear formula does not account for contract size. Configure default_taker_fee on BinanceExecClientConfig to match your fee tier (default: 0.0004 / 0.04%).

Hedge-mode position IDs

When use_position_ids is enabled (default), exchange-generated fill reports include a venue_position_id derived from the instrument and position side (e.g. ETHUSDT-PERP.BINANCE-LONG). Set use_position_ids to false on BinanceExecClientConfig for virtual positions with OmsType.HEDGING.

Order querying

Contingent orders

Order parameters

Customize individual orders by supplying a params dictionary when calling Strategy.submit_order (Python) or setting Params on a SubmitOrder command (Rust). The Binance execution clients recognize:

Price match

Binance Futures supports BBO (Best Bid/Offer) price matching via the priceMatch parameter, which delegates price selection to the exchange. Limit orders dynamically join the order book at optimal prices without specifying an exact price level.

When using price_match, you submit a limit order with a reference price (for local risk checks), and Binance determines the actual working price based on the current market state and price match mode.

Valid price match values

Event sequence

When an order is submitted with price_match:

1. Nautilus sends the order to Binance with the priceMatch parameter but omits the limit price from the API request.
2. Binance accepts the order and determines the actual working price.
3. Nautilus generates an OrderAccepted event.
4. If the Binance-accepted price differs from the reference price, Nautilus generates an OrderUpdated event with the actual working price.
5. The order price in the Nautilus cache now matches the Binance-accepted price.

Example

order = strategy.order_factory.limit(
    instrument_id=InstrumentId.from_str("BTCUSDT-PERP.BINANCE"),
    order_side=OrderSide.BUY,
    quantity=Quantity.from_int(1),
    price=Price.from_str("65000"),  # Reference price for local risk checks
)

strategy.submit_order(
    order,
    params={"price_match": "QUEUE"},
)

Close position

Binance Futures conditional orders support closePosition, which closes the entire position when the trigger fires. Binance resolves the quantity server-side from the current position size at trigger time.

Unlike reduce_only, closePosition adapts to position size changes, and Binance auto-cancels the order when the position is closed by other means.

Pass close_position via the params dictionary on StopMarket or MarketIfTouched orders. Cannot be combined with reduce_only.

<Tabs items={['Python', 'Rust']}>

strategy.submit_order(order, params={"close_position": True})

Trailing stops

For trailing stop market orders on Binance:

• Use activation_price (optional) to specify when the trailing mechanism activates.
• When omitted, Binance uses the current market price at submission time.
• Use trailing_offset for the callback rate (in basis points).

Link & Trade

The NautilusTrader integration ID is automatically prefixed to all system-generated client order IDs for every order placed through the Binance Rust adapter. This provides transparent order attribution through Binance's Link and Trade program without requiring any user configuration.

The adapter uses a deterministic two-way encoding to compress outgoing ClientOrderId values into a compact format that fits within Binance's 36-character newClientOrderId limit, and decodes incoming order events back to the original ID before they reach strategies. This transformation is fully transparent: strategies see only their original ClientOrderId values at all times.

Decoding client order IDs

When querying Binance directly (REST API, web UI, or your own HTTP code), the clientOrderId field contains the encoded form. Two utility functions recover the original Nautilus ClientOrderId:

from nautilus_trader.adapters.binance import (
    decode_binance_futures_client_order_id,
    decode_binance_spot_client_order_id,
)

# Encoded ID from Binance REST response or web UI
encoded = "x-TD67BGP9-T0A4b1H2vj50H"
original = decode_binance_spot_client_order_id(encoded)
# -> "O-20260305-120000-001-001-100"

# Futures equivalent
encoded_futures = "x-aHRE4BCj-U2xK9mPqR7sT1vW3y"
original_futures = decode_binance_futures_client_order_id(encoded_futures)

Strings without the broker prefix pass through unchanged, so these are safe to call on any clientOrderId value.

Order books

Order books can be maintained at full or partial depths. WebSocket stream update rates differ between Spot and Futures, with Nautilus using the highest available rate:

• Spot: 100ms
• Futures: 0ms (unthrottled)

Only one order book per instrument per trader instance is supported. When stream subscriptions vary, the Binance data client uses the latest order book data subscription (deltas or snapshots).

Order book snapshot rebuilds will be triggered on:

• Initial subscription of the order book data.
• Data websocket reconnects.

The sequence of events is as follows:

• Deltas will start buffered.
• Snapshot is requested and awaited.
• Snapshot response is parsed to OrderBookDeltas.
• Snapshot deltas are sent to the DataEngine.
• Buffered deltas are iterated, dropping those where the sequence number is not greater than the last delta in the snapshot.
• Deltas will stop buffering.
• Remaining deltas are sent to the DataEngine.

Binance data differences

The ts_event field on QuoteTick differs between Spot and Futures. Spot does not provide an event timestamp, so ts_init is used (meaning ts_event and ts_init are identical).

Binance specific data

You can subscribe to Binance-specific data streams as they become available.

BinanceFuturesMarkPriceUpdate

Subscribe to BinanceFuturesMarkPriceUpdate (including funding rate info) from your actor or strategy:

from nautilus_trader.adapters.binance import BinanceFuturesMarkPriceUpdate
from nautilus_trader.model import DataType
from nautilus_trader.model import ClientId

# In your `on_start` method
self.subscribe_data(
    data_type=DataType(BinanceFuturesMarkPriceUpdate, metadata={"instrument_id": self.instrument.id}),
    client_id=ClientId("BINANCE"),
)

Received BinanceFuturesMarkPriceUpdate objects are passed to your on_data method. Check the type, as this method handles all custom/generic data.

from nautilus_trader.core import Data

def on_data(self, data: Data):
    # First check the type of data
    if isinstance(data, BinanceFuturesMarkPriceUpdate):
        # Do something with the data

Funding rates

The Rust adapter emits FundingRateUpdate as a first-class data type through subscribe_funding_rates. The data comes from the Mark Price Stream WebSocket endpoint, which provides the current funding rate and next funding time alongside mark and index prices. All three subscriptions (subscribe_mark_prices, subscribe_index_prices, subscribe_funding_rates) share a single @markPrice@1s stream with ref-counted subscription management.

The Python adapter exposes funding rate data through BinanceFuturesMarkPriceUpdate custom data subscriptions (see Binance specific data below).

The interval field on FundingRateUpdate is None for Binance because the Mark Price Stream does not include a funding interval field. Binance exposes fundingIntervalHours through the Get Funding Rate Info REST endpoint, but the adapter does not consume it.

Instrument status polling

The adapter periodically polls Binance exchangeInfo to detect changes in instrument trading status. When a symbol transitions between states (e.g. Trading to Halt, or Trading to Delivering for a futures contract approaching expiry), the adapter emits an InstrumentStatus event.

The polling interval defaults to 3600 seconds (60 minutes) and is configurable via instrument_status_poll_secs in the data client config. Set to 0 to disable polling entirely.

On initial connect, the adapter seeds its status cache from the exchange info response without emitting events. Only subsequent polls that detect a status change emit InstrumentStatus events. If a symbol disappears from exchange info (e.g. after delisting or contract expiry), the adapter emits NotAvailableForTrading.

Status mapping

Spot

Futures (USD-M)

Futures (COIN-M)

Rate limiting

Binance uses an interval-based rate limiting system where request weight is tracked per fixed time window (every minute, resetting at

Global weight limits

These are the primary limits shared across all endpoints:

Endpoint weight costs

Some endpoints have higher weight costs per request:

WebSocket API limits

The WebSocket API (used for user data streams) shares the same weight quota as the REST API:

Adapter behavior

The adapter uses token bucket rate limiters to approximate Binance's interval-based limits. This reduces the risk of quota violations while maintaining throughput for normal operations.

For endpoints with dynamic weight (e.g. /klines scales with the limit parameter), the adapter draws a single token per call. Large history requests may need manual pacing. Monitor the X-MBX-USED-WEIGHT-* response headers to track actual usage.

Configuration

Data client configuration options

Execution client configuration options

The most common use case is to configure a live TradingNode with Binance data and execution clients. Add a BINANCE section to your client configuration:

from nautilus_trader.adapters.binance import BINANCE
from nautilus_trader.live.node import TradingNode

config = TradingNodeConfig(
    ...,  # Omitted
    data_clients={
        BINANCE: {
            "api_key": "YOUR_BINANCE_API_KEY",
            "api_secret": "YOUR_BINANCE_API_SECRET",
            "account_type": "spot",  # {spot, usdt_futures, coin_futures}
            "base_url_http": None,  # Override with custom endpoint
            "base_url_ws": None,  # Override with custom endpoint
            "us": False,  # If client is for Binance US
        },
    },
    exec_clients={
        BINANCE: {
            "api_key": "YOUR_BINANCE_API_KEY",
            "api_secret": "YOUR_BINANCE_API_SECRET",
            "account_type": "spot",  # {spot, usdt_futures, coin_futures}
            "base_url_http": None,  # Override with custom endpoint
            "base_url_ws": None,  # Override with custom endpoint
            "us": False,  # If client is for Binance US
        },
    },
)

Then, create a TradingNode and add the client factories:

from nautilus_trader.adapters.binance import BINANCE
from nautilus_trader.adapters.binance import BinanceLiveDataClientFactory
from nautilus_trader.adapters.binance import BinanceLiveExecClientFactory
from nautilus_trader.live.node import TradingNode

# Instantiate the live trading node with a configuration
node = TradingNode(config=config)

# Register the client factories with the node
node.add_data_client_factory(BINANCE, BinanceLiveDataClientFactory)
node.add_exec_client_factory(BINANCE, BinanceLiveExecClientFactory)

# Finally build the node
node.build()

Key types

Binance supports three API key types: Ed25519, HMAC-SHA256, and RSA. The adapter auto-detects the key type from your API secret format, so no configuration is needed.

Ed25519 is strongly recommended. Binance recommends Ed25519 for its superior performance and security. A future version of NautilusTrader will require Ed25519 exclusively.

Generating Ed25519 keys

Option 1: OpenSSL (recommended)

# Generate private key (PKCS#8 PEM format)
openssl genpkey -algorithm ed25519 -out binance_ed25519_private.pem

# Extract public key
openssl pkey -in binance_ed25519_private.pem -pubout -out binance_ed25519_public.pem

Option 2: Binance Key Generator

Download the Binance Asymmetric Key Generator from the releases page and run it to generate a keypair.

Registering with Binance

1. Log in to Binance and go to Profile → API Management
2. Click Create API and select Self-generated
3. Paste the contents of your public key file (including the -----BEGIN PUBLIC KEY----- header/footer)
4. Configure permissions (Enable Spot & Margin Trading, etc.)

Using with NautilusTrader

Set the private key as your API secret:

export BINANCE_API_KEY="your-api-key-from-binance"
export BINANCE_API_SECRET="$(cat binance_ed25519_private.pem)"

Or pass the PEM content directly in your configuration.

API credentials

Pass credentials directly to the configuration objects, or set the appropriate environment variables (see Environments for per-environment variables).

When the trading node starts, you receive confirmation of whether your credentials are valid and have trading permissions.

Account type

Set account_type using the BinanceAccountType enum:

• SPOT
• USDT_FUTURES (USDT or BUSD stablecoins as collateral)
• COIN_FUTURES (other cryptocurrency as collateral)

Base URL overrides

Override the default base URLs for both HTTP REST and WebSocket APIs. This is useful for configuring API clusters or when Binance has provided specialized endpoints.

Binance US

Set us=True in the config to use Binance US endpoints (False by default). All functionality available to US accounts behaves identically to standard Binance.

Environments

Binance provides three trading environments, each with separate API credentials and endpoints. The environment config option selects which to use.

Live (production)

The default environment for live trading with real funds. Uses your main Binance account credentials.

config = BinanceExecClientConfig(
    api_key="YOUR_API_KEY",
    api_secret="YOUR_API_SECRET",
    account_type=BinanceAccountType.SPOT,
    # environment=BinanceEnvironment.LIVE (default)
)

Demo trading

Practice trading with simulated funds on production infrastructure. Demo accounts use the same Binance login as your live account but trade with virtual balances. This is the recommended environment for integration testing, especially for futures.

How to get demo credentials:

1. Log in at binance.com/en/demo-trading.
2. Go to API Management and create a demo API key.
3. Demo keys work for both Spot and Futures on demo endpoints.

config = BinanceExecClientConfig(
    api_key="YOUR_DEMO_API_KEY",
    api_secret="YOUR_DEMO_API_SECRET",
    account_type=BinanceAccountType.USDT_FUTURES,
    environment=BinanceEnvironment.DEMO,
)

Testnet

A separate test network with its own user accounts, balances, and order books. Spot testnet is at testnet.binance.vision. The futures testnet at testnet.binancefuture.com now redirects to demo; use environment="DEMO" for futures testing instead.

How to get Spot testnet credentials:

1. Go to testnet.binance.vision.
2. Log in with GitHub.
3. Generate an API key (HMAC, RSA, or Ed25519).

Futures testnet: Binance has merged the futures testnet into the demo environment. If you need to test futures, use environment="DEMO" with demo credentials instead.

config = BinanceExecClientConfig(
    api_key="YOUR_TESTNET_API_KEY",
    api_secret="YOUR_TESTNET_API_SECRET",
    account_type=BinanceAccountType.SPOT,
    environment=BinanceEnvironment.TESTNET,
)

Aggregated trades

Binance provides aggregated trade data endpoints as an alternative source of trades. Unlike the default trade endpoints, aggregated trade endpoints can return all ticks between a start_time and end_time.

Set use_agg_trade_ticks=True to use aggregated trades (False by default).

Commission rate queries

By default, Binance Futures instruments use fee tier tables based on your VIP level. For market maker accounts with negative maker fees or when precise rates are required, enable per-symbol commission rate queries:

from nautilus_trader.adapters.binance import BinanceInstrumentProviderConfig

instrument_provider=BinanceInstrumentProviderConfig(
    load_all=True,
    query_commission_rates=True,  # Query accurate rates per symbol
)

When enabled, the adapter queries Binance's /fapi/v1/commissionRate endpoint for each symbol in parallel during instrument loading. Useful for:

• Market maker accounts with negative maker fees.
• Accounts with custom fee arrangements.
• Exact commission rates for PnL calculations.

The adapter uses parallel requests with rate limiting (120 requests/minute, accounting for the endpoint's weight of 20). If a query fails, it falls back to the fee tier table.

Parser warnings

Some Binance instruments cannot be parsed into Nautilus objects if they contain field values beyond what the platform handles. These instruments are skipped with a warning.

To suppress these warnings:

from nautilus_trader.config import InstrumentProviderConfig

instrument_provider=InstrumentProviderConfig(
    load_all=True,
    log_warnings=False,
)

Futures hedge mode

Binance Futures Hedge mode allows holding both long and short positions on the same instrument simultaneously.

To use hedge mode:

• 1. Configure hedge mode on Binance before starting the strategy.
• 2. Set use_reduce_only=False in BinanceExecClientConfig (True by default).

  from nautilus_trader.adapters.binance import BINANCE
  
  config = TradingNodeConfig(
      ...,  # Omitted
      data_clients={
          BINANCE: BinanceDataClientConfig(
              api_key=None,  # 'BINANCE_API_KEY' env var
              api_secret=None,  # 'BINANCE_API_SECRET' env var
              account_type=BinanceAccountType.USDT_FUTURES,
              base_url_http=None,  # Override with custom endpoint
              base_url_ws=None,  # Override with custom endpoint
          ),
      },
      exec_clients={
          BINANCE: BinanceExecClientConfig(
              api_key=None,  # 'BINANCE_API_KEY' env var
              api_secret=None,  # 'BINANCE_API_SECRET' env var
              account_type=BinanceAccountType.USDT_FUTURES,
              base_url_http=None,  # Override with custom endpoint
              base_url_ws=None,  # Override with custom endpoint
              use_reduce_only=False,  # Must be disabled for Hedge mode
          ),
      }
  )

• 3. When submitting an order, use the LONG or SHORT suffix in position_id to indicate position direction.

  class EMACrossHedgeMode(Strategy):
      ...,  # Omitted
      def buy(self) -> None:
          order: MarketOrder = self.order_factory.market(
              instrument_id=self.instrument_id,
              order_side=OrderSide.BUY,
              quantity=self.instrument.make_qty(self.trade_size),
              # time_in_force=TimeInForce.FOK,
          )
  
          # LONG suffix is recognized as a long position by Binance adapter.
          position_id = PositionId(f"{self.instrument_id}-LONG")
          self.submit_order(order, position_id)
  
      def sell(self) -> None:
          order: MarketOrder = self.order_factory.market(
              instrument_id=self.instrument_id,
              order_side=OrderSide.SELL,
              quantity=self.instrument.make_qty(self.trade_size),
              # time_in_force=TimeInForce.FOK,
          )
          # SHORT suffix is recognized as a short position by Binance adapter.
          position_id = PositionId(f"{self.instrument_id}-SHORT")
          self.submit_order(order, position_id)

Contributing