Skip to main content

Binance Spot US Trade Connector

Features​

crypto-binanceusConnector 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​

Binance US supports HMAC API Keys only.

Rate Limits​

Rate limits available via the following public REST API request: https://api.binance.us/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 TypeClient Order ID sourceRules and Restrictions
SEQUENCEOrder request's sequence numbersequence is numeric. clientOrderIdPrefix setting can be used for customization.
COMPOSITEOrder request's sourceId and orderIdsourceId 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.

Exchange and symbol filters information can be retrieved via public REST API: https://api.binance.us/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) <= 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.

note

Binance US reuses the WebSocket Listen Key for different connections with at least 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 with the same Listen Key, but makes them stale. Other connections can catch inactive state of the Listen Key with the Keepalive request only.

To avoid such issues, connector does not close the Listen Key when disconnecting.

Self Trade Prevention​

Default Self Trade Prevention Mode value for specific symbol can be found here: https://api.binance.com/api/v3/exchangeInfo

From the exchange STP Function FAQ:

Symbols may be configured to allow different sets of STP modes and take different default STP modes. defaultSelfTradePreventionMode - Orders will use this STP mode if the user does not provide one on order placement. allowedSelfTradePreventionModes - Defines the allowed set of STP modes for order placement on that symbol.

Symbology​

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

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

Configuration​

Connector settings​

ParameterDefault ValueDescription
recvWindowIf 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.
websocketHeartbeatInterval30mKeepalive 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.
staleWebsocketTimeout5sTimeout for reconnection when no websockets messages received after any order message sent to exchange.
selfTradePreventionModeEXPIRE_MAKEROptional setting for Self-Trade Prevention function. Supported values: EXPIRE_MAKER, EXPIRE_TAKER, EXPIRE_BOTH.
clientOrderIdPrefixOptional 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.
orderMapperTypeSEQUENCEType 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.ordersRequestSizeLimit200Limitation for the number of orders in the all orders history response. Maximum value is 1000.
binanceSyncSettings.tradesRequestSizeLimit100Limitation for the number of trades in the account trade list history response. Maximum value is 1000.

Supported order attributes​

KeyDescription
1818 (PostOnly) attribute relevant only for LIMIT orders. Switches between LIMIT and LIMIT_MAKER order types. Possible values: 6.
6100Stop order type can be changed with 6100 (StopOrderType) attribute. Possible values: StopLoss or TakeProfit. Default value is StopLoss.
6102Self-Trade Prevention function mode can be specified for each order via 6102 (SelfTradePreventionMode) attribute. Default value can be specified in connector settings. Possible values: EXPIRE_MAKER, EXPIRE_TAKER, EXPIRE_BOTH.

Config sample​

connectors {
  BINANCEUS: ${template.connector.crypto.binanceus} {
    settings {
      restUrl = "https://api.binance.us"
      websocketUrl = "wss://stream.binance.us:9443"

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