Binance Futures Trade Connector

Features

crypto-binancewsfutConnector Key

Instruments

FUTURE

Request Types

SUBMITCANCELREPLACE

Order Types

MARKETLIMIT

Time In Force

GTCIOCFOKGOOD_TILL_CROSSINGGTD

Order ID Mapper

SEQUENCE

✗

Order Status Request

✗

Cancel On Disconnect

✓

Commission

✓

Post Only

✓

Fast Cancel

✗

Fast Replace

Notes

API Key Permissions

Binance API-keys can be configured to only access certain types of secure endpoints.

The following Security Types for API key must be enabled for connector's proper functionality:

• TRADE
• USER_DATA
• USER_STREAM

API Key Types

Two types of API Keys are supported: HMAC and Ed25519.

• How to Generate an Ed25519 Key Pair

The connector first attempts to use the provided apiSecret as an Ed25519 key. If that fails, it falls back to using apiSecret for HMAC signature computation.

Important: The Ed25519 private key must contain -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- parts. It can be configured as a single-line parameter using # as a line separator.

WebSocket API Authentication

Binance supports authenticating a WebSocket connection using an Ed25519 API key. After successful authentication, subsequent requests may omit the signature calculation.

Important: Only the Ed25519 API key type is supported for WebSocket authentication. The connector uses the first Ed25519 API key found in the settings to sign the authentication request. If no Ed25519 API keys are provided, the connector signs every WebSocket request individually.

Time In Force

GOOD_TILL_DATE time in force is supported by Binance Futures (USDT-Futures) only.

Replacement

Order Replacement limitations:

When the new quantity or price doesn't satisfy PRICE_FILTER / PERCENT_FILTER / LOT_SIZE, amendment will be rejected and the order will stay as it is.

However the order will be cancelled by the amendment in the following situations:

• when the order is in partially filled status and the new quantity <= executedQty
• when the order is GTX and the new price will cause it to be executed immediately

One order can only be modified for less than 10000 times

Modify order will set selfMatchPreventionInstruction to NONE

Rate Limits

Rate limits available via the following public REST API request:

• Futures (USDT-Futures): https://fapi.binance.com/fapi/v1/exchangeInfo
• Delivery Futures (Coin-Futures): https://dapi.binance.com/dapi/v1/exchangeInfo

Rate limit rules:

• The /fapi/v1/exchangeInfo or /dapi/v1/exchangeInfo rateLimits array contains objects related to the exchange's RAW_REQUEST, REQUEST_WEIGHT, and ORDER rate limits.
• A 429 is returned when either rate limit is violated.
• Each route has a weight which determines for the number of requests each endpoint counts for. Heavier endpoints and endpoints that do operations on multiple symbols will have a heavier weight.
• When a 429 is received, it's your obligation as an API to back off and not spam the API.
• Repeatedly violating rate limits and/or failing to back off after receiving 429s will result in an automated IP ban (http status 418).
• IP bans are tracked and scale in duration for repeat offenders, from 2 minutes to 3 days.
• The limits on the API are based on the IPs, not the API keys.
• The order rate limit is counted against each account.
• Note: The connector does not currently track rate limit usage.

Client Order ID

Allowed characters: ., A-Z, :, /, a-z, 0-9, _, -. Maximum length is 36 characters.

Source and format of the Client Order ID are controlled by the orderMapperType setting:

Order Mapper Type	Client Order ID source	Rules and Restrictions
SEQUENCE	Order request's sequence number	sequence is numeric. clientOrderIdPrefix setting can be used for customization.
COMPOSITE	Order request's sourceId and orderId	sourceId and orderId are concatenated with ':' delimiter. Important: ':' cannot be used in sourceId. clientOrderIdPrefix is not applied to the Client Order ID.

Position Mode

Binance Futures exchange supports One-Way and Hedge position mode.

In Hedge mode it is possible to go long and short on the same contracts at the same time. Thus, traders can maintain long-term positions while participating in short-term movements.

To switch position mode, use the Binance exchange GUI directly. The trade connector does not support switching position modes.

Position Side

When Hedge mode is enabled, specify the position side for each order via 6200 (PositionSide) attribute. Allowed values per position mode:

Position Mode	Position Side
One-Way	BOTH
Hedge	LONG, SHORT

PostOnly Orders

Binance Futures exchange supports PostOnly LIMIT orders with TimeInForce = GTX (GOOD TILL CROSSING) only.

PostOnly order can be submitted in two ways:

• LIMIT order request with TimInForce = GOOD TILL CANCEL and 18 (PostOnly) tag set to 6. Order will be sent to Binance with TimeInForce = GTX.
• LIMIT order request with TimInForce = GOOD TILL CROSSING with or without 18 (PostOnly) tag.

Requests with other TimInForce values and 18 (PostOnly) tag set to 6 will be rejected for LIMIT orders.

ReduceOnly Orders

To close a position, the ReduceOnly option can be used. The option cannot be used in Hedge position mode because close position orders in Hedge mode always act as ReduceOnly.

Close position orders in One-Way position mode are controlled by 6201 (ReduceOnly) tag.

Close position quantity cannot be greater than the open position size. When a ReduceOnly order quantity is greater than the open position, the exchange accepts the order but reduces the order quantity to the actual open position quantity. After this reduced quantity is completely filled, the remaining order quantity is cancelled by the connector.

Position Mode, Position Side and ReduceOnly interaction

One-Way Position Mode

Positions have BOTH type. Actual position type is represented by the sign of a position size: positive means long, negative means short.

Execution of an order that reduces position size (a close position order) will result in position type change if the executed order amount is greater than the position size. ReduceOnly option helps to prevent this behaviour.

Sample order executions with the ReduceOnly option:

Open Position	Order	ReduceOnly	Resulting Position*	Notes
1000	1000 BUY	false	2000
1000	1000 SELL	false	0
1000	3000 BUY	false	4000
1000	3000 SELL	false	-2000	Actual position type changes from long to short
1000	1000 BUY	true	1000	The exchange rejects such orders
1000	1000 SELL	true	0
1000	3000 BUY	true	1000	The exchange rejects such orders
1000	3000 SELL	true	0	1000 is executed, 2000 is cancelled by the connector

* Position size after order execution

Hedge Position Mode

Positions have LONG and SHORT type. They can exist simultaneously.

Execution of an order that reduces position size (a close position order) will result in the position size change, but not lower than 0. Since each such order acts as a ReduceOnly order in One-Way mode, ReduceOnly option is redundant in Hedge mode and is not permitted by the exchange.

Filters and Errors

Filters define trading rules on a symbol or an exchange.

• https://binance-docs.github.io/apidocs/futures/en/#filters
• https://binance-docs.github.io/apidocs/futures/en/#error-codes-2

Exchange and symbol filters information can be retrieved via public REST API:

• Futures (USDT-Futures): https://fapi.binance.com/fapi/v1/exchangeInfo
• Delivery Futures (Coin-Futures): https://dapi.binance.com/dapi/v1/exchangeInfo

Timing Security

If the recvWindow connector setting is 0, the recvWindow parameter is omitted from requests.

From the exchange specification:

A SIGNED endpoint also requires a parameter, timestamp, to be sent which should be the millisecond timestamp of when the request was created and sent. An additional parameter, recvWindow, may be sent to specify the number of milliseconds after timestamp the request is valid for. If recvWindow is not sent, it defaults to 5000. The logic is as follows:

if (timestamp < (serverTime + 1000) && (serverTime - timestamp) <= recvWindow) {
   // process request
} else {
   // reject request
}

It's recommended to use a small recvWindow of 5_000 or less. The max cannot go beyond 60_000.

WebSocket

A single connection to every WebSocket channel is only valid for 24 hours; expect to be disconnected at the 24 hour mark

Important: Binance reuses the WebSocket Listen Key across connections sharing the same Api Key (and possibly within the same account). Closing a Listen Key for one connection closes the WebSocket channel for all other connections using the same key.

To avoid unintended disconnections, the connector does not close the Listen Key on disconnect.

Binance Delivery Futures (Coin-Futures)

Delivery Futures (Coin-Futures) uses the same API format as Futures (USDT-Futures), but with different REST and WebSocket URLs.

To configure the connector for Delivery Futures (Coin-Futures), see the Config sample section.

Streams URL

Default values for streamsUrl setting:

• Futures (USDT-Futures): wss://fstream.binance.com
• Delivery Futures (Coin-Futures): wss://dstream.binance.com

Symbology

Currency pairs without separator, uppercase required, e.g. BTCUSDT, LTCUSDT.

Symbol lists are available via public REST API:

• Futures (USDT-Futures): https://fapi.binance.com/fapi/v1/exchangeInfo
• Delivery Futures (Coin-Futures): https://dapi.binance.com/dapi/v1/exchangeInfo

Configuration

Connector settings

Parameter	Default Value	Description
streamsUrl		Base URL for User Data Streams Websocket connection. See Streams URL section for detailed values.
recvWindow		If recvWindow is not sent, it defaults to 5000. It's recommended to use a small recvWindow of 5_000 or less. The max cannot go beyond 60_000. See Timing security section for detailed explanation.
websocketHeartbeatInterval	15m	Keepalive period for a user data stream. User data streams will close after 60 minutes. It's recommended to send a ping about every 30 minutes.
staleWebsocketTimeout	5s	Timeout for reconnection when no websockets messages received after any order message sent to exchange.
selfMatchPreventionInstruction	CANCEL_RESTING	Optional setting for Self-Trade Prevention function. Supported values: CANCEL_RESTING, CANCEL_TAKING, CANCEL_BOTH.
clientOrderIdPrefix		Optional prefix for Client Order ID. Only the following symbols are accepted by exchange: '.', 'A'-'Z', ':', '/', 'a'-'z', '0'-'9', '_', '-'. See Client Order ID section for detailed explanation.
orderMapperType	SEQUENCE	Type of the mapper which is used to map order to Client Order ID. Supported values: COMPOSITE, SEQUENCE. See Client Order ID section for detailed explanation.
binanceFuturesSyncSettings.ordersRequestSizeLimit	100	Limitation for the number of orders in the all orders history response. Maximum value is 1000 for Futures (USDT-Futures), 100 for Delivery Futures (Coin-Futures).
binanceFuturesSyncSettings.tradesRequestSizeLimit	100	Limitation for the number of trades in the account trade list history response. Maximum value is 1000.

Supported order attributes

Key	Description
18	18 (PostOnly) attribute relevant only for LIMIT orders. Switches between GTC and GTX order time in force. Possible values: 6.
6102	Self-Trade Prevention function mode can be specified for each order via 6102 (SelfTradePreventionMode) attribute. Default value can be specified in connector settings (selfMatchPreventionInstruction). Possible values: EXPIRE_MAKER, EXPIRE_TAKER, EXPIRE_BOTH.
6200	Orders in Hedge position mode should have 6200 (PositionSide) attribute. Possible values: BOTH, LONG, SHORT. See Position Side section for detailed explanation.
6201	reduceOnly switch. Cannot be sent in Hedge position mode. Possible values: true, false. Default: false. See ReduceOnly orders section for detailed explanation.

Config sample

connectors {
    BINWSFUT: ${template.connector.crypto.binancewsfut} {
        settings {
            restUrl = "https://fapi.binance.com"
            websocketUrl = "wss://ws-fapi.binance.com/ws-fapi/v1"
            streamsUrl = "wss://fstream.binance.com/private"

            apiKeys: [
                {
                    apiKey = "<API_KEY>"
                    apiSecret = "<API_SECRET>"
                }
            ]
        }
    }

    BINWSDLV: ${template.connector.crypto.binancewsdlv} {
        settings {
            restUrl = "https://dapi.binance.com"
            websocketUrl = "wss://ws-dapi.binance.com/ws-dapi/v1"
            streamsUrl = "wss://dstream.binance.com"

            apiKeys: [
                {
                    apiKey = "<API_KEY>"
                    apiSecret = "<API_SECRET>"
                }
            ]
        }
    }
}