NodeJS Binance Futures Connector

This is a lightweight library that works as a connector to the UM and CM Binance Futures Endpoints. It’s designed to be simple, clean, and easy to use with minimal dependencies.

• Supported APIs:
  • /fapi/*
  • /dapi/*
  • UM Futures Websocket Market Stream
  • CM Futures Websocket Market Stream
  • UM Futures User Data Stream
  • CM Futures User Data Stream
• Inclusion of examples
• Customisable base URL
• Support request timeout and HTTP proxy
• Response metadata can be displayed
• Customisable Logger

Installation

1npm install @binance/futures-connector

Documentation

https://binance.github.io/binance-futures-connector-node/

RESTful APIs

1const { CMFutures } = require("@binance/futures-connector");
2
3const apiKey = "";
4const apiSecret = "";
5const cmFuturesClient = new CMFutures(apiKey, apiSecret, {
6  baseURL: "https://dapi.binance.com",
7});
8
9cmFuturesClient
10  .newOrder("BNBUSD_PERP", "BUY", "LIMIT", {
11    timeInForce: "GTC",
12    quantity: 1,
13    price: 0.001,
14  })
15  .then((response) => console.log(response))
16  .catch(console.error);

Please find examples folder to see the examples for more endpoints.

RSA Key based Authentication

1const { UMFutures } = require("@binance/futures-connector");
2
3const apiKey = "";
4const apiSecret = ""; // has no effect when RSA private key is provided
5
6// load private key
7const privateKey = fs.readFileSync("/Users/john/ssl/private_key_encrypted.pem");
8const privateKeyPassphrase = "password";
9
10const umFuturesClient = new UMFutures(apiKey, apiSecret, {
11  privateKey,
12  privateKeyPassphrase, // only used for encrypted key
13});
14
15// Get account information
16umFuturesClient
17  .getAccountInformation()
18  .then((response) => client.logger.log(response.data));

Testnet

You can use the testnet by adjusting the base URL:

1// provide the testnet base url
2const umFuturesClient = new UMFutures(apiKey, apiSecret, {
3  baseURL: "https://testnet.binancefuture.com",
4});

Base URL

If baseURL is not provided, it defaults to fapi.binance.com.

It's recommended to pass in the baseURL parameter to the constructor, so that it can easily be replaced with the testnet baseURL for testing/debugging.

1
2```javascript
3
4### Optional Parameters
5
6Optional parameters are encapsulated to a single object as the last function parameter.
7
8```javascript
9const { UMFutures } = require('@binance/futures-connector')
10
11const apiKey = ''
12const apiSecret = ''
13const client = new Spot(apiKey, apiSecret)
14
15umFuturesClient.getAccountInformation({ recvWindow: 2000 }).then(response => umFuturesClient.logger.log(response.data))
16

Timeout

It's easy to set timeout in milliseconds in request. If the request take longer than timeout, the request will be aborted. If it's not set, there will be no timeout.

1const { UMFutures } = require("@binance/futures-connector");
2
3const apiKey = "";
4const apiSecret = "";
5const umFuturesClient = new UMFutures(apiKey, apiSecret, { timeout: 1000 });
6
7client
8  .getAccountInformation()
9  .then((response) => umFuturesClient.logger.log(response.data))
10  .catch((error) => umFuturesClient.logger.error(error.message));

Proxy

The axios package is used as the http client in this library. A proxy settings is passed into axios directly, the details can be found at here:

1const { UMFutures } = require("@binance/futures-connector");
2
3const apiKey = "";
4const apiSecret = "";
5const umFuturesClient = new UMFutures(apiKey, apiSecret, {
6  proxy: {
7    protocol: "https",
8    host: "127.0.0.1",
9    port: 9000,
10    auth: {
11      username: "proxy_user",
12      password: "password",
13    },
14  },
15});

You may have a HTTP proxy, that can bring the problem that you need to make a HTTPS connection through the HTTP proxy. You can do that by build a HTTPS-over-HTTP tunnel by npm package tunnel, and then pass the turnnel agent to httpsAgent in axios.

1const tunnel = require("tunnel");
2
3const agent = tunnel.httpsOverHttp({
4  proxy: {
5    host: "127.0.0.1",
6    port: 3128,
7  },
8});
9
10const umFuturesClient = new UMFutures(null, null, {
11  baseURL: "https://fapi.binance.com",
12  httpsAgent: agent,
13});
14
15umFuturesClient
16  .getAccountInformation()
17  .then((response) => umFuturesClient.logger.log(response.data))
18  .catch((error) => umFuturesClient.logger.error(error));

This comment provides more details.

Custom Logger Integration

1const { UMFutures } = require("@binance/futures-connector");
2const fs = require("fs");
3const { Console } = require("console");
4
5// make sure the logs/ folder is created beforehand
6const output = fs.createWriteStream("./logs/stdout.log");
7const errorOutput = fs.createWriteStream("./logs/stderr.log");
8
9const logger = new Console({ stdout: output, stderr: errorOutput });
10const umFuturesClient = new UMFutures("", "", { logger: logger });
11
12umFuturesClient
13  .getExchangeInfo()
14  .then((response) => umFuturesClient.logger.log(response.data));
15// check the output file

The default logger defined in the package is Node.js Console class. Its output is sent to process.stdout and process.stderr, same as the global console.

Error

There are 2 types of error that may be returned from the API server and the user has to handle it properly:

• Client error

  • This is thrown when server returns 4XX, it's an issue from client side.
  • The following properties may be helpful to resolve the issue:
    • Response header - Please refer to Response Metadata section for more details.
    • HTTP status code
    • Error code - Server's error code, e.g. -1102
    • Error message - Server's error message, e.g. Unknown order sent.
    • Request config - Configuration send to the server, which can include URL, request method and headers.

  // client initialization is skipped
  client.exchangeInfo({ symbol: 'invalidSymbol' })
    .then(response => client.logger.log(response.data))
    .catch(err => {
      client.logger.error(err.response.headers) // full response header
      client.logger.error(err.response.status) // HTTP status code 400
      client.logger.error(err.response.data) // includes both error code and message
      client.logger.error(err.response.config) // includes request's config
    })
  
  

• Server error

  • This is thrown when server returns 5XX, it's an issue from server side.

Websocket

The WebSocket URLs for the available futures environments are as follows:

• Testnet CM: wss://dstream.binancefuture.com
• Testnet UM: wss://stream.binancefuture.com
• Main CM: wss://dstream.binance.com
• Main UM: wss://fstream.binance.com

Websocket Streams

You can connect to the WebSocket stream using the UMStream Module (for USD-M Futures). Here is an example:

1const { UMStream } = require("@binance/futures-connector");
2const logger = new Console({ stdout: process.stdout, stderr: process.stderr });
3
4// Define callbacks for different events
5const callbacks = {
6  open: () => logger.debug("Connected with Websocket server"),
7  close: () => logger.debug("Disconnected with Websocket server"),
8  message: (data) => logger.info(data),
9};
10
11// Create a new WebSocket client with the wsURL (Websocket URL) defined
12const umWebsocketStreamClient = new UMStream({
13  logger,
14  callbacks,
15  wsURL: "wss://fstream.binance.com",
16});
17
18// Subscribe to the allMarketMiniTickersStream stream
19umWebsocketStreamClient.allMarketMiniTickersStream("bnbusdt_perp");
20
21// Close the WebSocket stream after 6 seconds
22setTimeout(() => umWebsocketStreamClient.disconnect(), 6000);

Unsubscribe Websocket Stream

You can unsubscribe from a WebSocket stream as follows:

1umWebsocketStreamClient.unsubscribe("bnbusdt_perp@kline_1m");

License

MIT