feat(v3.1.4): New algo orders, minor changes

[JJ-Cro]

Overview

This PR implements the latest Binance API changes from their November 2025 changelog, including new parameters, deprecation warnings, and the introduction of Algo Orders for USDⓈ-M Futures.

Changes Implemented

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);
}
});#### 5.3 Order ID Validation

Files Modified:

• src/types/shared.ts - Extended OrderIdProperty to include algo order ID properties
• src/usdm-client.ts - Updated validateOrderId() to handle algo orders

New Order ID Properties:

• clientAlgoId
• aboveClientOrderId
• belowClientOrderId
• workingClientOrderId
• pendingAboveClientOrderId
• pendingBelowClientOrderId

Auto-generation: Client algo IDs are automatically generated and validated with the x- prefix convention.

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'
});## Testing

• ✅ All new types compile without errors
• ✅ Linter checks pass
• ✅ Examples updated and verified
• ✅ Order ID validation works for algo orders
• ⚠️ Manual testing recommended for new algo order endpoints (requires Binance account with futures enabled)

References

• Binance Changelog: 2025-11-14 (Spot API, WebSocket deprecation)
• Binance Changelog: 2025-10-28 (symbolStatus parameter)
• Binance Changelog: 2025-10-21 (priceMatch enum changes)
• Binance Changelog: 2025-10-20 (order expire reason field)
• Binance Changelog: 2025-11-06 (Algo Orders migration)

Related Issues

• Implements changes from Binance API Changelog (November 2025)
• Addresses deprecation of !ticker@arr stream
• Adds support for new Algo Orders service

Summary

Additional Information

PR Checklist

As part of the PR, make sure you have:

• No breaking changes / documented all breaking changes clearly.
• Updated & checked that all tests pass.
• Increased the version number in the package.json
• Checked npm install runs without issue.
• Included the package-lock.json, if it changed after npm install
• Checked npm run build runs without issue.
• Updated the endpoint map (optional, if you know how).
• Run llms.txt generator (optional, if you know how).

[tiagosiebler]

LGTM