Merge branch 'master' into bumpsfixesupdates

Author: tiagosiebler

README.md

@@ -65,6 +65,7 @@ Updated & performant JavaScript & Node.js SDK for the Binance REST APIs and WebS
 - [Related Projects](#related-projects)
 - [Documentation Links](#documentation)
 - [Usage](#usage)
+  - [Demo Trading vs Testnet](#demo-trading-vs-testnet)
   - [REST API Clients](#rest-api-clients)
     - [REST Main Client](#rest-main-client)
     - [REST USD-M Futures](#rest-usd-m-futures)
@@ -153,6 +154,16 @@ 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).
+- [Demo Trading](https://www.binance.com/en/support/faq/how-to-test-my-functions-on-binance-spot-test-network-ab78f9a1b8824cf0a106b4229c76496d) - Uses real market data with simulated trading.
+
+### Demo Trading vs Testnet
+
+Binance offers two testing environments:
+
+- **Demo Trading**: Uses real market data but simulated trading. This is ideal for testing strategies since market conditions match production. Available for Spot, USD-M Futures, and COIN-M Futures.
+- **Testnet**: Separate environment with simulated market data. Market conditions are very different from real markets and not recommended for strategy testing.
+
+To use demo trading, simply set `demoTrading: true` in the client options. See the [demo trading examples](./examples/REST/rest-spot-demo.ts) for more information.
 
 ## REST API Clients
 

examples/REST/rest-spot-demo.ts

@@ -0,0 +1,40 @@
+import { MainClient } from '../../src/index';
+
+// or
+// import { MainClient } from 'binance';
+
+const key = process.env.API_KEY_COM || 'APIKEY';
+const secret = process.env.API_SECRET_COM || 'APISECRET';
+
+const client = new MainClient({
+  api_secret: secret,
+  api_key: key,
+  beautifyResponses: true,
+  /**
+   * Demo trading uses real market data with simulated trading.
+   * Perfect for testing strategies without risk.
+   */
+  demoTrading: true,
+});
+
+async function start() {
+  try {
+    // Get account information on demo trading
+    const accountInfo = await client.getAccountInformation();
+    console.log('Demo account info: ', accountInfo);
+
+    // Place a test order on demo trading
+    const result = await client.submitNewOrder({
+      side: 'BUY',
+      symbol: 'BTCUSDT',
+      type: 'MARKET',
+      quantity: 0.001,
+    });
+
+    console.log('Demo market buy result: ', result);
+  } catch (e) {
+    console.error('Demo trading request failed: ', e);
+  }
+}
+
+start();

examples/REST/rest-usdm-demo.ts

@@ -0,0 +1,40 @@
+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,
+  /**
+   * Demo trading uses real market data with simulated trading.
+   * Perfect for testing strategies without risk.
+   */
+  demoTrading: true,
+});
+
+async function start() {
+  try {
+    // Get account information on demo trading
+    const accountInfo = await client.getAccountInformation();
+    console.log('Demo account info: ', accountInfo);
+
+    // Place a test order on demo trading
+    const result = await client.submitNewOrder({
+      side: 'SELL',
+      symbol: 'BTCUSDT',
+      type: 'MARKET',
+      quantity: 0.001,
+    });
+
+    console.log('Demo market sell result: ', result);
+  } catch (e) {
+    console.error('Demo trading request failed: ', e);
+  }
+}
+
+start();

examples/WebSockets/ws-demo-spot.ts

@@ -0,0 +1,49 @@
+import { WebsocketClient } from '../../src';
+
+// or
+// import { WebsocketClient } from 'binance';
+
+const key = process.env.API_KEY_COM || 'APIKEY';
+const secret = process.env.API_SECRET_COM || 'APISECRET';
+
+async function start() {
+  const wsClient = new WebsocketClient({
+    api_key: key,
+    api_secret: secret,
+    beautify: true,
+    /**
+     * Demo trading uses real market data with simulated trading.
+     * Perfect for testing strategies without risk.
+     *
+     * For more information:
+     * https://www.binance.com/en/support/faq/how-to-test-my-functions-on-binance-spot-test-network-ab78f9a1b8824cf0a106b4229c76496d
+     */
+    demoTrading: true,
+  });
+
+  wsClient.on('formattedMessage', (data) => {
+    console.log('Demo WS data: ', JSON.stringify(data, null, 2));
+  });
+
+  wsClient.on('open', (data) => {
+    console.log('Demo WS connection opened:', data.wsKey);
+  });
+
+  wsClient.on('response', (data) => {
+    console.log('Demo WS response: ', JSON.stringify(data, null, 2));
+  });
+
+  wsClient.on('reconnected', (data) => {
+    console.log('Demo WS reconnected ', data?.wsKey);
+  });
+
+  wsClient.on('exception', (data) => {
+    console.error('Demo WS error', data);
+  });
+
+  // Subscribe to spot market streams on demo trading
+  wsClient.subscribeSpotTrades('BTCUSDT');
+  wsClient.subscribeSpotKline('BTCUSDT', '1m');
+}
+
+start();

examples/WebSockets/ws-demo-usdm.ts

@@ -0,0 +1,46 @@
+import { WebsocketClient } from '../../src';
+
+// or
+// import { WebsocketClient } from 'binance';
+
+const key = process.env.API_KEY_COM || 'APIKEY';
+const secret = process.env.API_SECRET_COM || 'APISECRET';
+
+async function start() {
+  const wsClient = new WebsocketClient({
+    api_key: key,
+    api_secret: secret,
+    beautify: true,
+    /**
+     * Demo trading uses real market data with simulated trading.
+     * Perfect for testing strategies without risk.
+     */
+    demoTrading: true,
+  });
+
+  wsClient.on('formattedMessage', (data) => {
+    console.log('Demo WS data: ', JSON.stringify(data, null, 2));
+  });
+
+  wsClient.on('open', (data) => {
+    console.log('Demo WS connection opened:', data.wsKey);
+  });
+
+  wsClient.on('response', (data) => {
+    console.log('Demo WS response: ', JSON.stringify(data, null, 2));
+  });
+
+  wsClient.on('reconnected', (data) => {
+    console.log('Demo WS reconnected ', data?.wsKey);
+  });
+
+  wsClient.on('exception', (data) => {
+    console.error('Demo WS error', data);
+  });
+
+  // Subscribe to USDM futures market streams on demo trading
+  wsClient.subscribeKlines('BTCUSDT', '1m', 'usdm');
+  wsClient.subscribeUsdFuturesUserDataStream();
+}
+
+start();

src/types/websockets/ws-general.ts

@@ -139,6 +139,17 @@ export interface WSClientConfigurableOptions {
    */
   testnet?: boolean;
 
+  /**
+   * Set to `true` to use Binance's demo trading WebSocket endpoints.
+   * Demo trading uses real market data but simulated trading.
+   * More info: https://demo.binance.com/
+   *
+   * Notes:
+   * - If demo trading, `testnet` should be set to false!
+   * - If testing a strategy, use demo trading instead. Testnet market data is very different from real market conditions.
+   */
+  demoTrading?: boolean;
+
   /**
    * Default: false. If true, use market maker endpoints when available.
    * Eligible for high-frequency trading users who have enrolled and qualified

src/util/requestUtils.ts

@@ -53,6 +53,13 @@ export interface RestClientOptions {
    */
   testnet?: boolean;
 
+  /**
+   * Set to `true` to use Binance's demo trading endpoints.
+   * Demo trading uses real market data but simulated trading.
+   * More info: https://demo.binance.com/
+   */
+  demoTrading?: boolean;
+
   /**
    * Default: false. If true, use market maker endpoints when available.
    * Eligible for high-frequency trading users who have enrolled and qualified
@@ -427,6 +434,35 @@ const BINANCE_BASE_URLS: Record<BinanceBaseUrlKey, string> = {
   www: 'https://www.binance.com',
 };
 
+// Demo Trading URLs
+const BINANCE_DEMO_BASE_URLS: Record<BinanceBaseUrlKey, string | undefined> = {
+  // Demo Trading - Spot
+  spot: 'https://demo-api.binance.com',
+  spot1: 'https://demo-api.binance.com',
+  spot2: 'https://demo-api.binance.com',
+  spot3: 'https://demo-api.binance.com',
+  spot4: 'https://demo-api.binance.com',
+  spottest: undefined, // No demo for testnet (testnet already is a demo)
+
+  // Demo Trading - UM Futures
+  usdm: 'https://demo-fapi.binance.com',
+  usdmtest: undefined, // No demo for testnet
+
+  // Demo Trading - CM Futures
+  coinm: 'https://demo-dapi.binance.com',
+  coinmtest: undefined, // No demo for testnet
+
+  // Vanilla Options - no demo endpoints
+  voptions: undefined,
+  voptionstest: undefined,
+
+  // Portfolio Margin - no demo endpoints
+  papi: undefined,
+
+  // www - no demo endpoints
+  www: undefined,
+};
+
 const BINANCE_MM_BASE_URLS: Record<BinanceBaseUrlKey, string | undefined> = {
   // spot/margin/savings/mining - no MM endpoints
   spot: undefined,
@@ -517,6 +553,17 @@ export function getRestBaseUrl(
 
   const urlKey = restClientOptions.baseUrlKey || clientType;
 
+  // Use demo trading endpoints if requested and available
+  if (restClientOptions.demoTrading) {
+    const demoUrl = BINANCE_DEMO_BASE_URLS[urlKey];
+    if (demoUrl) {
+      return demoUrl;
+    }
+    throw new Error(
+      `Demo trading is currently not supported for the product group "${urlKey}". If demo trading should be available here, please open an issue on GitHub.`,
+    );
+  }
+
   // Use MM endpoints if requested and available
   if (restClientOptions.useMMSubdomain) {
     const mmUrl = BINANCE_MM_BASE_URLS[urlKey];

src/util/websockets/websocket-util.ts

@@ -210,6 +210,42 @@ export const WS_KEY_MM_URL_MAP: Record<WsKey, string | undefined> = {
   portfolioMarginProUserData: undefined,
 };
 
+// Demo Trading WebSocket URLs
+export const WS_KEY_DEMO_URL_MAP: Record<WsKey, string | undefined> = {
+  // Demo Trading - Spot
+  main: 'wss://demo-stream.binance.com:9443',
+  main2: 'wss://demo-stream.binance.com:443',
+  main3: 'wss://demo-stream-sbe.binance.com', // Alternative stream
+  mainTestnetPublic: undefined, // No demo for testnet
+  mainTestnetUserData: undefined, // No demo for testnet
+
+  // Demo Trading - Spot WebSocket API
+  mainWSAPI: 'wss://demo-ws-api.binance.com:443',
+  mainWSAPI2: 'wss://demo-ws-api.binance.com:9443',
+  mainWSAPITestnet: undefined, // No demo for testnet
+
+  // Margin Risk - no demo endpoint
+  marginRiskUserData: undefined,
+
+  // Demo Trading - USDM Futures
+  usdm: 'wss://fstream.binancefuture.com',
+  usdmTestnet: undefined, // No demo for testnet
+  usdmWSAPI: 'wss://testnet.binancefuture.com',
+  usdmWSAPITestnet: undefined, // No demo for testnet
+
+  // Demo Trading - COINM Futures
+  coinm: 'wss://dstream.binancefuture.com',
+  coinm2: undefined, // No demo for coinm2
+  coinmTestnet: undefined, // No demo for testnet
+  coinmWSAPI: 'wss://testnet.binancefuture.com',
+  coinmWSAPITestnet: undefined, // No demo for testnet
+
+  // Other connections - no demo endpoints
+  eoptions: undefined,
+  portfolioMarginUserData: undefined,
+  portfolioMarginProUserData: undefined,
+};
+
 export function getWsURLSuffix(
   wsKey: WsKey,
   connectionType: 'market' | 'userData',
@@ -381,10 +417,22 @@ export function getWsUrl(
   }
 
   const isTestnet = !!wsClientOptions.testnet;
+  const isDemoTrading = !!wsClientOptions.demoTrading;
   const useMMSubdomain = !!wsClientOptions.useMMSubdomain;
 
   const resolvedWsKey = isTestnet ? getTestnetWsKey(wsKey) : wsKey;
 
+  // Use demo trading endpoints if requested and available
+  if (isDemoTrading && !isTestnet) {
+    const demoUrl = WS_KEY_DEMO_URL_MAP[resolvedWsKey];
+    if (demoUrl) {
+      return demoUrl;
+    }
+    throw new Error(
+      `Demo trading is currently not supported for the WebSocket key "${resolvedWsKey}". If demo trading should be available here, please open an issue on GitHub.`,
+    );
+  }
+
   // Use MM endpoints if requested and available
   if (useMMSubdomain && !isTestnet) {
     const mmUrl = WS_KEY_MM_URL_MAP[resolvedWsKey];