Binance Spot Trade Connector

Features

crypto-binancewsConnector Key

Instruments

FX

Request Types

SUBMITCANCEL

Order Types

MARKETLIMITSTOPSTOP_LIMIT

Time In Force

GTCIOCFOK

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 proper connector's 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.

Rate Limits

Rate limits available via the following public REST API request: https://api.binance.com/api/v3/exchangeInfo

• The /api/v3/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.

Filters and Errors

Filters define trading rules on a symbol or an exchange.

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

Exchange and symbol filters information can be retrieved via public REST API: https://api.binance.com/api/v3/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) &lt;= 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 stream.binance.com 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 does not close the WebSocket channel for other connections using the same key, but makes them stale. Other connections can detect an inactive Listen Key only via a Keepalive request.

To avoid such issues, the connector does not close the Listen Key on disconnect.

Symbology

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

Symbol list can be retrieved via public REST API: https://api.binance.com/api/v3/exchangeInfo

Configuration

Connector settings

Parameter	Default Value	Description
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	15 minutes	Keep Alive 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	5 seconds	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.
binanceSyncSettings.ordersRequestSizeLimit	200	Limitation for the number of orders in the all orders history response. Maximum value is 1000.
binanceSyncSettings.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 LIMIT and LIMIT_MAKER order types. Possible values: 6.
6100	Stop order type can be changed with 6100 (StopOrderType) attribute. Possible values: StopLoss or TakeProfit. Default value is StopLoss.
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.

Config sample

connectors {
    BINANCEWS: ${template.connector.crypto.binancews} {
        settings {
            websocketUrl = "wss://ws-api.binance.com:443/ws-api/v3"

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