This is a lightweight library that works as a connector to the Binance public API.
npm install @binance/connector
This is a lightweight library that works as a connector to Binance public API. It’s designed to be simple, clean, and easy to use with minimal dependencies.
- Supported APIs:
- /api/*
- /sapi/*
- Spot Websocket Market Stream
- Spot User Data Stream
- Spot Websocket API
- Inclusion of test cases and examples
- Customizable base URL
- Support request timeout and HTTP proxy (since v2)
- Response metadata can be displayed
- Customizable Logger
``bash`
npm install @binance/connector
https://binance.github.io/binance-connector-node/
`javascript
const { Spot } = require('@binance/connector')
const apiKey = ''
const apiSecret = ''
const client = new Spot(apiKey, apiSecret)
// Get account information
client.account().then(response => client.logger.log(response.data))
// Place a new order
client.newOrder('BNBUSDT', 'BUY', 'LIMIT', {
price: '350',
quantity: 1,
timeInForce: 'GTC'
}).then(response => client.logger.log(response.data))
.catch(error => client.logger.error(error))
`
Please find examples folder to check for more endpoints.
`javascript
const { Spot, PrivateKeyAlgo } = require('@binance/connector')
const apiKey = ''
const apiSecret = '' // has no effect when RSA private key is provided
// load private key
const privateKey = fs.readFileSync('/Users/john/ssl/private_key_encrypted.pem')
const privateKeyPassphrase = 'password'
const privateKeyAlgo = PrivateKeyAlgo.RSA // for RSA key
const privateKeyAlgo = PrivateKeyAlgo.ED25519 // for Ed25519 key
const client = new Spot(apiKey, apiSecret, {
privateKey,
privateKeyPassphrase, // only used for encrypted key
privateKeyAlgo
})
// Get account information
client.account().then(response => client.logger.log(response.data))
`
While /sapi/ endpoints don't have testnet environment yet, /api/ endpoints can be tested in
Spot Testnet. You can use it by changing the base URL:
`javascript`
// provide the testnet base url
const client = new Spot(apiKey, apiSecret, { baseURL: 'https://testnet.binance.vision'})
If base_url is not provided, it defaults to api.binance.com.
It's recommended to pass in the base_url parameter, even in production as Binance provides alternative URLs in case of performance issues:
- https://api1.binance.com
-
-
Optional parameters are encapsulated to a single object as the last function parameter.
`javascript
const { Spot } = require('@binance/connector')
const apiKey = ''
const apiSecret = ''
const client = new Spot(apiKey, apiSecret)
client.account({ recvWindow: 2000 }).then(response => client.logger.log(response.data))
`
The API supports different time units for timestamp values. By default, timestamp values are provided in milliseconds. You can specify the time unit in the request parameters:
`javascript
const { Spot, TimeUnit } = require('@binance/connector')
const apiKey = ''
const apiSecret = ''
const client = new Spot(apiKey, apiSecret)
// Using milliseconds (default)
client.exchangeInfo({ timeUnit: TimeUnit.MILLISECOND }).then(response => client.logger.log(response.data))
// Using microseconds
client.exchangeInfo({ timeUnit: TimeUnit.MICROSECOND }).then(response => client.logger.log(response.data))
`
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.
`javascript
const { Spot } = require('@binance/connector')
const apiKey = ''
const apiSecret = ''
const client = new Spot(apiKey, apiSecret, { timeout: 1000 })
client.account()
.then(response => client.logger.log(response.data))
.catch(error => client.logger.error(error.message))
`
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:
`javascript
const { Spot } = require('@binance/connector')
const apiKey = ''
const apiSecret = ''
const client = new Spot(apiKey, apiSecret,
{
proxy: {
protocol: 'https',
host: '127.0.0.1',
port: 9000,
auth: {
username: 'proxy_user',
password: 'password'
}
}
}
)
`
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.
`javascript
const tunnel = require('tunnel')
const agent = tunnel.httpsOverHttp({
proxy: {
host: "127.0.0.1",
port: 3128
}
})
const client = new Spot(null, null,
{
baseURL: "https://api.binance.com",
httpsAgent: agent
}
)
client.time()
.then(response => client.logger.log(response.data))
.catch(error => client.logger.error(error))
`
This comment provides more details.
The Binance API server provides weight usages in the headers of each response. This information can be fetched from headers property. x-mbx-used-weight and x-mbx-used-weight-1m show the total weight consumed within 1 minute.
`
// client initialization is skipped
client.exchangeInfo().then(response => client.logger.log(response.headers['x-mbx-used-weight-1m']))
`
`javascript
const Spot = require('@binance/connector')
const fs = require('fs')
const { Console } = require('console')
// make sure the logs/ folder is created beforehand
const output = fs.createWriteStream('./logs/stdout.log')
const errorOutput = fs.createWriteStream('./logs/stderr.log')
const logger = new Console({ stdout: output, stderr: errorOutput })
const client = new Spot('', '', {logger: logger})
client.exchangeInfo().then(response => client.logger.log(response.data))
// 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.
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 , it's an issue from client side.Response Metadata
- The following properties may be helpful to resolve the issue:
- Response header - Please refer to section for more details.-1102
- HTTP status code
- Error code - Server's error code, e.g.
- Error message - Server's error message, e.g.
- 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 , it's an issue from server side.
javascript
const { WebsocketStream } = require('@binance/connector')
const logger = new Console({ stdout: process.stdout, stderr: process.stderr })// define callbacks for different events
const callbacks = {
open: () => logger.debug('Connected with Websocket server'),
close: () => logger.debug('Disconnected with Websocket server'),
message: data => logger.info(data)
}
// initialize websocket stream with microseconds as the preferred time unit
const websocketStreamClient = new WebsocketStream({ logger, callbacks, timeUnit: TimeUnit.MICROSECOND })
// subscribe ticker stream
websocketStreamClient.ticker('bnbusdt')
// close websocket stream
setTimeout(() => websocketStreamClient.disconnect(), 6000)
`$3
javascript
// unsubscribe websocket stream
websocketStreamClient.unsubscribe('bnbusdt@kline_1m')
`$3
javascript
const { WebsocketAPI, TimeUnit } = require('@binance/connector')
const logger = new Console({ stdout: process.stdout, stderr: process.stderr })// callbacks for different events
const callbacks = {
open: (client) => {
logger.debug('Connected with Websocket server')
// send message to get orderbook info after connection open
client.orderbook('BTCUSDT')
client.orderbook('BNBUSDT', { limit: 10 })
},
close: () => logger.debug('Disconnected with Websocket server'),
message: data => logger.info(data)
}
// initialize WebsocketAPI client with microseconds as the preferred time unit
const websocketAPIClient = new WebsocketAPI(null, null, { logger, callbacks, timeUnit: TimeUnit.MICROSECOND })
// disconnect the connection
setTimeout(() => websocketAPIClient.disconnect(), 20000)
`More websocket examples are available in the
folder
$3
If there is a close event not initiated by the user, the reconnection mechanism will be triggered in 5 secs.
$3
It is possible to ping server from client, and expect to receive a PONG message.
`javascript
websocketStreamClient.pingServer()
`$3
The default logger defined in the package is Node.js Console class. Its output is sent to
and process.stderr, same as the global console.Note that when the connection is initialized, the console outputs a list of callbacks in the form of
listen to event: .Test
`bash
npm installnpm run test
`Limitation
Futures and Vanilla Options APIs are not supported:
-
-
-