最佳实践指南

产品配置

用户可以通过 GET /api/v2/spot/public/symbols 获取交易所的产品配置。

后续的产品更新，例如最小变动价位变化、新上市，可通过 GET /api/v2/public/annoucements 公告接口查询。

市场数据

用户能够从 WebSocket 频道接收实时的市场数据更新。

深度数据频道：
books,books5,books15现货默认推送频率：200ms，合约默认推送频率：150ms
books1默认推送频率: 10ms

books 对应全量深度数据，首次推送全量数据：snapshot，后续推送增量变化数据：update。
books1 对应1档位深度数据，每次推送：snapshot。
books5 对应5档位深度数据，每次推送：snapshot。
books15 对应15档位深度数据，每次推送：snapshot。

当订单簿没有变化时，系统不会发送新的快照。

订单簿数据由订单事件触发更新并推送。用户在大多数情况下从所有 WebSocket 连接和频道接收到的订单簿数据是相同的。在长时间未有订单簿变化时，系统会通过定时任务触发补偿推送，此时不同服务器可能因时钟差异导致推送序列号略有不同。

系统会推送订单簿的最新状态。当深度发生变化时（包括短时间内的多次变化，如 A→B→A），系统会发送最终状态的更新。

配置账户

创建 API 密钥后，用户可以在交易之前通过 API 或网页端配置账户。

账户配置

用户可以通过以下的 REST API 查看当前账户的信息：

GET /api/v2/spot/account/info

API 会返回账户类型、用户 ID 以及其他与账户相关的信息。

账户类型

Classic 账户系统提供多个独立的账户类型：

账户类型	说明	用途
现货账户	用于现货交易	币币交易
杠杆账户	用于杠杆交易	全仓/逐仓杠杆交易
合约账户	用于合约交易	USDT/USDC/币本位合约
资金账户	用于资金存储	充值、提现、账户间转账

注意：不同账户类型之间需要通过转账接口进行资金划转。

持仓模式

合约交易支持两种持仓模式：

持仓模式	说明
单向持仓模式	只可持有开多或开空仓位。交易所会根据您所指定的持仓数量自动开/平仓
双向持仓模式	可同时持有开多仓位和开空仓位

用户可以通过以下的 REST API 设置持仓模式（设置前需平掉所有仓位和没有挂单）：

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

获取杠杆倍数

用户可以通过以下的 REST API 获取合约杠杆倍数：

GET /api/v2/mix/account/account

目前杠杆倍数设置层面如下：

合约交易：

产品类型	保证金模式	设置层面
U本位合约	全仓	交易对
U本位合约	逐仓	交易对
币本位合约	全仓	交易对
币本位合约	逐仓	交易对
USDC合约	全仓	交易对
USDC合约	逐仓	交易对

设置杠杆倍数

在获取杠杆倍数之后，用户可根据需要进行设置：

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

用户可以运用上述 API 接口，在交易前预先设置每个产品的杠杆倍数。

示例

假设我们有以下的设置和需求：

• 账户类型：合约账户
• 产品类型：U本位合约
• 保证金模式：全仓
• 持仓模式：单向持仓
• 需要设置杠杆倍数为 3 倍的交易对：BTCUSDT、ETHUSDT

设置 BTCUSDT 杠杆倍数为 3 倍的请求体示例：

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

设置 ETHUSDT 的请求体也很类似，不在此一一列举。

订单管理

保证金模式

Classic 账户系统的全仓/逐仓设置更为弹性，用户可以按币对设置全仓或逐仓。因此，用户需要在下单时指定该订单的保证金模式。

各种情景下保证金模式所需的值：

账户类型	产品类型	保证金模式	下单参数
现货账户	现货	N/A	无需指定
杠杆账户	杠杆	全仓	marginMode=crossed
杠杆账户	杠杆	逐仓	marginMode=isolated
合约账户	合约	全仓	marginMode=crossed
合约账户	合约	逐仓	marginMode=isolated

示例

假设我们有以下的设置和订单需求：

• 账户类型：合约账户
• 产品：BTCUSDT（USDT 永续合约）
• 保证金模式：全仓
• 订单方向：买入（开多）
• 订单类型：限价单
• 委托价格：50,000 USDT
• 委托数量：0.1 BTC

查找上表得知需要在下单时设置 marginMode=crossed。

订阅订单频道

下单前，用户应先使用 WebSocket 订阅订单频道，这样才能够监察订单状态（如等待成交、完全成交）和作出相应的操作（如在完全成交后下新单）。

订单频道提供全币种的订阅，用户可在连接到和登入私有 WebSocket 后，传送下面的请求：

订阅维度	产品类型
请求	{"op": "subscribe", "args": [{"instType": "USDT-FUTURES", "channel": "orders", "instId": "default"}]}
成功返回	{"event": "subscribe", "arg": {"channel": "orders", "instType": "USDT-FUTURES", "instId": "default"}}

注：订单频道不设首次订阅全量数据推送，只会在订单状态改变时（如由等待成交到撤单成功）推送该订单的更新。

换言之，用户无法在订阅订单频道时得知当时的订单数据。要获取订阅订单频道前未完成订单的数据，可通过以下的 REST API 查看：

GET /api/v2/spot/trade/unfilled-orders（现货）
GET /api/v2/mix/order/orders-pending（合约）

下单

为了系统能够更容易地识别订单，我们建议用户在下单时填上客户自定义订单 ID（clientOid 字段）。客户自定义订单 ID 需满足^[0-9A-Za-z_:#\\-+\\s]{1,32}$。

clientOid 唯一性检查仅适用于所有挂单，但我们仍推荐用户始终使用唯一的 clientOid 以便于故障排除等工作。

此示例我们会在 clientOid 字段填上 testBTC0123。

在订阅订单频道后，用户便可以准备 BTCUSDT 订单的下单。

用户可通过 REST 和 WebSocket 去下单。

REST API

用户可以通过以下的 REST API 下单，服务器收到请求后会返回订单 ID（orderId）。

REST API	POST /api/v2/mix/order/place-order
请求体	{"symbol": "BTCUSDT", "productType": "usdt-futures", "marginMode": "crossed", "marginCoin": "USDT", "clientOid": "testBTC0123", "side": "buy", "orderType": "limit", "price": "50000", "size": "0.1"}
成功返回	{"code": "00000", "msg": "success", "data": {"clientOid": "testBTC0123", "orderId": "1234567890"}}

注：这只代表交易所已成功收取请求，并把订单 ID 指派到该订单。此时订单有可能还没到撮合系统，用户需要进一步检查订单状态去确认。

WebSocket

用户亦可以通过 WebSocket 下单，理论上比 REST 更有效率及节约资源。

由于 WebSocket 操作为异步通信，用户需要提供信息 ID（id）以便识别其返回。

于私有 WebSocket 登录后，传送以下 WebSocket 信息：

{
  "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"
}

服务器收到请求后，会连同信息 ID（即 NEWtestBTC0123）返回结果，并附上交易所指派的订单 ID（orderId）：

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

注：这只代表交易所已成功收取请求，并把订单 ID 指派到该订单。此时订单有可能还没到撮合系统，用户需要进一步检查订单状态去确认。

检查订单状态

下单后，若订单未返回任何错误（"code": "0"），用户会在 WebSocket 订单频道收到该订单状态为 live 的信息。

订单完全成交后，用户会收到订单状态变更为 filled 的推送信息，并填上其他有关成交的字段。

如果订单部分或全部成交，WebSocket 将分别返回 state = partially_filled 和 filled。

对于立即成交并取消剩余（IOC）、全部成交或立即取消（FOK）以及仅挂单的订单（post only），这些订单可能会被撮合引擎拒绝，用户将收到 live 然后是 canceled 的状态。

用户订单可能会由于各种原因被系统取消，例如清算或自成交。用户可以参考 cancelSource 以确定订单被取消的原因。

一个订单的终止状态为 canceled 或 filled。

订单的每一笔成交都会被系统赋予一个成交 ID（tradeId）。

可能的订单状态：

场景	状态变化
在入口处被拒绝	code 不为零，WebSocket 订单频道无更新推送
下单并立即全部成交	live → filled
下单并立即通过多笔交易成交	live → partially_filled → ... → filled
下单但立即被撮合引擎取消（如 IOC、FOK、仅挂单）	live → canceled（取消原因可从 cancelSource 查询）
下单为 IOC，部分成交后因价格深度不足而被系统取消	live → partially_filled → canceled

改单

改单接口，对于处于委托状态的订单进行修改，支持修改止盈止损及其size/price。

REST：

POST /api/v2/spot/trade/cancel-replace-order（现货）
POST /api/v2/mix/order/modify-order（合约）

经典账户不支持WebSocket改单：

与下单相似，用户应会收到服务器相应 REST 的成功返回，然后于 WebSocket 订单频道收到订单推送更新。

注：订单完全成交或撤单已成功时不能改单。

成功响应仅表示交易所已收到该请求，用户应参考 WebSocket 订单频道以进行确认。

撤单

用户可以以类似的方式，通过 REST 或 WebSocket 撤单。

REST：

POST /api/v2/spot/trade/cancel-order（现货）
POST /api/v2/mix/order/cancel-order（合约）

WebSocket 业务操作请求参数：

{ "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" }

同样，用户应会收到服务器相应 REST / WebSocket 的成功返回。当用户从 WebSocket 订单频道收到订单状态为 canceled 的推送更新时，才代表订单撤单成功。

注：订单完全成交或撤单已成功时不能撤单。

成功响应仅表示交易所已收到该请求，用户应参考 WebSocket 订单频道以进行确认。

批量操作

下单、撤单均支持批量操作，每次最多 20 个订单。

REST：

操作	现货	合约
下单	POST /api/v2/spot/trade/batch-orders	POST /api/v2/mix/order/batch-place-order
撤单	POST /api/v2/spot/trade/batch-cancel-order	POST /api/v2/mix/order/cancel-batch-orders

批量操作容许部分订单操作成功。在收到返回后，用户应检查返回结果内每个订单的 errorCode 和 errorMsg 字段来判断订单的执行结果。

订单时间戳

订单数据中有多个时间戳，供用户跟踪订单状态和延迟。

字段	说明
cTime	订单管理系统在风险检查后的订单创建时间
uTime	订单管理系统最后一次更新订单的时间。在订单修改、成交和取消后进行更新
fillTime	订单成交的时间。fillTime 与公共交易数据的时间相同

分页

Bitget 提供分页功能，以帮助用户从海量数据中轻松获得他们想要的数据。相关的请求参数如下：

参数名	类型	是否必须	描述
idLessThan	String	否	请求此 ID 之前（更旧的数据）的分页内容，传的值为对应接口的 orderId、billId、tradeId 等
startTime	String	否	开始时间，Unix 时间戳（毫秒）
endTime	String	否	结束时间，Unix 时间戳（毫秒）
limit	String	否	返回结果的数量，最大为 100，默认 100 条

拥有分页功能的交易接口罗列如下：

• GET /api/v2/spot/trade/unfilled-orders - 获取未成交订单列表
• GET /api/v2/spot/trade/history-orders - 获取历史订单记录
• GET /api/v2/spot/trade/fills - 获取成交明细
• GET /api/v2/mix/order/orders-history - 获取合约历史订单
• GET /api/v2/mix/order/fills - 获取合约成交明细

自成交保护

交易系统会以母账户维度实施强制自成交保护，同一母账户下所有账户，包括母账户本身和所有子账户，都无法进行自成交。订单的默认 STP 模式为 Cancel Maker，用户亦可以通过下单接口的 stpMode 参数指定订单的 STP 模式。

Bitget 将支持 4 种 STP 模式（stpMode），分别是 none、cancel_maker、cancel_taker 和 cancel_both。

注：强制自成交保护功能仅适用于所有用户，所有订单类型，以及所有订单簿交易产品。

自成交保护模式

Bitget 为用户提供了四种模式，定义了如何阻止自成交，STP 的执行结果取决于 Taker 订单的 STP 模式，挂单表中现有订单的 STP 模式不予考虑。

none模式

订单不受 STP 机制限制，系统不对比 UID，交易正常执行。

cancel_taker 模式

取消 Taker 订单，保留 Maker 订单。

cancel_maker 模式

取消 Maker 订单，保留 Taker 订单。

cancel_both 模式

同时取消 Taker 和 Maker 订单。

账户和持仓

账户

WebSocket 订阅

我们建议使用 WebSocket 订阅账户频道收取账户更新。账户频道设有可选参数 coin，目前只支持全部币种。

该端点返回用户的资产价值，以及其他由于价格变化而持续更新的参数。Bitget 在估值变化时向用户发送更新数据。

连接到私有 WebSocket 和登入后的请求和返回示例：

订阅维度	账户
请求	{"op": "subscribe", "args": [{"instType": "SPOT", "channel": "account", "coin": "default"}]}
成功返回	{"event": "subscribe", "arg": {"channel": "account", "instType": "SPOT"}}

首次订阅全量数据

与订单频道不同，账户频道首次订阅会推送全量数据。

后续推送

之后，用户会根据以下情况收到账户数据推送：

推送类型	说明
事件触发推送	现货：订单成交、划转、充值、提现 合约：下开/平仓委托、开/平仓委托成交、撤单

REST API

用户亦可以通过 REST API 查看账户余额：

GET /api/v2/spot/account/assets（现货账户）
GET /api/v2/mix/account/accounts（合约账户）

REST API 亦提供可选参数 coin，支持单个币种（如 BTC）查询。

示例：

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

当用户于 coin 参数指定币种时，无论该币种层面资产是否为 0，REST API 均会返回该币种的数据，与 WebSocket 账户频道不同。这只适用于曾经持有的币种。

最大可开数量

合约交易时，用户可能想知道该产品最大的开仓数量为多少。用户可以通过以下的 REST API 得知最大可开数量：

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

请求和返回示例：

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

以上的返回结果表示 ETHUSDT 最大可开数量为 0.47 ETH。

最大可转余额

为了获得交易账户或是某个子账户的最大可转余额，用户可以通过以下 API 获取余额：

GET /api/v2/spot/account/assets（现货账户）
GET /api/v2/mix/account/accounts（合约账户）

此端点返回的数据考虑了未偿还的贷款和使用中的保证金。

持仓

用户应该使用 WebSocket 获取持仓信息更新。

WebSocket 订阅

与订单频道类似，持仓频道提供多种维度的订阅。

该端点返回标记价格以及其他持续变化的参数。Bitget 会向用户推送数据更新。

要订阅 BTCUSDT 持仓的数据，用户可在连接到和登入私有 WebSocket 后，传送下表任一请求：

订阅维度	产品类型
请求	{"op": "subscribe", "args": [{"instType": "USDT-FUTURES", "channel": "positions", "instId": "default"}]}
成功返回	{"event": "subscribe", "arg": {"channel": "positions", "instType": "USDT-FUTURES", "instId": "default"}}

首次订阅全量数据

与账户频道一样，持仓频道首次订阅会推送全量数据，推送所有持仓不为 0 的持仓信息。

后续推送

之后，用户会根据以下情况收到持仓数据推送：

推送类型	说明
事件触发推送	下开/平仓委托、开/平仓委托成交、撤单

REST API

用户亦可以通过 REST API 查看持仓信息：

GET /api/v2/mix/position/all-position（所有持仓）
GET /api/v2/mix/position/single-position（单个持仓）