Installations
npm install @binance/connector
Developer Guide
Typescript
No
Module System
CommonJS
Min. Node Version
>=12.22.3
Node Version
16.20.2
NPM Version
8.19.4
Score
80.5
Supply Chain
99.6
Quality
79.9
Maintenance
100
Vulnerability
100
License
Releases
Contributors
Languages
JavaScript (99.95%)
Shell (0.05%)
validate.email 🚀
Verify real, reachable, and deliverable emails with instant MX records, SMTP checks, and disposable email detection.
Developer
binance
Download Statistics
Total Downloads
534,643
Last Day
360
Last Week
2,858
Last Month
21,773
Last Year
165,351
GitHub Statistics
MIT License
622 Stars
54 Commits
180 Forks
10 Watchers
2 Branches
16 Contributors
Updated on Mar 11, 2025
Bundle Size
78.56 kB
Minified
22.37 kB
Minified + Gzipped
Package Meta Information
Latest Version
3.6.1
Package Id
@binance/connector@3.6.1
Unpacked Size
207.55 kB
Size
30.22 kB
File Count
42
NPM Version
8.19.4
Node Version
16.20.2
Published on
Jan 08, 2025
Total Downloads
Cumulative downloads
Total Downloads
534,643
Last Day
-34.1%
360
Compared to previous day
Last Week
-21.1%
2,858
Compared to previous week
Last Month
-53.4%
21,773
Compared to previous month
Last Year
-36.5%
165,351
Compared to previous year
Daily Downloads
Weekly Downloads
Monthly Downloads
Yearly Downloads
Binance connector in Nodejs
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
Installation
1npm install @binance/connector
Documentation
https://binance.github.io/binance-connector-node/
RESTful APIs
1const { Spot } = require('@binance/connector') 2 3const apiKey = '' 4const apiSecret = '' 5const client = new Spot(apiKey, apiSecret) 6 7// Get account information 8client.account().then(response => client.logger.log(response.data)) 9 10// Place a new order 11client.newOrder('BNBUSDT', 'BUY', 'LIMIT', { 12 price: '350', 13 quantity: 1, 14 timeInForce: 'GTC' 15}).then(response => client.logger.log(response.data)) 16 .catch(error => client.logger.error(error))
Please find examples
folder to check for more endpoints.
Key Pair Based Authentication
1const { Spot, PrivateKeyAlgo } = require('@binance/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' 9const privateKeyAlgo = PrivateKeyAlgo.RSA // for RSA key 10const privateKeyAlgo = PrivateKeyAlgo.ED25519 // for Ed25519 key 11 12const client = new Spot(apiKey, apiSecret, { 13 privateKey, 14 privateKeyPassphrase, // only used for encrypted key 15 privateKeyAlgo 16}) 17 18// Get account information 19client.account().then(response => client.logger.log(response.data))
Testnet
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:
1// provide the testnet base url 2const client = new Spot(apiKey, apiSecret, { baseURL: 'https://testnet.binance.vision'})
Base URL
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
https://api2.binance.com
https://api3.binance.com
Optional Parameters
Optional parameters are encapsulated to a single object as the last function parameter.
1const { Spot } = require('@binance/connector') 2 3const apiKey = '' 4const apiSecret = '' 5const client = new Spot(apiKey, apiSecret) 6 7client.account({ recvWindow: 2000 }).then(response => client.logger.log(response.data))
Time Unit
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:
1const { Spot, TimeUnit } = require('@binance/connector') 2 3const apiKey = '' 4const apiSecret = '' 5const client = new Spot(apiKey, apiSecret) 6 7// Using milliseconds (default) 8client.exchangeInfo({ timeUnit: TimeUnit.MILLISECOND }).then(response => client.logger.log(response.data)) 9 10// Using microseconds 11client.exchangeInfo({ timeUnit: TimeUnit.MICROSECOND }).then(response => client.logger.log(response.data))
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 { Spot } = require('@binance/connector') 2 3const apiKey = '' 4const apiSecret = '' 5const client = new Spot(apiKey, apiSecret, { timeout: 1000 }) 6 7client.account() 8 .then(response => client.logger.log(response.data)) 9 .catch(error => client.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 { Spot } = require('@binance/connector') 2 3const apiKey = '' 4const apiSecret = '' 5const client = new Spot(apiKey, apiSecret, 6 { 7 proxy: { 8 protocol: 'https', 9 host: '127.0.0.1', 10 port: 9000, 11 auth: { 12 username: 'proxy_user', 13 password: 'password' 14 } 15 } 16 } 17)
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 client = new Spot(null, null, 11 { 12 baseURL: "https://api.binance.com", 13 httpsAgent: agent 14 } 15) 16 17client.time() 18 .then(response => client.logger.log(response.data)) 19 .catch(error => client.logger.error(error)) 20
This comment provides more details.
Response Metadata
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']))
Custom Logger Integration
1const Spot = require('@binance/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 client = new Spot('', '', {logger: logger}) 11 12client.exchangeInfo().then(response => client.logger.log(response.data)) 13// check the output file 14
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.
- Response header - Please refer to
// 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 })
- This is thrown when server returns
-
Server error
- This is thrown when server returns
5XX
, it's an issue from server side.
- This is thrown when server returns
Websocket
Websocket Stream
1const { WebsocketStream } = require('@binance/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// initialize websocket stream with microseconds as the preferred time unit 12const websocketStreamClient = new WebsocketStream({ logger, callbacks, timeUnit: TimeUnit.MICROSECOND }) 13// subscribe ticker stream 14websocketStreamClient.ticker('bnbusdt') 15// close websocket stream 16setTimeout(() => websocketStreamClient.disconnect(), 6000)
Unsubscribe Websocket Stream
1// unsubscribe websocket stream 2websocketStreamClient.unsubscribe('bnbusdt@kline_1m')
WebSocket API
1const { WebsocketAPI, TimeUnit } = require('@binance/connector') 2const logger = new Console({ stdout: process.stdout, stderr: process.stderr }) 3 4// callbacks for different events 5const callbacks = { 6 open: (client) => { 7 logger.debug('Connected with Websocket server') 8 // send message to get orderbook info after connection open 9 client.orderbook('BTCUSDT') 10 client.orderbook('BNBUSDT', { limit: 10 }) 11 }, 12 close: () => logger.debug('Disconnected with Websocket server'), 13 message: data => logger.info(data) 14} 15 16// initialize WebsocketAPI client with microseconds as the preferred time unit 17const websocketAPIClient = new WebsocketAPI(null, null, { logger, callbacks, timeUnit: TimeUnit.MICROSECOND }) 18 19// disconnect the connection 20setTimeout(() => websocketAPIClient.disconnect(), 20000) 21
More websocket examples are available in the examples
folder
Auto Reconnect
If there is a close event not initiated by the user, the reconnection mechanism will be triggered in 5 secs.
Ping Server
It is possible to ping server from client, and expect to receive a PONG message.
1websocketStreamClient.pingServer()
Custom Logger Integration
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.
Note that when the connection is initialized, the console outputs a list of callbacks in the form of listen to event: <event_name>
.
Test
1npm install 2 3npm run test 4
Limitation
Futures and Vanilla Options APIs are not supported:
/fapi/*
/dapi/*
/vapi/*
- Associated Websocket Market and User Data Streams
License
MIT

No vulnerabilities found.
Reason
no dangerous workflow patterns detected
Reason
no binaries found in the repo
Reason
license file detected
Details
- Info: project has a license file: LICENSE.md:0
- Info: FSF or OSI recognized license: MIT License: LICENSE.md:0
Reason
Found 15/17 approved changesets -- score normalized to 8
Reason
2 existing vulnerabilities detected
Details
- Warn: Project is vulnerable to: GHSA-968p-4wvh-cqc8
- Warn: Project is vulnerable to: GHSA-jr5f-v2jv-69x6
Reason
4 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 3
Reason
detected GitHub workflow tokens with excessive permissions
Details
- Warn: no topLevel permission defined: .github/workflows/node.js.yml:1
- Info: no jobLevel write permissions found
Reason
dependency not pinned by hash detected -- score normalized to 0
Details
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/node.js.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/binance/binance-connector-node/node.js.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/node.js.yml:21: update your workflow using https://app.stepsecurity.io/secureworkflow/binance/binance-connector-node/node.js.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/node.js.yml:34: update your workflow using https://app.stepsecurity.io/secureworkflow/binance/binance-connector-node/node.js.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/node.js.yml:35: update your workflow using https://app.stepsecurity.io/secureworkflow/binance/binance-connector-node/node.js.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/node.js.yml:41: update your workflow using https://app.stepsecurity.io/secureworkflow/binance/binance-connector-node/node.js.yml/master?enable=pin
- Warn: npmCommand not pinned by hash: .github/workflows/node.js.yml:26
- Warn: npmCommand not pinned by hash: .github/workflows/node.js.yml:39
- Info: 0 out of 4 GitHub-owned GitHubAction dependencies pinned
- Info: 0 out of 1 third-party GitHubAction dependencies pinned
- Info: 0 out of 2 npmCommand dependencies pinned
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
security policy file not detected
Details
- Warn: no security policy file detected
- Warn: no security file to analyze
- Warn: no security file to analyze
- Warn: no security file to analyze
Reason
project is not fuzzed
Details
- Warn: no fuzzer integrations found
Reason
SAST tool is not run on all commits -- score normalized to 0
Details
- Warn: 0 commits out of 30 are checked with a SAST tool
Score
4.7
/10
Last Scanned on 2025-03-10
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn MoreOther packages similar to @binance/connector
@binance-chain/bsc-connector
A simple, maximally extensible, dependency minimized framework for building modern Bsc dApps
binance-futures-connector
binance-futures-spot 币安-合约+现货-sdk,持续更新,欢迎PR一起完善。微信:wkc19891
@gm-network/binance-connector
gm-network sdk
@binance/connector-typescript
This is a lightweight library that works as a connector to the Binance public API.