feat(v3.0.0): Introduce Binance WebSocket API, introduce multiplex WebSocket client, bump dependencies, remove some deprecated endpoints

.eslintrc.cjs

@@ -33,6 +33,7 @@ module.exports = {
     'array-bracket-spacing': ['error', 'never'],
     'linebreak-style': ['error', 'unix'],
     'lines-between-class-members': ['warn', 'always'],
+    allowObjectTypes: 0,
     semi: ['error', 'always'],
     'new-cap': 'off',
     'no-console': 'off',

examples/README.md

@@ -1,23 +1,95 @@
 # Binance API - Examples
 
-This folder contains ready to go examples demonstrating various aspects of this API implementation, written in typescript.
+This folder contains ready to go examples demonstrating various aspects of this API implementation, written in TypeScript (but they are compatible with pure JavaScript projects).
 
 Found something difficult to implement? Contribute to these examples and help others!
 
 ## Getting started
 
-- Clone the project (or install the module in your own project `npm install binance`).
-- Edit the sample as needed (some samples require edits, e.g APi keys or import statements).
-- Execute the sample using ts-node: `ts-node examples/rest-spot-public.ts`.
+- Clone the project (or download it as a zip, or install the module in your own project `npm install binance`).
+- Edit the sample as needed (some samples require edits, e.g API keys or import statements to import from npm, not src).
+- Execute the sample using tsx: `tsx examples/REST/rest-spot-public.ts`.
 
-Samples that API credentials using `process.env.APIKEY` can be spawned with environment variables. Unix/macOS example:
+Samples that refer to API credentials using `process.env.API_KEY_COM` can be spawned with environment variables. Unix/macOS example:
 ```
-APIKEY="apikeypastedhere" APISECRET="apisecretpastedhere" ts-node examples/ws-userdata.ts
+APIKEY="apikeypastedhere" APISECRET="apisecretpastedhere" tsx examples/WebSockets/ws-userdata-listenkey.ts
 ```
 
+Or edit the example directly to hardcode your API keys.
 
-## REST USDM Examples
+### WebSockets
+
+All examples relating to WebSockets can be found in the [examples/WebSockets](./WebSockets/) folder. High level summary of available examples:
+
+#### Consumers
+
+These are purely for receiving data from Binance's WebSockets (market data, account updates, etc).
+
+##### Market Data
+
+These examples demonstrate subscribing to & receiving market data from Binance's WebSockets:
+
+- ws-public.ts
+  - Demonstration on general usage of the WebSocket client to subscribe to / unsubscribe from one or more market data topics.
+- ws-public-spot-orderbook.ts
+  - Subscribing to orderbook events for multiple symbols in spot markets.
+-	ws-public-spot-trades.ts
+  - Subscribing to raw trades for multiple symbols in spot markets.
+- ws-unsubscribe.ts
+  - Subscribing to a list of topics, and then unsubscribing from a few topics in that list.
+- ws-public-usdm-funding.ts
+  - Simple example subscribing to a general topic, and how to process incoming events to only extract funding rates from those events.
+
+##### Account Data
+
+These examples demonstrate receiving account update events from Binance's WebSockets:
+
+-	ws-userdata-listenkey.ts
+  - Demonstration on subscribing to various user data streams (spot, margin, futures),
+  - Handling incoming user data events
+  - Using provided type guards to determine which product group the user data event is for (spot, margin, futures, etc).
+- ws-userdata-listenKey-testnet.ts
+  - Similar to above, but on testnet.
+- ws-userdata-connection-safety.ts
+  - Demonstration on extra safety around the first user data stream connection.
+  - Note: this is overkill in most situations...
+
+##### WebSocket API
+
+These examples demonstrate how to send commands using Binance's WebSocket API (e.g. submitting orders). Very similar to the REST API, but using a persisted WebSocket connection instead of HTTP requests.
+
+- ws-api-client.ts
+  - Demonstration of using Binance's WebSocket API in Node.js/JavaScript/TypeScript, using the WebsocketAPIClient.
+  - This WebsocketAPIClient is very similar to a REST client, with one method per available command (endpoint) and fully typed requests & responses.
+  - Routing is automatically handled via the WebsocketClient, including authentication and connection persistence. Just call the functions you need - the SDK does the rest.
+  - From a usage perspective, it feels like a REST API - you can await responses just like a HTTP request.
+- ws-api-raw-promises.ts
+  - More verbose usage of the WebSocket API using the `sendWSAPIRequest()` method.
+  - The `WebsocketAPIClient` uses this method too, so in most cases it is simple to just use the `WebsocketAPIClient` instead.
+- ws-userdata-wsapi.ts
+  - The listenKey workflow for the user data stream is deprecated (in spot markets).
+  - This example demonstrates how to subscribe to the user data stream in spot markets, without a listen key, using the WebSocket API.
+
+##### Misc Workflows
+
+These are miscellaneous examples that cover one or more of the above categories:
+
+- ws-close.ts
+  - Closing the (old listen-key driven) user data stream.
+  - Unsubscribing from various topics.
+- ws-proxy-socks.ts
+  - Using WebSockets over a SOCKS proxy.
+- deprecated-ws-public.ts
+
+
+### REST APIs
+
+All examples relating to REST APIs can be found in the [examples/REST](./REST/) folder. Most examples are named around functionality & product group. Any examples with "private" involve API calls relating to your account (such as changing settings or submitting orders, etc),
+
+High level summary for some of the available examples, but check the folder for a complete list:
+
+#### REST USDM Examples
 
 - `rest-future-bracket-order.ts` Creates three order, entry, TP, SL and submit them all at once using `submitMultipleOrders`
 - `rest-usdm-order.ts` Creates single entry, using `submitNewOrder`
-- `rest-usdm-order-sl.ts` Modify current Stop Loss order(HedgeMode only)
+- `rest-usdm-order-sl.ts` Modify current Stop Loss order(HedgeMode only)

examples/rest-future-bracket-order.ts → examples/REST/rest-future-bracket-order.ts

@@ -1,7 +1,7 @@
-import { USDMClient, NewFuturesOrderParams } from '../src/index';
+import { NewFuturesOrderParams, USDMClient } from '../../src/index';
 
-const key = process.env.APIKEY || 'APIKEY';
-const secret = process.env.APISECRET || 'APISECRET';
+const key = process.env.API_KEY_COM || 'APIKEY';
+const secret = process.env.API_SECRET_COM || 'APISECRET';
 
 const client = new USDMClient({
   api_key: key,

examples/rest-portfoliomargin-private.ts → examples/REST/rest-portfoliomargin-private.ts

@@ -1,4 +1,4 @@
-import { PortfolioClient } from '../src/index';
+import { PortfolioClient } from '../../src/index';
 
 // or
 // import { PortfolioClient } from 'binance';

examples/rest-portfoliomargin-public.ts → examples/REST/rest-portfoliomargin-public.ts

@@ -1,4 +1,4 @@
-import { PortfolioClient } from '../src/index';
+import { PortfolioClient } from '../../src/index';
 
 // or
 // import { PortfolioClient } from 'binance';

examples/rest-spot-private-autoinvest.ts → examples/REST/rest-spot-private-autoinvest.ts

@@ -1,4 +1,4 @@
-import { MainClient } from '../src/index';
+import { MainClient } from '../../src/index';
 
 // or
 // import { MainClient } from 'binance';

examples/rest-spot-private-misc.ts → examples/REST/rest-spot-private-misc.ts

@@ -1,4 +1,4 @@
-import { MainClient } from '../src/index';
+import { MainClient } from '../../src/index';
 
 // or
 // import { MainClient } from 'binance';

examples/rest-spot-private-trade.ts → examples/REST/rest-spot-private-trade.ts

@@ -1,15 +1,15 @@
 import {
+  MainClient,
   NewSpotOrderParams,
   OrderResponseFull,
-  MainClient,
   SymbolPrice,
-} from '../src/index';
+} from '../../src/index';
 
 // or
 // import { MainClient } from 'binance';
 
-const key = process.env.APIKEY || 'APIKEY';
-const secret = process.env.APISECRET || 'APISECRET';
+const key = process.env.API_KEY_COM || 'APIKEY';
+const secret = process.env.API_SECRET_COM || 'APISECRET';
 
 const client = new MainClient({
   api_key: key,
@@ -89,13 +89,13 @@ function trimToDecimalPlaces(number: number, precision: number): number {
       newOrderRespType: 'FULL',
     };
 
-    console.log(`Submitting buy order: `, buyOrderRequest);
+    console.log('Submitting buy order: ', buyOrderRequest);
     await client.testNewOrder(buyOrderRequest);
     const buyOrderResult = (await client.submitNewOrder(
       buyOrderRequest,
     )) as OrderResponseFull;
     console.log(
-      `Order result: `,
+      'Order result: ',
       JSON.stringify(
         { request: buyOrderRequest, response: buyOrderResult },
         null,
@@ -126,14 +126,14 @@ function trimToDecimalPlaces(number: number, precision: number): number {
       newOrderRespType: 'FULL',
     };
 
-    console.log(`Submitting sell order: `, sellOrderRequest);
+    console.log('Submitting sell order: ', sellOrderRequest);
     await client.testNewOrder(sellOrderRequest);
     const sellOrderResult = (await client.submitNewOrder(
       sellOrderRequest,
     )) as OrderResponseFull;
 
     console.log(
-      `Order result: `,
+      'Order result: ',
       JSON.stringify(
         { request: sellOrderRequest, response: sellOrderResult },
         null,

examples/rest-spot-public.ts → examples/REST/rest-spot-public.ts

@@ -1,4 +1,4 @@
-import { MainClient } from '../src/index';
+import { MainClient } from '../../src/index';
 
 // or
 // import { MainClient } from 'binance';
@@ -19,16 +19,16 @@ const client = new MainClient({
     //   JSON.stringify(await client.getExchangeInfo(), null, 2),
     // );
 
-    const oneTicker = await client.get24hrChangeStatististics({
+    const oneTicker = await client.get24hrChangeStatistics({
       symbol: 'BTCUSDT',
     });
     console.log('getTickers', oneTicker);
 
-    const manyTickers = await client.get24hrChangeStatististics({
+    const manyTickers = await client.get24hrChangeStatistics({
       symbols: ['BTCUSDT', 'ETHUSDT'],
     });
     console.log('getTickers many', manyTickers);
-    const allTickers = await client.get24hrChangeStatististics();
+    const allTickers = await client.get24hrChangeStatistics();
     console.log('getTickers all', allTickers);
   } catch (e) {
     console.error('request failed: ', e);

examples/rest-usdm-order-sl.ts → examples/REST/rest-usdm-order-sl.ts

@@ -1,10 +1,11 @@
-import { USDMClient } from '../src/index';
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import { USDMClient } from '../../src/index';
 
 // or
 // import { USDMClient } from 'binance';
 
-const key = process.env.APIKEY || 'APIKEY';
-const secret = process.env.APISECRET || 'APISECRET';
+const key = process.env.API_KEY_COM || 'APIKEY';
+const secret = process.env.API_SECRET_COM || 'APISECRET';
 
 const client = new USDMClient({
   api_secret: secret,
@@ -26,8 +27,8 @@ async function start() {
      */
     const [
       { positionAmt: longAmount, ...long },
-      { positionAmt: shortAmount, ...short }
-    ]: any = await client.getPositions({ symbol });
+      { positionAmt: shortAmount, ...short },
+    ]: any = await client.getPositionsV3({ symbol });
 
     // if longAmount is bigger than 0 means we have open long position and if shortAmount is below 0 means we have open short position
     const hasLong = parseFloat(longAmount) > 0;
@@ -36,16 +37,17 @@ async function start() {
 
     // if we have any open position then we continue
     if (hasOpen) {
-
       // we get ourstop loss here
       const orders = await client.getAllOpenOrders({ symbol });
-      const stopOrders = orders.filter(({ type }) => type === 'STOP_MARKET') ?? {};
+      const stopOrders =
+        orders.filter(({ type }) => type === 'STOP_MARKET') ?? [];
 
-      // we want to modify our long position SL here 
+      // we want to modify our long position SL here
       if (hasLong) {
-
         // we get the StopLoss order which is realted to long
-        const { orderId }: any = stopOrders.find(({ positionSide: ps }) => ps == 'LONG');
+        const { orderId }: any = stopOrders.find(
+          ({ positionSide: ps }) => ps == 'LONG',
+        );
 
         // if it exists, cancel it.
         if (orderId) {
@@ -62,8 +64,8 @@ async function start() {
           timeInForce: 'GTC',
           type: 'STOP_MARKET',
           closePosition: 'true', // this is here because we don't have the position quantity value, and it means closee all quantity
-          stopPrice: parseFloat((markPrice * .99).toFixed(3)), // set sl price 1% below current price
-          workingType: 'MARK_PRICE'
+          stopPrice: parseFloat((markPrice * 0.99).toFixed(3)), // set sl price 1% below current price
+          workingType: 'MARK_PRICE',
         });
         console.log('SL Modifiled sell result: ', result);
       }

examples/rest-usdm-order.ts → examples/REST/rest-usdm-order.ts

@@ -1,10 +1,10 @@
-import { USDMClient } from '../src/index';
+import { USDMClient } from '../../src/index';
 
 // or
 // import { USDMClient } from 'binance';
 
-const key = process.env.APIKEY || 'APIKEY';
-const secret = process.env.APISECRET || 'APISECRET';
+const key = process.env.API_KEY_COM || 'APIKEY';
+const secret = process.env.API_SECRET_COM || 'APISECRET';
 
 const client = new USDMClient({
   api_secret: secret,

examples/rest-usdm-private-get.ts → examples/REST/rest-usdm-private-get.ts

@@ -1,11 +1,11 @@
-import { USDMClient } from '../src/index';
+import { USDMClient } from '../../src/index';
 // import axios from 'axios';
 
 // or
 // import { USDMClient } from 'binance';
 
-const key = process.env.APIKEY || 'APIKEY';
-const secret = process.env.APISECRET || 'APISECRET';
+const key = process.env.API_KEY_COM || 'APIKEY';
+const secret = process.env.API_SECRET_COM || 'APISECRET';
 
 const client = new USDMClient({
   api_key: key,

examples/REST/rest-usdm-public.ts

@@ -0,0 +1,15 @@
+import { USDMClient } from '../../src';
+
+const client = new USDMClient({
+  testnet: true,
+  // keepAlive: true,
+  // ... any other params,
+});
+
+client
+  .getRecentTrades({
+    symbol: 'BTCUSDT',
+    limit: 2,
+  })
+  .then((r) => console.log('results: ', r))
+  .catch((e) => console.error('exception: ', e));

examples/REST/rest-usdm-testnet.ts

@@ -0,0 +1,39 @@
+import { USDMClient } from '../../src/index';
+
+// or
+// import { USDMClient } from 'binance';
+
+const key = process.env.API_KEY_COM || 'APIKEY';
+const secret = process.env.API_SECRET_COM || 'APISECRET';
+
+const client = new USDMClient({
+  api_secret: secret,
+  api_key: key,
+  beautifyResponses: true,
+  /**
+   * Note: testnet is NOT a good place to test strategy performance.
+   *
+   * For more information and guidance, refer to:
+   * https://github.com/tiagosiebler/awesome-crypto-examples/wiki/CEX-Testnets
+   */
+  testnet: true,
+});
+
+async function start() {
+  try {
+    // To open a short position - if you don't have a position yet, and your account is set to one-way mode, just place a sell order to open a short position
+    const result = await client.submitNewOrder({
+      side: 'SELL',
+      symbol: 'BTCUSDT',
+      type: 'MARKET',
+      quantity: 0.001,
+      // newOrderRespType: 'FULL',
+    });
+
+    console.log('market sell result: ', result);
+  } catch (e) {
+    console.error('market sell failed: ', e);
+  }
+}
+
+start();