binance 3.0.0-beta.1 → 3.0.0-beta.11

package/README.md

@@ -21,34 +21,64 @@
 
 Updated & performant JavaScript & Node.js SDK for the Binance REST APIs and WebSockets:
 
-- Extensive integration with Binance REST APIs and WebSockets.
-- TypeScript support (with type declarations for most API requests & responses).
-- Supports Binance REST APIs for Binance Spot, Margin, Isolated Margin, USDM & CoinM Futures.
-  - Strongly typed on most requests and responses.
-  - Automated end-to-end tests on most API calls, ensuring no breaking changes are released.
-- Extremely robust & performant JavaScript/Node.js Binance SDK with significant trading volume in production (livenet).
+- Professional, robust & performant Binance SDK with leading trading volume in production (livenet).
+- Extensive integration with Binance REST APIs, WebSockets & WebSocket APIs.
+- Complete TypeScript support (with type declarations for all API requests & responses).
+- Supports Binance REST APIs for Binance Spot, Margin, Isolated Margin, Options, USDM & CoinM Futures.
+  - Strongly typed requests and responses.
+  - Automated end-to-end tests on most API calls, ensuring no breaking changes are released to npm.
 - Actively maintained with a modern, promise-driven interface.
-- Support for all authentication mechanisms:
+- Support for all authentication mechanisms available on Binance:
   - HMAC
   - RSA
   - Ed25519 (required for WS API).
-  - Passing a private key as a secret will automatically revert to RSA/Ed25519 authentication (depending on key format).
-- Supports Websockets for Binance Spot, Margin, Isolated Margin, USDM & CoinM Futures.
+  - Passing a private key as a secret will automatically detect whether to switch to RSA or Ed25519 authentication.
+- Supports WebSockets for all available product groups on Binance including Spot, Margin, Isolated Margin, Portfolio, Options, USDM & CoinM Futures.
   - Event driven messaging.
-  - Smart websocket persistence
-    - Automatically handle silent websocket disconnections through timed heartbeats, including the scheduled 24hr disconnect.
+  - Smart WebSocket persistence
+    - Automatically handle silent WebSocket disconnections through timed heartbeats, including the scheduled 24hr disconnect.
     - Automatically handle listenKey persistence and expiration/refresh.
     - Emit `reconnected` event when dropped connection is restored.
-  - Strongly typed on most websocket events, with typeguards available for TypeScript users.
+  - Strongly typed on most WebSocket events, with typeguards available for TypeScript users.
   - Optional:
-    - Automatic beautification of Websocket events (from one-letter keys to descriptive words, and strings with floats to numbers).
+    - Automatic beautification of WebSocket events (from one-letter keys to descriptive words, and strings with floats to numbers).
     - Automatic beautification of REST responses (parsing numbers in strings to numbers).
+- Supports WebSocket API on all available product groups, including Spot & Futures:
+  - Use the WebsocketClient's event-driven `sendWSAPIRequest()` method, or;
+  - Use the WebsocketAPIClient for a REST-like experience. Use the WebSocket API like a REST API! See [examples/ws-api-client.ts](./examples/ws-api-client.ts) for a demonstration.
 - Heavy automated end-to-end testing with real API calls.
   - End-to-end testing before any release.
   - Real API calls in e2e tests.
 - Proxy support via axios integration.
 - Active community support & collaboration in telegram: [Node.js Algo Traders](https://t.me/nodetraders).
 
+## Table of Contents
+
+- [Installation](#installation)
+- [Examples](#examples)
+  - [REST API Examples](./examples/REST)
+  - [WebSocket Examples](./examples/WebSockets)
+    - [WebSocket Consumers](./examples/WebSockets/)
+    - [WebSocket API](./examples/WebSockets/ws-api-client.ts)
+- [Issues & Discussion](#issues--discussion)
+- [Related Projects](#related-projects)
+- [Documentation Links](#documentation)
+- [Usage](#usage)
+  - [REST API Clients](#rest-api-clients)
+    - [REST Main Client](#rest-main-client)
+    - [REST USD-M Futures](#rest-usd-m-futures)
+    - [REST COIN-M Futures](#rest-coin-m-futures)
+  - [WebSockets](#websockets)
+    - [WebSocket Consumers](#websocket-consumers)
+    - [WebSocket API](#websocket-api)
+      - [Event Driven API](#event-driven-api)
+      - [Promise Driven API](#async-await-api)
+  - [Customise Logging](#customise-logging)
+  - [Frontend Usage](#browserfrontend-usage)
+    - [Import](#import)
+    - [Webpack](#webpack)
+- [Contributions & Thanks](#contributions--thanks)
+
 ## Installation
 
 `npm install binance --save`
@@ -90,15 +120,12 @@ Check out my related JavaScript/TypeScript/Node.js projects:
 
 Most methods accept JS objects. These can be populated using parameters specified by Binance's API documentation.
 
-- [Binance API Documentation](https://developers.binance.com/docs)
-
+- Binance API Documentation
   - [ Spot ](https://developers.binance.com/docs/binance-spot-api-docs)
   - [ Derivatives ](https://developers.binance.com/docs/derivatives)
   - [ Margin ](https://developers.binance.com/docs/margin_trading)
   - [ Wallet ](https://developers.binance.com/docs/wallet)
-
 - [Find all products here](https://developers.binance.com/en)
-
 - [REST Endpoint Function List](./docs/endpointFunctionList.md)
 - [TSDoc Documentation (autogenerated using typedoc)](https://tsdocs.dev/docs/binance)
 
@@ -117,6 +144,8 @@ This project uses typescript. Resources are stored in 3 key structures:
 Create API credentials at Binance
 
 - [Livenet](https://www.binance.com/en/support/faq/360002502072?ref=IVRLUZJO)
+- [Testnet](https://testnet.binance.vision/).
+- [Testnet Futures](testnet.binancefuture.com).
 
 ## REST API Clients
 
@@ -125,15 +154,40 @@ There are several REST API modules as there are some differences in each API gro
 1. `MainClient` for most APIs, including: spot, margin, isolated margin, mining, BLVT, BSwap, Fiat & sub-account management.
 2. `USDMClient` for USD-M futures APIs.
 3. `CoinMClient` for COIN-M futures APIs.
-
-Vanilla Options connectors are not yet available, though contributions are welcome!
-
-### REST Spot/Margin/etc
-
-Start by importing the spot client. API credentials are optional, though an error is thrown when attempting any private API calls without credentials.
+4. `PortfolioClient` for Portfolio Margin APIs.
+
+Vanilla Options is not yet available. Please get in touch if you're looking for this.
+
+### REST Main Client
+
+The MainClient covers all endpoints under the main "api*.binance.com" subdomains, including but not limited to endpoints in the following product groups:
+- Spot
+- Cross & isolated margin
+- Convert
+- Wallet
+- Futures management (transfers & history)
+- Sub account management
+- Misc transfers
+- Auto & dual invest
+- Staking
+- Mining
+- Loans & VIP loans
+- Simple Earn
+- NFTs
+- C2C
+- Exchange Link
+
+Refer to the following links for a complete list of available endpoints:
+- [Binance Node.js & JavaScript SDK Endpoint Map](https://github.com/tiagosiebler/binance/blob/master/docs/endpointFunctionList.md)
+- [Binance Spot API Docs](https://developers.binance.com/docs/binance-spot-api-docs/rest-api/general-endpoints)
+
+Start by importing the `MainClient` class. API credentials are optional, unless you plan on making private API calls. More Node.js & JavaScript examples for Binance's REST APIs & WebSockets can be found in the [examples](./examples) folder on GitHub.
 
 ```javascript
-const { MainClient } = require('binance');
+import { MainClient } from 'binance';
+
+// or, if you prefer `require()`:
+// const { MainClient } = require('binance');
 
 const API_KEY = 'xxx';
 const API_SECRET = 'yyy';
@@ -141,6 +195,8 @@ const API_SECRET = 'yyy';
 const client = new MainClient({
   api_key: API_KEY,
   api_secret: API_SECRET,
+  // Connect to testnet environment
+  // testnet: true,
 });
 
 client
@@ -162,14 +218,17 @@ client
   });
 ```
 
-See [spot-client.ts](./src/main-client.ts) for further information.
+See [main-client.ts](./src/main-client.ts) for further information on the available REST API endpoints for spot/margin/etc.
 
 ### REST USD-M Futures
 
-Start by importing the usd-m client. API credentials are optional, though an error is thrown when attempting any private API calls without credentials.
+Start by importing the USDM client. API credentials are optional, unless you plan on making private API calls.
 
 ```javascript
-const { USDMClient } = require('binance');
+import { USDMClient } from 'binance';
+
+// or, if you prefer `require()`:
+// const { USDMClient } = require('binance');
 
 const API_KEY = 'xxx';
 const API_SECRET = 'yyy';
@@ -177,6 +236,8 @@ const API_SECRET = 'yyy';
 const client = new USDMClient({
   api_key: API_KEY,
   api_secret: API_SECRET,
+  // Connect to testnet environment
+  // testnet: true,
 });
 
 client
@@ -189,13 +250,19 @@ client
   });
 
 client
-  .get24hrChangeStatististics()
+  .submitNewOrder({
+    side: 'SELL',
+    symbol: 'BTCUSDT',
+    type: 'MARKET',
+    quantity: 0.001,
+  })
   .then((result) => {
-    console.log('get24hrChangeStatististics inverse futures result: ', result);
+    console.log('submitNewOrder result: ', result);
   })
   .catch((err) => {
-    console.error('get24hrChangeStatististics inverse futures error: ', err);
+    console.error('submitNewOrder error: ', err);
   });
+
 ```
 
 See [usdm-client.ts](./src/usdm-client.ts) for further information.
@@ -205,7 +272,10 @@ See [usdm-client.ts](./src/usdm-client.ts) for further information.
 Start by importing the coin-m client. API credentials are optional, though an error is thrown when attempting any private API calls without credentials.
 
 ```javascript
-const { CoinMClient } = require('binance');
+import { CoinMClient } from 'binance';
+
+// or, if you prefer `require()`:
+// const { CoinMClient } = require('binance');
 
 const API_KEY = 'xxx';
 const API_SECRET = 'yyy';
@@ -213,6 +283,8 @@ const API_SECRET = 'yyy';
 const client = new CoinMClient({
   api_key: API_KEY,
   api_secret: API_SECRET,
+  // Connect to testnet environment
+  // testnet: true,
 });
 
 client
@@ -229,29 +301,37 @@ See [coinm-client.ts](./src/coinm-client.ts) for further information.
 
 ## WebSockets
 
+### WebSocket Consumers
+
 All websockets are accessible via the shared `WebsocketClient`. As before, API credentials are optional unless the user data stream is required.
 
+The below example demonstrates connecting as a consumer, to receive WebSocket events from Binance:
+
 ```javascript
-const { WebsocketClient } = require('binance');
+import { WebsocketClient } from 'binance';
+
+// or, if you prefer `require()`:
+// const { WebsocketClient } = require('binance');
 
 const API_KEY = 'xxx';
 const API_SECRET = 'yyy';
 
-// optionally override the logger
-const logger = {
-  ...DefaultLogger,
-  silly: (...params) => {},
-};
-
+/**
+ * The WebsocketClient will manage individual connections for you, under the hood.
+ * Just make an instance of the WS Client and subscribe to topics. It'll handle the rest.
+ */
 const wsClient = new WebsocketClient(
   {
     api_key: key,
     api_secret: secret,
+    // Optional: when enabled, the SDK will try to format incoming data into more readable objects.
+    // Beautified data is emitted via the "formattedMessage" event
     beautify: true,
     // Disable ping/pong ws heartbeat mechanism (not recommended)
-    // disableHeartbeat: true
+    // disableHeartbeat: true,
+    // Connect to testnet environment
+    // testnet: true,
   },
-  logger,
 );
 
 // receive raw events
@@ -261,7 +341,7 @@ wsClient.on('message', (data) => {
 
 // notification when a connection is opened
 wsClient.on('open', (data) => {
-  console.log('connection opened open:', data.wsKey, data.ws.target.url);
+  console.log('connection opened open:', data.wsKey, data.wsUrl);
 });
 
 // receive formatted events with beautified keys. Any "known" floats stored in strings as parsed as floats.
@@ -270,8 +350,8 @@ wsClient.on('formattedMessage', (data) => {
 });
 
 // read response to command sent via WS stream (e.g LIST_SUBSCRIPTIONS)
-wsClient.on('reply', (data) => {
-  console.log('log reply: ', JSON.stringify(data, null, 2));
+wsClient.on('response', (data) => {
+  console.log('log response: ', JSON.stringify(data, null, 2));
 });
 
 // receive notification when a ws connection is reconnecting automatically
@@ -285,60 +365,212 @@ wsClient.on('reconnected', (data) => {
 });
 
 // Recommended: receive error events (e.g. first reconnection failed)
-wsClient.on('error', (data) => {
+wsClient.on('exception', (data) => {
   console.log('ws saw error ', data?.wsKey);
 });
 
-// Call methods to subcribe to as many websockets as you want.
-// Each method spawns a new connection, unless a websocket already exists for that particular request topic.
-// wsClient.subscribeSpotAggregateTrades(market);
-// wsClient.subscribeSpotTrades(market);
-// wsClient.subscribeSpotKline(market, interval);
-// wsClient.subscribeSpotSymbolMini24hrTicker(market);
-// wsClient.subscribeSpotAllMini24hrTickers();
-// wsClient.subscribeSpotSymbol24hrTicker(market);
-// wsClient.subscribeSpotAll24hrTickers();
-// wsClient.subscribeSpotSymbolBookTicker(market);
-// wsClient.subscribeSpotAllBookTickers();
-// wsClient.subscribeSpotPartialBookDepth(market, 5);
-// wsClient.subscribeSpotDiffBookDepth(market);
+/**
+ * Subscribe to public topics either one at a time or many in an array
+ */
+
+// E.g. one at a time, routed to the coinm futures websockets:
+wsClient.subscribe('btcusd@indexPrice', 'coinm');
+wsClient.subscribe('btcusd@miniTicker', 'coinm');
+
+// Or send many topics at once to a stream, e.g. the usdm futures stream:
+wsClient.subscribe(
+  [
+    'btcusdt@aggTrade',
+    'btcusdt@markPrice',
+    '!ticker@arr',
+    '!miniTicker@arr',
+  ],
+  'usdm',
+);
+
+// spot & margin topics should go to "main"
+// (similar how the MainClient is for REST APIs in that product group)
+wsClient.subscribe(
+  [
+    // All Market Rolling Window Statistics Streams
+    // https://developers.binance.com/docs/binance-spot-api-docs/web-socket-streams#all-market-rolling-window-statistics-streams
+    '!ticker_1h@arr',
+    // Individual Symbol Book Ticker Streams
+    // https://developers.binance.com/docs/binance-spot-api-docs/web-socket-streams#individual-symbol-book-ticker-streams
+    'btcusdt@bookTicker',
+    // Average Price
+    // https://developers.binance.com/docs/binance-spot-api-docs/web-socket-streams#average-price
+    'btcusdt@avgPrice',
+    // Partial Book Depth Streams
+    // https://developers.binance.com/docs/binance-spot-api-docs/web-socket-streams#partial-book-depth-streams
+    'btcusdt@depth10@100ms',
+    // Diff. Depth Stream
+    // https://developers.binance.com/docs/binance-spot-api-docs/web-socket-streams#diff-depth-stream
+    'btcusdt@depth',
+  ],
+  // Look at the `WS_KEY_URL_MAP` for a list of values here:
+  // https://github.com/tiagosiebler/binance/blob/master/src/util/websockets/websocket-util.ts
+  // "main" connects to wss://stream.binance.com:9443/stream
+  // https://developers.binance.com/docs/binance-spot-api-docs/web-socket-streams
+  'main',
+);
+
+/**
+ * For the user data stream, these convenient subscribe methods open a dedicated
+ * connection with the listen key workflow:
+ */
 
 wsClient.subscribeSpotUserDataStream();
 wsClient.subscribeMarginUserDataStream();
 wsClient.subscribeIsolatedMarginUserDataStream('BTCUSDT');
-
 wsClient.subscribeUsdFuturesUserDataStream();
-
-// each method also restores the WebSocket object, which can be interacted with for more control
-// const ws1 = wsClient.subscribeSpotSymbolBookTicker(market);
-// const ws2 = wsClient.subscribeSpotAllBookTickers();
-// const ws3 = wsClient.subscribeSpotUserDataStream(listenKey);
-
-// optionally directly open a connection to a URL. Not recommended for production use.
-// const ws4 = wsClient.connectToWsUrl(`wss://stream.binance.com:9443/ws/${listenKey}`, 'customDirectWsConnection1');
 ```
 
 See [websocket-client.ts](./src/websocket-client.ts) for further information. Also see [ws-userdata.ts](./examples/ws-userdata.ts) for user data examples.
 
+### WebSocket API
+
+Some of the product groups available on Binance also support sending requests (commands) over an active WebSocket connection. This is called the WebSocket API.
+
+Note: the WebSocket API requires the use of Ed25519 keys. HMAC & RSA keys are not supported by Binance for the WebSocket API (as of Apr 2025).
+
+#### Event Driven API
+
+The WebSocket API is available in the [WebsocketClient](./src/websocket-client.ts) via the `sendWSAPIRequest(wsKey, command, commandParameters)` method.
+
+Each call to this method is wrapped in a promise, which you can async await for a response, or handle it in a raw event-driven design.
+
+#### Async Await API
+
+The WebSocket API is also available in a promise-wrapped REST-like format. Either, as above, await any calls to `sendWSAPIRequest(...)`, or directly use the convenient WebsocketAPIClient. This class is very similar to existing REST API classes (such as the MainClient or USDMClient).
+
+It provides one function per endpoint, feels like a REST API and will automatically route your request via an automatically persisted, authenticated and health-checked WebSocket API connection.
+
+Below is an example showing how easy it is to use the WebSocket API without any concern for the complexity of managing WebSockets.
+
+```typescript
+import { WebsocketAPIClient } from 'binance';
+
+// or, if you prefer `require()`:
+// const { WebsocketAPIClient } = require('binance');
+
+/**
+ * The WS API only works with an Ed25519 API key.
+ *
+ * Check the rest-private-ed25519.md in this folder for more guidance
+ * on preparing this Ed25519 API key.
+ */
+
+const publicKey = `-----BEGIN PUBLIC KEY-----
+MCexampleQTxwLU9o=
+-----END PUBLIC KEY-----
+`;
+
+const privateKey = `-----BEGIN PRIVATE KEY-----
+MC4CAQAexamplewqj5CzUuTy1
+-----END PRIVATE KEY-----
+`;
+
+// API Key returned by binance, generated using the publicKey (above) via Binance's website
+const apiKey = 'TQpJexamplerobdG';
+
+// Make an instance of the WS API Client
+const wsClient = new WebsocketAPIClient({
+  api_key: apiKey,
+  api_secret: privateKey,
+  beautify: true,
+
+  // Enforce testnet ws connections, regardless of supplied wsKey
+  // testnet: true,
+});
+
+// Optional, if you see RECV Window errors, you can use this to manage time issues. However, make sure you sync your system clock first!
+// https://github.com/tiagosiebler/awesome-crypto-examples/wiki/Timestamp-for-this-request-is-outside-of-the-recvWindow
+// wsClient.setTimeOffsetMs(-5000);
+
+// Optional, see above. Can be used to prepare a connection before sending commands
+// await wsClient.connectWSAPI(WS_KEY_MAP.mainWSAPI);
+
+// Make WebSocket API calls, very similar to a REST API:
+
+wsClient
+  .getFuturesAccountBalanceV2({
+    timestamp: Date.now(),
+    recvWindow: 5000,
+  })
+  .then((result) => {
+    console.log('getFuturesAccountBalanceV2 result: ', result);
+  })
+  .catch((err) => {
+    console.error('getFuturesAccountBalanceV2 error: ', err);
+  });
+
+wsClient
+  .submitNewFuturesOrder('usdm', {
+    side: 'SELL',
+    symbol: 'BTCUSDT',
+    type: 'MARKET',
+    quantity: 0.001,
+    timestamp: Date.now(),
+    // recvWindow: 5000,
+  })
+  .then((result) => {
+    console.log('getFuturesAccountBalanceV2 result: ', result);
+  })
+  .catch((err) => {
+    console.error('getFuturesAccountBalanceV2 error: ', err);
+  });
+```
+
 ---
 
 ## Customise Logging
 
-Pass a custom logger which supports the log methods `silly`, `debug`, `notice`, `info`, `warning` and `error`, or override methods from the default logger as desired.
+Pass a custom logger which supports the log methods `trace`, `info` and `error`, or override methods from the default logger as desired.
 
 ```javascript
-const { WebsocketClient, DefaultLogger } = require('binance');
+import { WebsocketClient, DefaultLogger } from 'binance';
 
-// Enable all logging on the silly level
-DefaultLogger.silly = (...params) => {
-  console.log('sillyLog: ', params);
+// or, if you prefer `require()`:
+// const { WebsocketClient, DefaultLogger } = require('binance');
+
+// Enable all logging on the trace level (disabled by default)
+DefaultLogger.trace = (...params) => {
+  console.trace('trace: ', params);
 };
 
+// Pass the updated logger as the 2nd parameter
 const ws = new WebsocketClient(
-  api_key: 'xxx',
-  api_secret: 'yyyy',
+  {
+    api_key: key,
+    api_secret: secret,
+    beautify: true,
+  },
   DefaultLogger
 );
+
+// Or, create a completely custom logger with the 3 available functions
+const customLogger = {
+  trace: (...params: LogParams): void => {
+    console.trace(new Date(), params);
+  },
+  info: (...params: LogParams): void => {
+    console.info(new Date(), params);
+  },
+  error: (...params: LogParams): void => {
+    console.error(new Date(), params);
+  },
+}
+
+// Pass the custom logger as the 2nd parameter
+const ws = new WebsocketClient(
+  {
+    api_key: key,
+    api_secret: secret,
+    beautify: true,
+  },
+  customLogger
+);
 ```
 
 ## Browser/Frontend Usage
@@ -381,8 +613,6 @@ Build a bundle using webpack:
 
 The bundle can be found in `dist/`. Altough usage should be largely consistent, smaller differences will exist. Documentation is still TODO.
 
-However, note that browser usage will lead to CORS errors due to Binance.
-
 ---
 
 <!-- template_contributions -->

package/index.js

@@ -1 +1 @@
-module.exports = require('lib/index');
+module.exports = require('lib/index');