Binance User Data Stream 410 Gone: Fix Spot listenKey in JavaScript

A process using the old Spot startup method can fail before opening its private socket:

POST https://api.binance.com/api/v3/userDataStream
HTTP 410 Gone

That URL identifies the migration. Changing HTTP libraries or repeatedly creating a listenKey cannot restore a retired endpoint. Binance's 21 January 2026 announcement set its retirement for 20 February 2026 at 07:00 UTC.

The replacement for Spot account events is a subscription on the WebSocket API. Other product families have their own startup methods, so first identify whether the failing process serves Spot, Margin, USD-M Futures, COIN-M Futures, or Portfolio Margin.

A 410 from this retired URL does not diagnose the credentials for its replacement. The new connection can still fail separately because of its key type, environment, or permissions.

Spot account events include balance changes and order updates such as outboundAccountPosition, balanceUpdate, and executionReport. They describe the account, independently of public price streams. The Binance event reference defines each payload.

On WebsocketAPIClient, calling subscribeUserDataStream() with WS_KEY_MAP.mainWSAPI selects the Spot subscription path in the Binance SDK. The SDK uses userDataStream.subscribe on an Ed25519-authenticated session and the signature-subscription method for HMAC or RSA keys. A migration does not require replacing a supported HMAC key with Ed25519.

Install binance, save this as spot-user-data.mjs, and supply credentials created for the production Spot API. The example subscribes and logs event types without submitting orders or printing account payloads:

import { WebsocketAPIClient, WS_KEY_MAP } from 'binance';

const api_key = process.env.BINANCE_API_KEY;
const api_secret = process.env.BINANCE_API_SECRET;
if (!api_key || !api_secret) throw new Error('Set both Binance credentials');

const client = new WebsocketAPIClient({ api_key, api_secret, beautify: true });
const ws = client.getWSClient();
let stopped = false;
let deadline;
async function stop() {
  if (stopped) return;
  stopped = true;
  clearTimeout(deadline);
  await client.disconnectAll();
}
ws.on('formattedUserDataMessage', (event) => {
  if (!stopped) console.log({ eventType: event.eventType });
});
ws.on('reconnecting', ({ wsKey }) => {
  console.error('Account consumer needs recovery:', wsKey);
});
ws.on('reconnected', ({ wsKey }) => {
  console.error('Connection restored; account recovery still required:', wsKey);
});
ws.on('exception', () => {
  console.error('Spot user-data connection failed');
  process.exitCode = 1;
  void stop();
});
process.once('SIGINT', () => void stop());
deadline = setTimeout(() => void stop(), 20_000);
try {
  await client.subscribeUserDataStream(WS_KEY_MAP.mainWSAPI);
} catch {
  console.error('Spot user-data subscription failed');
  process.exitCode = 1;
  await stop();
}

With beautify: true, the formatted event exposes eventType; raw Binance payloads use short field names such as e. Keep the handler aligned with the selected emitter. Attach it before subscribing so early account events are not discarded.

The script demonstrates connection setup only. Its reconnect messages do not perform account recovery. The Binance tutorial supplies the complete client setup and environment options.

The SDK's user-data methods follow different protocols:

A Spot retirement notice does not establish that the Futures endpoints have retired. Likewise, replacing a Margin subscription with the Spot key would select the wrong account feed. Check the installed SDK's product-specific example before changing a working integration.

The Spot changelog records several different steps: deprecation on 7 April 2025, removal of the old stream documentation on 24 October 2025, and the later endpoint retirement announcement. Deprecation and documentation removal were not the final shutdown date.

The February 2026 retirement covered the Spot REST listenKey create, keepalive, and close endpoints, plus the older WebSocket API userDataStream.start, ping, and stop methods. The replacement subscription methods are separate API operations.

A successful subscription does not provide every value required by an account consumer. Initialize missing values and apply the events according to their documented scope. For example, a balance event containing changed assets must not erase unrelated asset rows.

After a reconnect, the SDK can resubscribe, but it cannot infer the application's missed history or unresolved orders. The account initializer covers missing values; reconnect recovery covers the affected state and unknown submissions. Healthy private events then maintain the cache without polling REST after each event.

Subscriptions and REST recovery still consume exchange resources. The application owns request scheduling; moving an operation to WebSocket does not exempt it from limits.

The WebSocket API also exposes request/response methods. Its persistent connection can avoid connection setup on later requests. HTTP clients can reuse connections too, so assuming a fresh DNS lookup and TLS handshake for every REST call gives a misleading comparison.

Ed25519 session authentication removes per-command signing where Binance permits session credentials. That is a protocol difference, not a measured latency result. The awaitable WebSocket article explains matching replies, timeouts, and how to compare equivalent operations.

Before enabling an existing account consumer, interrupt the replacement connection and check that its normal recovery path runs. Receiving a price or an account event establishes connectivity, but neither proves that events missed during the interruption were recovered.