最佳实践指南

产品配置

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

市场数据

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

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

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

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

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

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

配置账户和子账户

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

账户配置

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

GET /api/v3/account/settings

API 会返回账户模式、持仓模式、资产模式以及许多其他与账户相关的信息。

账户模式

统一交易账户系统提供三个账户模式，分别为现货模式（即将推出）、基础模式以及进阶模式。

账户模式	可交易产品	保证金支持	资格要求
现货模式	仅支持现货交易，不支持杠杆交易和合约交易	不使用保证金	受监管实体下的用户：默认适用该账户模式
基础模式	现货、U本位合约、USDC合约	基础模式下，以 USDT 和 USDC 计价的币对共用同一保证金，这些产品之间的盈亏可以相互抵扣	全球实体下注册的用户：默认适用该账户模式。需完成问卷以激活该模式。
进阶模式	现货、杠杆、U本位合约、USDC合约、币本位	所有资产支持相互保证金	账户权益 ≥ 1,000 USD：完成问卷调查以激活此模式

进阶模式下，所有产品类型的资产都可以用作共享保证金，盈亏可以相互抵消。

更改账户模式可使用api或在网页上进行。

持仓模式

交易所目前支持两种持仓模式。

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

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

POST /api/v3/account/set-hold-mode

全仓/逐仓保证金模式

统一交易账户系统的暂时只支持全仓保证金模式

获取杠杆倍数

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

GET /api/v3/account/settings

目前杠杆倍数没有全局设置，需按照产品交易对分开设置。

产品类型：

持仓模式	产品类型	保证金模式	层面
单向持仓	U本位合约	全仓	交易币对
单向持仓	USDC合约	全仓	交易币对
单向持仓	币本位永续	全仓	交易币对
双向持仓	U本位合约	全仓	交易币对
双向持仓	USDT永续	全仓	交易币对
双向持仓	USDC合约	全仓	交易币对

设置杠杆倍数

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

POST /api/v3/account/set-leverage

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

示例

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

• 账户模式：高级模式
• 持仓模式：单向持仓模式
• 需要设置杠杆倍数为 3 的产品：
  • BTCUSDT
• 以上产品只使用全仓保证金模式

现货杠杆的设置层面为币种，用户可以截取币种去逐一设置，即 BTC、USDT。

设置 BTC 币种杠杆倍数为 3 的请求体示例（适用于卖出 BTCUSDT）：

{
  "leverage": "3.0",
  "coin": "BTC",
  "productType": "MARGIN"
}

设置 USDT的请求体也类似。

下一步就是设置 BTCUSDT 永续合约的杠杆倍数。

因为是U本位合约，用户需要分别设置：

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

在发送了上面的 API REST 请求后，这些产品杠杆倍数的设置便完成了。

订单管理

订阅订单频道

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

订单频道提供多种维度的订阅。要订阅以上 BTCUSDT 订单的数据，用户可在连接到和登入私有 WebSocket 后，传送下表任一请求：

订阅维度	产品类型
请求	{"op": "subscribe", "args": [{"instType": "UTA", "topic": "order"}]}
成功返回	{"event": "subscribe", "arg": {"topic": "order", "instType": "UTA"}}

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

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

GET /api/v3/trade/unfilled-orders

下单

为了系统能够更容易地识别订单，我们建议用户在下单时填上客户自定义订单 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/v3/trade/place-order
请求体	{"category":"SPOT","symbol":"BGBUSDT","orderType":"limit","qty":"123","price":"1.11","side":"buy","posSide":"long","timeInForce":"gtc","reduceOnly":"no"}
成功返回	{"code": "00000", "msg": "success", "requestTime": 1695806875837, "data": {"clientOid": "testBTC0123", "orderId": "1234567890"}}

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

WebSocket

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

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

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

{
  "op": "trade",
  "id": "testBTC0123",
  "category": "spot",
  "topic": "place-order",
  "args": [
    {
      "orderType": "limit",
      "price": "100",
      "qty": "0.1",
      "side": "buy",
      "symbol": "BTCUSDT",
      "timeInForce": "gtc",
      "clientOid": "testBTC0123"
    }
  ]
}

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

{
  "event": "trade",
  "id": "testBTC0123",
  "category": "spot",
  "topic": "place-order",
  "args": [
    {
      "symbol": "BTCUSDT",
      "orderId": "1234567890",
      "clientOid": "testBTC0123",
      "cTime": "1750034397008"
    }
  ],
  "code": "0",
  "msg": "success",
  "ts": "1750034397076"
}

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

检查订单状态

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

订单进入撮合后，用户会收到该订单状态为 new 的信息。

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

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

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

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

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

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

可能的订单状态：

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

改单

改单接口支持所有产品类型的改单，允许用户修改订单的价格（price 字段）和/或数量（qty 字段）。另外 API 也提供 autoCancel 参数，设置订单修改失败时自动撤单的操作。

REST：

POST /api/v3/trade/modify-order

WebSocket 业务操作请求参数：

{ "args": [ { "autoCancel": "yes", "clientOid": "135423791666666666", "orderId": "1354237910666666666", "price": "5", "qty": "2", "symbol":"BTCUSDT" } ], "id": "ae5ea6df-215f-4750-a700-d487d03ac020", "op": "trade", "category": "usdt-futures", "topic": "modify-order" }

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

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

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

撤单

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

REST：

POST /api/v3/trade/cancel-order

WebSocket 业务操作请求参数：

{ "args": [ { "orderId": "xxxxxxxxxxxxxxxxxx", "clientOid": "xxxxxxxxxxxxxxxxxx" } ], "id": "c8a1999c-1f82-409d-870e-f40ff49c4072", "op": "trade", "topic": "cancel-order" }"

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

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

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

批量操作

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

REST：

操作	API
下单	POST /api/v3/trade/place-batch
改单	POST /api/v3/trade/batch-modify-order
撤单	POST /api/v3/trade/cancel-batch

WebSocket 业务操作请求参数：

操作	参数
下单	"topic": "batch-place"
改单	"topic": "batch-modify"
撤单	"topic": "batch-cancel"

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

订单时间戳

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

字段	说明
createdTime	订单管理系统在风险检查后的订单创建时间
updatedTime	订单管理系统最后一次更新订单的时间。在订单修改、成交和取消后进行更新
ts	websocket网关推送时间

分页

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

参数名	类型	是否必须	描述
cursor	String	否	用于翻页，首次查询不传，查询第二页及后面的数据时，取上一次查询返回的最小Id，结果会返回小于该值的数据
startTime	String	否	开始时间，Unix 时间戳（毫秒）
endTime	String	否	结束时间，Unix 时间戳（毫秒）
limit	String	否	返回结果的数量，最大为 100，默认 100 条

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

• GET /api/v3/trade/unfilled-orders - 获取当前委托
• GET /api/v3/trade/history-orders - 获取历史委托
• GET /api/v3/trade/fills - 获取成交明细
• GET /api/v3/account/financial-records - 获取财务记录

自成交保护

交易系统会以母账户维度实施强制自成交保护，同一母账户下所有账户，包括母账户本身和所有子账户，都无法进行自成交。订单的默认 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 订阅账户频道收取账户更新。

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

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

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

首次订阅全量数据

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

后续推送

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

推送类型	说明
事件触发推送	统一账户现货/杠杆/合约委托单成交, 资金结算时，改变balance时（划转、空投、借贷等）

REST API

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

GET /api/v3/account/assets GET /api/v3/account/funding-assets

最大可用数量

高级模式下，启用自动借币能让用户以多于币种余额的数量买入/卖出产品。

在这种情况下，用户便会想知道该产品最大的买入/卖出数量为多少。用户可以轮询以下的 REST API 得知最大可用数量（包括可用余额和交易所的最大可借）：

POST /api/v3/account/max-open-available

请求和返回示例：

请求	{"category":"SPOT","symbol":"BTCUSDT","orderType":"market","side":"sell"}
成功返回	{"code": "00000", "requestTime": 1741851607871, "data": {"available": "52.008255", "maxOpen": "", "buyOpenCost": "", "sellOpenCost": "", "maxBuyOpen": "", "maxSellOpen": ""}, "msg": "success"}

现货/杠杆的 available，当 side=buy 时代表计价币数量，side=sell时代表基础币数量。

最大可转出

为了获得统一账户或是某个子账户的最大可转出金额，用户可以通过 GET /api/v3/account/max-transferable 获取最大可转出。

此端点支持获取借币最大可转出。

持仓

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

WebSocket 订阅

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

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

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

订阅维度	产品类型
请求	{"op": "subscribe","args": [{"instType": "UTA","topic": "position"}]}
成功返回	{"event": "subscribe","arg": {"instType": "UTA","topic": "position"} }

首次订阅全量数据

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

后续推送

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

推送类型	说明
事件触发推送	统一账户合约平仓委托单下单，统一账户合约开仓委托成交，统一账户合约平仓委托成交，统一账户合约平仓委托单改单，统一账户合约平仓委托单撤单

REST API

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

GET /api/v3/position/current-position