Bitget Futures: Classic V2 and Unified V3 Clients

Changing a Bitget futures client from V2 to V3 changes more than an import. The account model and request fields change with it. A public price read can work even when the private order path still describes the old account.

The Bitget tutorial covers installation and authentication. This comparison concerns the boundary between Classic and Unified Trading Account workflows.

Use RestClientV2 for the SDK's Classic methods and RestClientV3 for its Unified Trading Account methods. The corresponding stream clients are WebsocketClientV2 and WebsocketClientV3. Sharing a package does not make their request objects interchangeable.

Bitget's UTA account documentation describes account modes with different product and collateral support. Establish the actual account mode before selecting a private workflow. Do not upgrade an account as a side effect of starting a worker.

A public V3 read can be checked independently:

import { RestClientV3 } from 'bitget-api';

const client = new RestClientV3();
const response = await client.getCandles({
  category: 'USDT-FUTURES',
  symbol: 'BTCUSDT',
  interval: '1m',
});
if (response.code !== '00000') throw new Error(response.msg);
console.log(response.data);

This establishes the public route and response shape. It does not establish private account access.

A migration should compare the old and new method signatures field by field. Classic futures methods use fields such as productType; V3 methods use category. Keep the correct symbol, quantity unit, margin settings, order type, and client identifier for the selected method. Do not spread a V2 request object into a V3 call and assume matching names imply matching semantics.

Retain the old request and expected result as a fixture. Build the new request from the application's intent, then compare the fields that matter. A changed account balance representation also requires a deliberate consumer change.

Subscriptions and payload envelopes differ between stream versions. Attach the new handlers before subscribing and validate the new acknowledgement and data shapes. An old parser returning an empty array can make an authenticated connection look healthy while discarding every account update.

The SDK's V3 WebsocketAPIClient exposes command methods for supported UTA workflows. Awaiting a reply is separate from receiving order progress. Preserve the client identifier across those paths and reconcile any command whose outcome is unknown.

Run the migration for one product and account before broadening it. Record the installed package version, account mode, REST methods, topics, and expected responses together so the change can be reproduced.