v3.1.4: New algo orders endpoints, deprecation of !ticker@arr topic

What's Changed

• feat(v3.1.4): New algo orders, minor changes by @JJ-Cro in #604

1. Spot API - New symbolStatus Parameter

Affected Endpoints:

• REST API:

  • GET /api/v3/depth
  • GET /api/v3/ticker/price
  • GET /api/v3/ticker/bookTicker
  • GET /api/v3/ticker/24hr
  • GET /api/v3/ticker/tradingDay
  • GET /api/v3/ticker

• WebSocket API:

  • depth
  • ticker.price
  • ticker.book
  • ticker.24hr
  • ticker.tradingDay
  • ticker

Files Modified:

• src/types/spot.ts - Added symbolStatus to TradingDayTickerParams and RollingWindowTickerParams
• src/types/shared.ts - Added symbolStatus to OrderBookParams
• src/main-client.ts - Added symbolStatus to method parameters
• src/types/websockets/ws-api-requests.ts - Added symbolStatus to request interfaces

Usage:

// REST API
client.get24hrChangeStatistics({
  symbols: ['BTCUSDT'],
  symbolStatus: 'TRADING'
});

// WebSocket API
wsClient.sendWSAPIRequest('mainWSAPI', 'ticker.24hr', {
  symbol: 'BTCUSDT',
  symbolStatus: 'TRADING'
});

2. Deprecated WebSocket Stream - !ticker@arr

Change: The !ticker@arr stream has been deprecated by Binance (effective 2025-11-14).

Files Modified:

• src/types/websockets/ws-events-formatted.ts - Added @deprecated JSDoc warning
• src/util/typeGuards.ts - Added deprecation warning to isWsFormatted24hrTickerArray()
• examples/WebSockets/ws-public.ts - Updated to use !miniTicker@arr instead
• examples/WebSockets/ws-custom-parser.ts - Updated to use !miniTicker@arr instead
• README.md - Updated examples to use recommended alternatives

Migration:

// Old (deprecated)
wsClient.subscribe(['!ticker@arr'], 'main');

// New (recommended)
wsClient.subscribe(['!miniTicker@arr'], 'main'); // For all symbols
// or
wsClient.subscribe(['btcusdt@ticker'], 'main'); // For single symbol### 3. Derivatives - `priceMatch` Enum Updates

Change: OPPONENT_10 and OPPONENT_20 are temporarily removed from place/amend flows (effective 2025-10-23).

Files Modified:

• src/types/futures.ts - Added deprecation comment to PriceMatchMode
• src/types/portfolio-margin.ts - Added deprecation comment to PMPriceMatch

Affected Endpoints:

• USDⓈ-M Futures: POST/PUT /fapi/v1/order, POST/PUT /fapi/v1/batchOrders
• COIN-M Futures: POST/PUT /dapi/v1/order, POST/PUT /dapi/v1/batchOrders
• Portfolio Margin: POST/PUT /papi/v1/um/order, POST/PUT /papi/v1/cm/order, etc.

4. USDⓈ-M Futures - Order Expire Reason Field

Change: New er (order expire reason) field available in ORDER_TRADE_UPDATE stream (effective 2025-10-23).

Files Modified:

• src/types/websockets/ws-events-raw.ts - Added er?: string to WsMessageFuturesUserDataOrderTradeUpdateEventRaw
• src/types/websockets/ws-events-formatted.ts - Added orderExpireReason?: string to WsMessageFuturesUserDataTradeUpdateEventFormatted

Usage:

wsClient.on('formattedUserDataMessage', (data) => {
  if (data.eventType === 'ORDER_TRADE_UPDATE') {
    console.log('Order expire reason:', data.order.orderExpireReason);
  }
});

5. USDⓈ-M Futures - Algo Orders (Conditional Orders Migration)

Change: Conditional orders migrated to Algo Service (effective 2025-12-02).

Order Types Affected:

• STOP_MARKET
• TAKE_PROFIT_MARKET
• STOP
• TAKE_PROFIT
• TRAILING_STOP_MARKET

5.1 New REST API Endpoints

Files Modified:

• src/types/futures.ts - Added new Algo Order types and interfaces
• src/usdm-client.ts - Added new REST API methods

New Methods:

// Place algo order
client.submitNewAlgoOrder({
  algoType: 'CONDITIONAL',
  symbol: 'BTCUSDT',
  side: 'SELL',
  type: 'TAKE_PROFIT',
  quantity: '0.01',
  triggerPrice: '50000',
  price: '50000',
  timeInForce: 'GTC'
});

// Cancel algo order
client.cancelAlgoOrder({
  algoId: 12345
});

// Cancel all algo open orders
client.cancelAllAlgoOpenOrders({
  symbol: 'BTCUSDT'
});

// Query algo order
client.getAlgoOrder({
  algoId: 12345
});

// Query open algo orders
client.getOpenAlgoOrders({
  symbol: 'BTCUSDT'
});

// Query all algo orders
client.getAllAlgoOrders({
  symbol: 'BTCUSDT'
});

New Endpoints:

• POST /fapi/v1/algoOrder - Place an algo order
• DELETE /fapi/v1/algoOrder - Cancel an algo order
• DELETE /fapi/v1/algoOpenOrders - Cancel all open algo orders
• GET /fapi/v1/algoOrder - Query an algo order
• GET /fapi/v1/openAlgoOrders - Query algo open order(s)
• GET /fapi/v1/allAlgoOrders - Query algo order(s)

5.2 New WebSocket Events

Files Modified:

• src/types/websockets/ws-events-raw.ts - Added WsMessageFuturesUserDataAlgoUpdateRaw
• src/types/websockets/ws-events-formatted.ts - Added WsMessageFuturesUserDataAlgoUpdateFormatted

New Event Type: ALGO_UPDATE

Usage:

// Raw event
wsClient.on('message', (data) => {
  if (data.e === 'ALGO_UPDATE') {
    console.log('Algo Order Update:', data.ao);
  }
});

// Formatted event
wsClient.on('formattedUserDataMessage', (data) => {
  if (data.eventType === 'ALGO_UPDATE') {
    console.log('Algo Order Update:', data.algoOrder);
  }
});

6. New TypeScript Types and Interfaces

Added to src/types/futures.ts:

// Types
export type AlgoOrderType = 'CONDITIONAL';
export type AlgoOrderStatus = 'NEW' | 'CANCELED' | 'TRIGGERED' | 'EXPIRED' | 'FINISHED';

// Interfaces
export interface NewAlgoOrderParams { /* ... */ }
export interface AlgoOrderResponse { /* ... */ }
export interface CancelAlgoOrderParams { /* ... */ }
export interface CancelAlgoOrderResponse { /* ... */ }
export interface CancelAllAlgoOpenOrdersResponse { /* ... */ }
export interface QueryAlgoOrderParams { /* ... */ }
export interface QueryAlgoOrderResponse { /* ... */ }
export interface QueryOpenAlgoOrdersParams { /* ... */ }
export interface QueryAllAlgoOrdersParams { /* ... */ }

Breaking Changes

None. All changes are backwards compatible:

• New optional parameters won't affect existing code
• Deprecated streams still work (will be removed by Binance at a later date)
• Deprecated priceMatch values temporarily removed by Binance but kept in types for compatibility
• New methods and types are additive

Migration Guide

For !ticker@arr Stream Users

// Before
wsClient.subscribe(['!ticker@arr'], 'main');

// After (recommended)
wsClient.subscribe(['!miniTicker@arr'], 'main');
// or for single symbol
wsClient.subscribe(['btcusdt@ticker'], 'main');### For Conditional Orders → Algo Orders

// Old conditional order (still works but will migrate to algo service)
client.submitNewOrder({
  symbol: 'BTCUSDT',
  side: 'SELL',
  type: 'TAKE_PROFIT',
  quantity: '0.01',
  stopPrice: '50000',
  price: '50000',
  timeInForce: 'GTC'
});

// New algo order (recommended for conditional orders after 2025-12-02)
client.submitNewAlgoOrder({
  algoType: 'CONDITIONAL',
  symbol: 'BTCUSDT',
  side: 'SELL',
  type: 'TAKE_PROFIT',
  quantity: '0.01',
  triggerPrice: '50000', // Note: stopPrice → triggerPrice
  price: '50000',
  timeInForce: 'GTC'
});

Full Changelog: v3.1.3...v3.1.4