Best Practices Guide

Product Configuration

Users can obtain the exchange's product configuration through GET /api/v2/spot/public/symbols.

Subsequent product updates, such as minimum price increment changes and new listings, can be queried through the GET /api/v2/public/annoucements announcement interface.

Market Data

Users can receive real-time market data updates from WebSocket channels.

Depth Data Channels:
books, books5, books15 default push frequency for spot: 200ms, for futures: 150ms
books1 default push frequency: 10ms

books corresponds to full depth data, first push is full data: snapshot, subsequent pushes are incremental changes: update.
books1 corresponds to 1-level depth data, each push: snapshot.
books5 corresponds to 5-level depth data, each push: snapshot.
books15 corresponds to 15-level depth data, each push: snapshot.

When there are no changes to the order book, the system will not send new snapshots.

Order book data is triggered and pushed by order events. In most cases, users receive the same order book data from all WebSocket connections and channels. When there are no order book changes for an extended period, the system triggers compensatory pushes through scheduled tasks, which may result in slightly different push sequence numbers due to clock differences between servers.

The system pushes the latest state of the order book. When depth changes occur (including multiple changes in a short time, such as A→B→A), the system sends updates for the final state.

Account Configuration

After creating API keys, users can configure their accounts through the API or web interface before trading.

Account Configuration

Users can view current account information through the following REST API:

GET /api/v2/spot/account/info

The API returns account type, user ID, and other account-related information.

Account Types

The Classic account system provides multiple independent account types:

Account Type	Description	Purpose
Spot Account	For spot trading	Crypto-to-crypto trading
Margin Account	For margin trading	Cross/Isolated margin trading
Futures Account	For futures trading	USDT/USDC/Coin-margined futures
Funding Account	For fund storage	Deposits, withdrawals, inter-account transfers

Note: Funds need to be transferred between different account types through the transfer interface.

Position Mode

Futures trading supports two position modes:

Position Mode	Description
One-way Mode	Can only hold long or short positions. The exchange automatically opens/closes positions based on your specified position quantity
Hedge Mode	Can hold both long and short positions simultaneously

Users can set the position mode through the following REST API (all positions must be closed and no pending orders before setting):

POST /api/v2/mix/account/set-position-mode

Get Leverage

Users can get leverage through the following REST API:

GET /api/v2/mix/account/account

Current leverage settings are at the following levels:

Futures Trading:

Product Type	Margin Mode	Setting Level
USDT Futures	Cross	Trading Pair
USDT Futures	Isolated	Trading Pair
Coin Futures	Cross	Trading Pair
Coin Futures	Isolated	Trading Pair
USDC Futures	Cross	Trading Pair
USDC Futures	Isolated	Trading Pair

Set Leverage

After obtaining the leverage, users can set it as needed:

POST /api/v2/mix/account/set-leverage

Users can use the above API interfaces to preset the leverage for each product before trading.

Example

Suppose we have the following settings and requirements:

• Account Type: Futures Account
• Product Type: USDT Futures
• Margin Mode: Cross
• Position Mode: One-way
• Trading pairs requiring 3x leverage: BTCUSDT, ETHUSDT

Request body example for setting BTCUSDT leverage to 3x:

{
  "symbol": "BTCUSDT",
  "productType": "usdt-futures",
  "marginCoin": "usdt",
  "leverage": "3"
}

The request body for setting ETHUSDT is similar and not listed here.

Order Management

Margin Mode

The Classic account system's cross/isolated settings are more flexible, allowing users to set cross or isolated margin by trading pair. Therefore, users need to specify the margin mode when placing orders.

Required margin mode values for various scenarios:

Account Type	Product Type	Margin Mode	Order Parameter
Spot Account	Spot	N/A	Not required
Margin Account	Margin	Cross	marginMode=crossed
Margin Account	Margin	Isolated	marginMode=isolated
Futures Account	Futures	Cross	marginMode=crossed
Futures Account	Futures	Isolated	marginMode=isolated

Example

Suppose we have the following settings and order requirements:

• Account Type: Futures Account
• Product: BTCUSDT (USDT Perpetual)
• Margin Mode: Cross
• Order Direction: Buy (Open Long)
• Order Type: Limit Order
• Order Price: 50,000 USDT
• Order Quantity: 0.1 BTC

Looking up the table above, we need to set marginMode=crossed when placing the order.

Subscribe to Order Channel

Before placing orders, users should first subscribe to the order channel using WebSocket to monitor order status (such as pending, filled) and take appropriate actions (such as placing new orders after complete fill).

The order channel provides subscription for all currencies. After connecting to and logging into the private WebSocket, users can send the following request:

Subscription Dimension	Product Type
Request	{"op": "subscribe", "args": [{"instType": "USDT-FUTURES", "channel": "orders", "instId": "default"}]}
Success Response	{"event": "subscribe", "arg": {"channel": "orders", "instType": "USDT-FUTURES", "instId": "default"}}

Note: The order channel does not push full data on initial subscription, only pushes order updates when order status changes (such as from pending to canceled).

In other words, users cannot know the current order data when subscribing to the order channel. To get data for unfilled orders before subscribing to the order channel, use the following REST API:

GET /api/v2/spot/trade/unfilled-orders (Spot)
GET /api/v2/mix/order/orders-pending (Futures)

Place Order

To make it easier for the system to identify orders, we recommend users fill in the client order ID (clientOid field) when placing orders. The client order ID must match ^[0-9A-Za-z_:#\\-+\\s]{1,32}$.

clientOid uniqueness check only applies to all pending orders, but we still recommend users always use unique clientOid for troubleshooting purposes.

In this example, we will fill in testBTC0123 in the clientOid field.

After subscribing to the order channel, users can prepare to place the BTCUSDT order.

Users can place orders through REST and WebSocket.

REST API

Users can place orders through the following REST API. After the server receives the request, it will return the order ID (orderId).

REST API	POST /api/v2/mix/order/place-order
Request Body	{"symbol": "BTCUSDT", "productType": "usdt-futures", "marginMode": "crossed", "marginCoin": "USDT", "clientOid": "testBTC0123", "side": "buy", "orderType": "limit", "price": "50000", "size": "0.1"}
Success Response	{"code": "00000", "msg": "success", "data": {"clientOid": "testBTC0123", "orderId": "1234567890"}}

Note: This only means the exchange has successfully received the request and assigned an order ID to the order. At this point, the order may not have reached the matching system yet, and users need to further check the order status for confirmation.

WebSocket

Users can also place orders through WebSocket, which is theoretically more efficient and resource-saving than REST.

Since WebSocket operations are asynchronous communication, users need to provide a message ID (id) for identification of its return.

After logging into the private WebSocket, send the following WebSocket message:

{
  "args":[
    {
      "channel":"place-order",
      "id":"NEWtestBTC0123",
      "instId":"BTCUSDT",
      "instType":"USDT-FUTURES",
      "params":{
        "orderType":"limit",
        "side":"buy",
        "size":"2",
        "tradeSide":"open",
        "price":"501",
        "marginCoin":"USDT",
        "force":"gtc",
        "marginMode":"crossed",
        "clientOid":"testBTC0123"
      }
    }
  ],
  "op":"trade"
}

After the server receives the request, it will return the result along with the message ID (i.e., NEWtestBTC0123) and the order ID (orderId) assigned by the exchange:

{
  "event":"trade",
  "arg":[
    {
      "id":"NEWtestBTC0123",
      "instType":"USDT-FUTURES",
      "channel":"place-order",
      "instId":"BTCUSDT",
      "params":{
        "orderId":"1234567890",
        "clientOid":"testBTC0123"
      }
    }
  ],
  "code":0,
  "msg":"Success"
}

Note: This only means the exchange has successfully received the request and assigned an order ID to the order. At this point, the order may not have reached the matching system yet, and users need to further check the order status for confirmation.

Check Order Status

After placing an order, if the order returns no errors ("code": "0"), users will receive a message in the WebSocket order channel indicating the order status is live.

After the order is completely filled, users will receive a push message indicating the order status has changed to filled, along with other fields related to the fill.

If the order is partially or fully filled, WebSocket will return state = partially_filled and filled respectively.

For Immediate-Or-Cancel (IOC), Fill-Or-Kill (FOK), and post-only orders, these orders may be rejected by the matching engine, and users will receive live followed by canceled status.

User orders may be canceled by the system for various reasons, such as liquidation or self-trade. Users can refer to cancelSource to determine the reason for order cancellation.

The terminal status of an order is canceled or filled.

Each fill of an order is assigned a trade ID (tradeId) by the system.

Possible Order States:

Scenario	Status Change
Rejected at entry	code is not zero, no update push in WebSocket order channel
Order placed and immediately fully filled	live → filled
Order placed and immediately filled through multiple trades	live → partially_filled → ... → filled
Order placed but immediately canceled by matching engine (e.g., IOC, FOK, post-only)	live → canceled (cancellation reason can be queried from cancelSource)
IOC order partially filled then canceled by system due to insufficient price depth	live → partially_filled → canceled

Modify Order

The modify order interface allows modification of orders in pending status, supporting modification of take-profit/stop-loss and their size/price.

REST:

POST /api/v2/spot/trade/cancel-replace-order (Spot)
POST /api/v2/mix/order/modify-order (Futures)

Classic account does not support WebSocket order modification:

Similar to placing orders, users should receive a successful REST response from the server, then receive order push updates in the WebSocket order channel.

Note: Orders cannot be modified when completely filled or successfully canceled.

A successful response only indicates the exchange has received the request. Users should refer to the WebSocket order channel for confirmation.

Cancel Order

Users can cancel orders in a similar way through REST or WebSocket.

REST:

POST /api/v2/spot/trade/cancel-order (Spot)
POST /api/v2/mix/order/cancel-order (Futures)

WebSocket Business Operation Request Parameters:

{ "args":[ { "channel":"cancel-order", "id":"xxxxx-xxx-xxx-xxxx-xxxxxx", "instId":"BTCUSDT", "instType":"USDT-FUTURES", "params":{ "orderId":"xxxxxxxxxx", "clientOid":"xxxxx-xxx-xxx-xxxx-xxxxxx" } } ], "op":"trade" }

Similarly, users should receive a successful REST/WebSocket response from the server. When users receive a push update from the WebSocket order channel indicating the order status is canceled, it means the order cancellation was successful.

Note: Orders cannot be canceled when completely filled or successfully canceled.

A successful response only indicates the exchange has received the request. Users should refer to the WebSocket order channel for confirmation.

Batch Operations

Both placing and canceling orders support batch operations, with a maximum of 20 orders per batch.

REST:

Operation	Spot	Futures
Place Order	POST /api/v2/spot/trade/batch-orders	POST /api/v2/mix/order/batch-place-order
Cancel Order	POST /api/v2/spot/trade/batch-cancel-order	POST /api/v2/mix/order/cancel-batch-orders

Batch operations allow partial order operations to succeed. After receiving the response, users should check the errorCode and errorMsg fields for each order in the return result to determine the execution result.

Order Timestamps

Order data contains multiple timestamps for users to track order status and latency.

Field	Description
cTime	Order creation time in the order management system after risk check
uTime	Last update time of the order in the order management system. Updated after order modification, fill, and cancellation
fillTime	Order fill time. fillTime is the same as the time in public trade data

Pagination

Bitget provides pagination functionality to help users easily obtain the data they want from massive amounts of data. Related request parameters are as follows:

Parameter	Type	Required	Description
idLessThan	String	No	Request paginated content before this ID (older data), the value passed is the corresponding interface's orderId, billId, tradeId, etc.
startTime	String	No	Start time, Unix timestamp (milliseconds)
endTime	String	No	End time, Unix timestamp (milliseconds)
limit	String	No	Number of results returned, maximum 100, default 100

Trading interfaces with pagination functionality are listed below:

• GET /api/v2/spot/trade/unfilled-orders - Get unfilled orders list
• GET /api/v2/spot/trade/history-orders - Get historical orders
• GET /api/v2/spot/trade/fills - Get fill details
• GET /api/v2/mix/order/orders-history - Get futures historical orders
• GET /api/v2/mix/order/fills - Get futures fill details

Self-Trade Prevention

The trading system implements mandatory self-trade prevention at the parent account level. All accounts under the same parent account, including the parent account itself and all sub-accounts, cannot self-trade. The default STP mode for orders is Cancel Maker, and users can also specify the order's STP mode through the stpMode parameter in the order placement interface.

Bitget supports 4 STP modes (stpMode): none, cancel_maker, cancel_taker, and cancel_both.

Note: The mandatory self-trade prevention feature applies to all users, all order types, and all order book trading products.

Self-Trade Prevention Modes

Bitget provides users with four modes that define how to prevent self-trading. The execution result of STP depends on the STP mode of the Taker order; the STP mode of existing orders in the order book is not considered.

none Mode

Orders are not restricted by the STP mechanism, the system does not compare UIDs, and trading proceeds normally.

cancel_taker Mode

Cancel the Taker order, keep the Maker order.

cancel_maker Mode

Cancel the Maker order, keep the Taker order.

cancel_both Mode

Cancel both Taker and Maker orders.

Account and Position

Account

WebSocket Subscription

We recommend using WebSocket to subscribe to the account channel to receive account updates. The account channel has an optional coin parameter, currently only supporting all currencies.

This endpoint returns the user's asset value and other parameters that are continuously updated due to price changes. Bitget sends update data to users when valuations change.

Request and response examples after connecting to private WebSocket and logging in:

Subscription Dimension	Account
Request	{"op": "subscribe", "args": [{"instType": "SPOT", "channel": "account", "coin": "default"}]}
Success Response	{"event": "subscribe", "arg": {"channel": "account", "instType": "SPOT"}}

Initial Subscription Full Data

Unlike the order channel, the account channel pushes full data on initial subscription.

Subsequent Pushes

Subsequently, users will receive account data pushes based on the following situations:

Push Type	Description
Event-triggered Push	Spot: Order fill, transfer, deposit, withdrawal Futures: Place open/close position order, open/close position order fill, cancel order

REST API

Users can also view account balance through REST API:

GET /api/v2/spot/account/assets (Spot Account)
GET /api/v2/mix/account/accounts (Futures Account)

REST API also provides an optional coin parameter, supporting single currency (e.g., BTC) queries.

Example:

GET /api/v2/spot/account/assets?coin=BTC

When users specify a currency in the coin parameter, the REST API will return data for that currency regardless of whether the asset at the currency level is 0, unlike the WebSocket account channel. This only applies to currencies that have been held before.

Maximum Openable Quantity

When trading futures, users may want to know the maximum position quantity for that product. Users can get the maximum openable quantity through the following REST API:

GET /api/v2/mix/account/open-count

Request and response example:

Request	GET /api/v2/mix/account/open-count?productType=usdt-futures&symbol=ethusdt&marginCoin=USDT&openPrice=23189.5&leverage=20&openAmount=5000"
Success Response	{"code": "00000", "msg": "success", "requestTime": 1695812285073, "data": {"size": "0.47"}}

The above return result indicates that the maximum openable quantity for ETHUSDT is 0.47 ETH.

Maximum Transferable Balance

To get the maximum transferable balance of a trading account or a sub-account, users can get the balance through the following API:

GET /api/v2/spot/account/assets (Spot Account)
GET /api/v2/mix/account/accounts (Futures Account)

The data returned by this endpoint considers outstanding loans and margin in use.

Position

Users should use WebSocket to get position information updates.

WebSocket Subscription

Similar to the order channel, the position channel provides multiple subscription dimensions.

This endpoint returns mark price and other continuously changing parameters. Bitget pushes data updates to users.

To subscribe to BTCUSDT position data, users can send any of the following requests after connecting to and logging into the private WebSocket:

Subscription Dimension	Product Type
Request	{"op": "subscribe", "args": [{"instType": "USDT-FUTURES", "channel": "positions", "instId": "default"}]}
Success Response	{"event": "subscribe", "arg": {"channel": "positions", "instType": "USDT-FUTURES", "instId": "default"}}

Initial Subscription Full Data

Like the account channel, the position channel pushes full data on initial subscription, pushing all position information where positions are not 0.

Subsequent Pushes

Subsequently, users will receive position data pushes based on the following situations:

Push Type	Description
Event-triggered Push	Place open/close position order, open/close position order fill, cancel order

REST API

Users can also view position information through REST API:

GET /api/v2/mix/position/all-position (All Positions)
GET /api/v2/mix/position/single-position (Single Position)