English
NAV
console

Welcome

Welcome to Bitget ApiDoc! Click here for quick start

Coming Soon

No. Interface Launch Date Remark

Update Log

20/05/2023

12/05/2023

21/04/2023

28/03/2023

17/03/2023

15/03/2023

13/02/2023

28/12/2022

16/12/2022

06/12/2022

15/11/2022

18/10/2022

19/09/2022

13/09/2022

19/08/2022

15/08/2022

08/08/2022

06/08/2022

03/08/2022

21/07/2022

24/06/2022

05/05/2022

12/02/2022 【Ticker】

07/1/2022

Add main domain name https://api.bitget.com

Request Url rule
/api/spot/v1/public/time 20c/1s
/api/spot/v1/public/currencies 20c/1s
/api/spot/v1/public/products 20c/1s
/api/spot/v1/public/product 20c/1s
/api/spot/v1/market/ticker 20c/1s
/api/spot/v1/market/tickers 20c/1s
/api/spot/v1/market/fills 20c/1s
/api/spot/v1/market/candles 20c/1s
/api/spot/v1/market/depth 20c/1s
/api/spot/v1/account/assets 10c/1s
/api/spot/v1/account/bills 10c/1s
/api/spot/v1/account/transferRecords 20c/1s
/api/spot/v1/trade/orders 10c/1s
/api/spot/v1/trade/batch-orders 5c/1s
/api/spot/v1/trade/cancel-order 10c/1s
/api/spot/v1/trade/cancel-batch-orders 10c/1s
/api/spot/v1/trade/orderInfo 20c/1s
/api/spot/v1/trade/open-orders 20c/1s
/api/spot/v1/trade/history 20c/1s
/api/spot/v1/trade/fills 20c/1s

24/09/ 2021【WebSocket Api 】

15/09/2021 【Add transfer record interface】

05/07/2021【New creation v1 Spot trading document】

Introduction

API Introduction

Welcome to Bitget developer documentation!

This document is the only official document of Bitget API. The capabilities provided by Bitget API will be continuously updated here. Please pay attention to it in time.

You can switch to access different business APIs by clicking the upper menu, and you can switch the document language by clicking the language button on the upper right.

On the right side of the document is an example of request parameters and response results.

Update follow-up

Regarding API additions, updates, and offline information, Bitget will issue announcements in advance. It is recommended that users follow and subscribe to our announcements to obtain relevant information in a timely manner.

You can click here to subscribe to the announcement.

Contact us

If you have any questions or suggestions, feel free to contact us:

Quick start

Prepare to integrate

If you need to use the API, please log in to the web page, then apply the API key and complete the permission configuration, and then develop and trade according to the details of this document.

You can click here to create the API Key after login.

Each user can create 10 sets of Api Keys, and each Api Key can set permissions for reading and trading.

The permissions are described as follows:

After successfully created the API Key, please remember the following information:

SDK / Code example

SDK（Recommended）

Java | Python | Node Js | Golang | PHP

PostMan Demo

PostMan

You should first try to config the APIKey, Secretkey and Passphrase in the Environments tab on left of the PostMan

Interface Type

This chapter is consist of the following two aspects for the interface types:

Public interface

The public interface can be used to obtain configuration information and market data. Public requests can be called without authentication.

Private interface

The private interface can be used for order management and account management. Every private request must be Signatured.

The private interface will be verified from server side with your APIKey.

Access restriction

This chapter mainly focuses on access restrictions:

Rest API

If a valid APIKey is passed with the request, We will use APIKey to limit the frequency; if not, the public IP Address will be used to limit the frequency.

Frequency limit rules: There are separate instructions on each interface. If there is no specific instruction, the frequency limit of general interface is 10 times per second.

Special note: When place orders in batches, 10 orders per currency pair will be counted as one request. For example, a batch order like: 1 order with ETHUSDT, 10 order with BTCUSDT, then the rate-limit will count this batch order as 2 requests.

API domain

You can use different domain as below Rest API.

Domain REST API Recommend to use
Domain1 https://api.bitget.com Main Domain
Domain2 https://capi.bitget.com Old domain

API Public parameters

side

Trade direction

String Description
sell Sell
buy Buy

orderType

Order type

String Description
limit Limit order
market Market order

force

Order type

String Description
normal Good till cancel
post_only Maker Only
fok Fill Or Kill（FOK）
ioc Immediate-Or-Cancel（IOC）

status

Order status

String Description
init initial, inserted into DB
new Unfilled, pending in orderbook
partial_fill Partially filled
full_fill Fully filled
cancelled Cancelled

groupType

Major types of transaction

String Description
deposit Deposit
withdraw Withdrawal
transaction Trade
transfer Transfer
other Others

bizType

Business type

String Description
deposit Deposit
withdraw Withdrawal
buy Buy
Sell sell
deduction of handling fee deduction of handling fee
transfer-in Transfer-in
transfer-out Transfer-out
rebate rewards rebate rewards
airdrop rewards airdrop rewards
USDT contract rewards USDT contract rewards
mix contract rewards mix contract rewards
System lock System lock
User lock User lock

deposit withdrawal order status

String Description
cancel Cancel
reject Reject
success Success
wallet-fail Wallet failed
wallet-processing Wallet processing
first-audit 1st audit
recheck 2nd audit
first-reject 1st audit rejected
recheck-reject 2nd audit rejected

withdrawal type

User withdrawal address query

String Description
chain-on On blockchain
inner-transfer Internal address

triggerType

String Description
fill_price fill price
market_price mark price

accountType

String Description
EXCHANGE spot account
CONTRACT contract account
USDT_MIX USDT Future account
USD_MIX Mix account
USDC_MIX usdc futures
MARGIN_CROSS margin cross
MARGIN_ISOLATED margin isolated

Candlestick line timeframe

granularity

fromType,toType(transfer in type，transfer out type)

String Description
spot spot asset coin
mix_usdt USDT transfer only
mix_usd BTC, ETH, EOS, XRP, USDC
mix_usdc USDC transfer only
margin_cross cross margin account
margin_isolated isolated margin account

enterPointSource

String Description
WEB WEB Client
APP APP Client
API API Client
SYS SYS Client
ANDROID ANDROID Client
IOS IOS Client

p2pAdvertisementStatus

String Description
online p2p advertisement online
offline p2p advertisement offline
editing p2p advertisement editing
completed p2p advertisement completed

p2pOrderStatus

String Description
pending_pay p2p order pending pay
paid p2p order paid
appeal p2p order appeal
completed p2p order completed
cancelled p2p order cancelled

orderSource

String Description
normal normal order
market market order
spot_trader_buy spot trace trader buy (trader)
spot_follower_buy Spot follower buy (follower)
spot_trader_sell spot trace trader sell (trader)
spot_follower_sell Spot follower sell (follower)

API Verification

Initiating request

The header of all REST requests must contain the following keys:

//Java
System.currentTimeMillis();

//python
import time
time.time_ns() / 1000000

//Golang
import (
  "time"
)
int64(time.Now().UnixNano()/1000000)

//Javascript
Math.round(new Date())

//PHP
microtime(true) * 1000;

Signature

The request header of ACCESS-SIGN is obtained by encrypting timestamp + method.toUpperCase() + requestPath + "?" + queryString + body **string (+ means string concat) encrypt by **HMAC SHA256 **algorithm, and encode the encrypted result through **BASE64.

Description for each parameter of the signature

When queryString is empty, the signature format

timestamp + method.toUpperCase() + requestPath + body

 

When queryString is not empty, the signature format

timestamp + method.toUpperCase() + requestPath + "?" + queryString + body

For example

To obtain in-depth information, take BTCUSDT as an example:

Generate the string to be signed:

'1591089508404GET/api/spot/v1/market/depth?symbol=btcusdt_spbl&limit=20'

Place order，take BTCUSDT as an example:

Generate the string to be signed:

'1561022985382POST/api/spot/v3/order/order{"symbol":"btcusdt_spbl","size":"8","side":"buy","price":"1","orderType":"limit","clientOrderId":"bitget#123456"}'

 

Steps to generate the final signature

Step 1. Use the private key secretkey to encrypt the string to be signed with hmac sha256

String payload = hmac_sha256(secretkey, Message);

 

Step 2. Base64 encoding for Signature.

String signature = base64.encode(payload);

Signature Demo Code

Java

public static String generate(String timestamp, String method, String requestPath,
                                  String queryString, String body, String secretKey)
            throws CloneNotSupportedException, InvalidKeyException, UnsupportedEncodingException {

        method = method.toUpperCase();
        body = StringUtils.defaultIfBlank(body, StringUtils.EMPTY);
        queryString = StringUtils.isBlank(queryString) ? StringUtils.EMPTY : "?" + queryString;

        String preHash = timestamp + method + requestPath + queryString + body;
        System.out.println(preHash);
        byte[] secretKeyBytes = secretKey.getBytes(SignatureUtils.CHARSET);
        SecretKeySpec secretKeySpec = new SecretKeySpec(secretKeyBytes, SignatureUtils.HMAC_SHA256);
        Mac mac = (Mac) SignatureUtils.MAC.clone();
        mac.init(secretKeySpec);
        return Base64.getEncoder().encodeToString(mac.doFinal(preHash.getBytes(SignatureUtils.CHARSET)));
    }


public static void main(String[] args) throws Exception {
      String msg=generate("1659927638003","POST","/api/spot/v1/trade/orders" ,null,"{"symbol":"TRXUSDT_SPBL","side":"buy","orderType":"limit","force":"normal","price":"0.046317","quantity":"1212"}","");
      System.out.println(msg);
    }

Python

def sign(message, secret_key):
    mac = hmac.new(bytes(secret_key, encoding='utf8'), bytes(message, encoding='utf-8'), digestmod='sha256')
    d = mac.digest()
    return base64.b64encode(d)


def pre_hash(timestamp, method, request_path, body):
    return str(timestamp) + str.upper(method) + request_path + body



if __name__ == '__main__':
    signStr = sign(pre_hash('1659927638003', 'POST', '/api/spot/v1/trade/orders', str('{"symbol":"TRXUSDT_SPBL","side":"buy","orderType":"limit","force":"normal","price":"0.046317","quantity":"1212"}')), '')
    print(signStr)

For more demo code on other languages, please refer to SDK/Code Example

Request interaction

All requests are based on the Https protocol, and the Content-Type in the POST request header information needs to be standardized as:'application/json'.

Request interaction description

Success

HTTP status code 200 indicates a successful response and may contain content. If the response contains content, it will be displayed in the corresponding return content.

Common error codes

Standard Specification

Timestamp

The unit of ACCESS-TIMESTAMP in the request signature is milliseconds. The timestamp of the request must be within 30 seconds of the API service time, otherwise the request will be considered expired and rejected. If there is a large deviation between the local server time and the API server time, we recommend that you update the timestamp by query and compare the time difference between API server time and the time in your code.

Frequency limiting rules

If the request is too frequent, the system will automatically limit the request and return the “429 too many requests” status code in the http header.

· Public interface: For the market information interfaces, the global rate limit is 2 seconds with max. 20 requests.

· Authorization interface: restrict the call of the authorization interface through apikey, refer to the frequency limitation rule of each interface for frequency limitation.

Request format

There are currently only two supported request methods: GET and POST

RestAPI

Public

Get Server Time

Rate Limit: 20 times/1s (IP)

HTTP Request

Obtain server time

Request Example

curl "https://api.bitget.com/api/spot/v1/public/time"

Response

{
    "code": "00000",
    "msg": "success",
    "requestTime": 1622097118135,
    "data": 1622097118134
}

Get Coin List

Rate Limit: 3 times/1s (IP)

HTTP Request 

Obtain all coins information on the platform

Request Example

curl "https://api.bitget.com/api/spot/v1/public/currencies"

Response

{
    "code":"00000",
    "msg":"success",
    "data":[
        {
            "coinId":"1",
            "coinName":"BTC",
            "transfer":"true",
            "chains":[
                {
                    "chain":null,
                    "needTag":"false",
                    "withdrawable":"true",
                    "rechargeAble":"true",
                    "withdrawFee":"0.005",
                    "depositConfirm":"1",
                    "withdrawConfirm":"1",
                    "minDepositAmount":"0.001",
                    "minWithdrawAmount":"0.001",
                    "browserUrl":"https://blockchair.com/bitcoin/testnet/transaction/"
                }
            ]
        }
    ]
}

Response Parameters

Parameter Description
coinId Coin ID
coinName Coin name
transfer Whether can be transferred
chains
> chain Chain name
> needTag Whether need to tag
> withdrawable Whether can be withdrawn
> rechargeAble Whether can deposit
> withdrawFee Withdrawal fee, 0.0006 means 0.06% BTC fee per BTC
> depositConfirm Deposit no. of confirmation block
> withdrawConfirm Withdrawal no. of confirmation block
> minDepositAmount Min. deposit amount, BTC
> minWithdrawAmount Min. withdrawal amount, BTC
> browserUrl Blockchain browser

Get Symbols

Rate Limit: 20 times/1s (IP)

HTTP Request 

obtain basic configuration information of all trading pairs

Request Example

curl "https://api.bitget.com/api/spot/v1/public/products"

Response

{
    "code":"00000",
    "msg":"success",
    "data":[
        {
            "symbol":"BTCUSDT_SPBL",
            "symbolName":"BTCUSDT",
            "baseCoin":"BTC",
            "quoteCoin":"USDT",
            "minTradeAmount":"0.0001",
            "maxTradeAmount":"10000",
            "takerFeeRate":"0.001",
            "makerFeeRate":"0.001",
            "priceScale":"4",
            "quantityScale":"8",
            "minTradeUSDT":"5",
            "status":"online",
            "buyLimitPriceRatio": "0.05",
            "sellLimitPriceRatio": "0.05"
        }
    ]
}

Response Parameter

Parameter Description
symbol symbol Id
symbolName symbol name
baseCoin Base coin
quoteCoin Denomination coin
minTradeAmount Min. trading amount
maxTradeAmount Max. trading amount
takerFeeRate Taker transaction fee rate
makerFeeRate Maker transaction fee rate
priceScale Pricing scale
quantityScale Quantity scale
status Status: offline,gray,online
minTradeUSDT Min trade USDT amount
buyLimitPriceRatio Buy price gap from market price, "0.05" means: 5%
sellLimitPriceRatio Sell price gap from market price, "0.05" means: 5%

Get Single Symbol

Rate Limit: 20 times/1s (IP)

HTTP Request 

obtain all ticker information

Request parameter

Parameter name Parameter type Required Description
symbol String Yes Symbol Id

Request Example

curl "https://api.bitget.com/api/spot/v1/public/product?symbol=BTCUSDT_SPBL"

Response

{
    "code":"00000",
    "msg":"success",
    "data":[
        {
            "symbol":"BTCUSDT_SPBL",
            "symbolName":"BTCUSDT",
            "baseCoin":"BTC",
            "quoteCoin":"USDT",
            "minTradeAmount":"0.0001",
            "maxTradeAmount":"10000",
            "takerFeeRate":"0.001",
            "makerFeeRate":"0.001",
            "priceScale":"4",
            "quantityScale":"8",
            "minTradeUSDT":"5",
            "status":"online",
            "buyLimitPriceRatio": "0.05",
            "sellLimitPriceRatio": "0.05"
        }
    ]
}

Response Parameter

Parameter Description
symbol Symbol ID
symbolName Symbol Name
baseCoin Base coin
quoteCoin Denomination coin
minTradeAmount Min. trading amount
maxTradeAmount Max. trading amount
takerFeeRate Taker transaction fee rate
makerFeeRate Maker transaction fee rate
priceScale Pricing scale
quantityScale Quantity scale
status Status
minTradeUSDT Min trade USDT amount
buyLimitPriceRatio Buy price gap from market price, "0.05" means: 5%
sellLimitPriceRatio Sell price gap from market price, "0.05" means: 5%

Market

Get Single Ticker

Rate Limit: 20 times/1s (IP)

HTTP Request 

Request parameter

Parameter name Parameter type Required Description
symbol String Yes Symbol ID

Request Example

curl "https://api.bitget.com/api/spot/v1/market/ticker?symbol=BTCUSDT_SPBL"

Response

{
    "code": "00000",
    "msg": "success",
    "data": {
        "symbol": "BTCUSDT",
        "high24h": "24175.65",
        "low24h": "23677.75",
        "close": "24014.11",
        "quoteVol": "177689342.3025",
        "baseVol": "7421.5009",
        "usdtVol": "177689342.302407",
        "ts": "1660704288118",
        "buyOne": "24013.94",
        "sellOne": "24014.06",
        "bidSz": "0.0663",
        "askSz": "0.0119",
        "openUtc0": "23856.72",
        "changeUtc":"0.00301",
        "change":"0.00069"
    }
}

Response Parameter

Parameter Description
symbol Symbol Id
high24h 24h highest price
close Latest transaction price
low24h 24h lowest price
ts System timestamp, milliseconds
baseVol Base coin volume
quoteVol Denomination coin volume
buyOne buy one price
sellOne sell one price
bidSz Bid1 size
askSz Ask1 size
usdtVol USDT volume
openUtc0 UTC0 opening price
changeUtc change since UTC0, 0.01 means 1%
change change, 0.01 means 1%

Get All Tickers

Rate Limit: 20 times/1s (IP)

HTTP Request

Request Example 

curl "https://api.bitget.com/api/spot/v1/market/tickers"

Response

{
    "code": "00000",
    "msg": "success",
    "data": [{
        "symbol": "BTCUSDT",
        "high24h": "24175.65",
        "low24h": "23677.75",
        "close": "24014.11",
        "quoteVol": "177689342.3025",
        "baseVol": "7421.5009",
        "usdtVol": "177689342.302407",
        "ts": "1660704288118",
        "buyOne": "24013.94",
        "sellOne": "24014.06",
        "bidSz": "0.0663",
        "askSz": "0.0119",
        "openUtc0": "23856.72",
        "changeUtc":"0.00301",
        "change":"0.00069"
    }]
}

Response Parameter

Parameter Description
symbol Symbol Id
high24h 24h highest price
close Latest transaction price
low24h 24h lowest price
ts System timestamp
baseVol Base coin volume
quoteVol Denomination coin volume
buyOne buy one price
sellOne sell one price
bidSz Bid1 size
askSz Ask1 size
usdtVol USDT volume
openUtc0 UTC0 open price
changeUtc change since UTC0, 0.01 means 1%
change change, 0.01 means 1%

Get Recent Trades

Get most recent 500 trades

Rate Limit: 10 times/1s (IP)

HTTP Request

Request parameter

Parameter name Parameter type Required Description
symbol String Yes Symbol ID
limit String No Default is 100，Max. is 500

Request Example 

curl "https://api.bitget.com/api/spot/v1/market/fills?symbol=BTCUSDT_SPBL"

Response

{
    "code":"00000",
    "msg":"success",
    "data":[
        {
            "symbol":"BFTUSDT_SPBL",
            "tradeId":"781698148534505473",
            "side":"buy",
            "fillPrice":"2.38735",
            "fillQuantity":"2470.6224",
            "fillTime":"1622097282536"
        },
        {
            "symbol":"BFTUSDT_SPBL",
            "tradeId":"781698140590493697",
            "side":"sell",
            "fillPrice":"2.38649",
            "fillQuantity":"3239.7976",
            "fillTime":"1622097280642"
        }
    ]
}

Response Parameter

Parameter Description
symbol Symbol ID
tradeId Filled order ID
side Trade direction, 'buy', 'sell'
fillPrice Transaction price, quote coin
fillQuantity Transaction quantity, base coin
fillTime Transaction time

Get Market Trades

Fetch trade history within 30 days, response will be cached with same param for 10 minutes, please revise 'endTime' to get the latest records

Rate Limit: 10 times/1s (IP)

HTTP Request

Request parameter

Parameter name Parameter type Required Description
symbol String Yes Symbol ID
limit String No Default is 500, Max is 1000
tradeId String No tradeId, return records with 'tradeId' less than the provided value
startTime String No startTime, ms
endTime String No endTime, ms

Request Example 

curl "https://api.bitget.com/api/spot/v1/market/fills-history?symbol=btcusdt_spbl&limit=2&tradeId=1020221685304578123&startTime=1678965010861&endTime=1678965910861"

Response

{
    "code": "00000",
    "msg": "success",
    "requestTime": 1678965934811,
    "data": [
        {
            "symbol": "BTCUSDT_SPBL",
            "tradeId": "1020221668657385473",
            "side": "Sell",
            "fillPrice": "21120",
            "fillQuantity": "0.5985",
            "fillTime": "1678965721000"
        },
        {
            "symbol": "BTCUSDT_SPBL",
            "tradeId": "1020221660121976833",
            "side": "Buy",
            "fillPrice": "21120",
            "fillQuantity": "0.3119",
            "fillTime": "1678965719000"
        }
    ]
}

Response Parameter

Parameter Description
symbol Symbol ID
tradeId Filled order ID, desc
side Trade direction, 'Buy', 'Sell'
fillPrice Transaction price, quote coin
fillQuantity Transaction quantity, base coin
fillTime Transaction time

Get Candle Data

Rate Limit: 20 times/1s (IP)

HTTP Request 

obtain candlestick line data

Request parameter

Parameter name Parameter type Required Description
symbol String Yes Symbol Id
period String Yes Candlestick line time unit, granularity (refer to the following list for values)
after String No Time after, milliseconds, return greater than or equals
before String No Time before, milliseconds, return less than or equals
limit String No Default 100, max 1000

Request Example

curl "https://api.bitget.com/api/spot/v1/market/candles?symbol=BTCUSDT_SPBL&period=1min&after=1659076670000&before=1659080270000&limit=100"

Response

{
    "code":"00000",
    "msg":"success",
    "data":[
        {
            "open":"2.34517",
            "high":"2.34771",
            "low":"2.34214",
            "close":"2.34555",
            "quoteVol":"189631.101357091",
            "baseVol":"80862.6823",
            "usdtVol":"189631.101357091",
            "ts":"1622091360000"
        },
        {
            "open":"2.34391",
            "high":"2.34903",
            "low":"2.34391",
            "close":"2.34608",
            "quoteVol":"167725.002115681",
            "baseVol":"71479.3205",
            "usdtVol":"167725.002115681",
            "ts":"1622091420000"
        }
    ]
}

Response Parameter

Parameter Description
ts System timestamp
open Opening price
high Highest price
low Lowest price
close Closing price
baseVol Base coin volume
quoteVol Denomination coin volume
usdtVol USDT volume

period

Get Depth

Rate Limit: 20 times/1s (IP)

HTTP Request

Request Example

curl "https://api.bitget.com/api/spot/v1/market/depth?symbol=BTCUSDT_SPBL&type=step0&limit=100"

Response

{
    "code":"00000",
    "msg":"success",
    "data":{
        "asks":[
            [
                "38084.5",
                "0.0039"
            ],
            [
                "38085.7",
                "0.0018"
            ],
            [
                "38086.7",
                "0.0310"
            ],
            [
                "38088.2",
                "0.5303"
            ]
        ],
        "bids":[
            [
                "38073.7",
                "0.4993000000000000"
            ],
            [
                "38073.4",
                "0.4500"
            ],
            [
                "38073.3",
                "0.1179"
            ],
            [
                "38071.5",
                "0.2162"
            ]
        ],
        "timestamp":"1622102974025"
    }
}

Request parameter

Parameter name Parameter type Required Description
symbol String Yes Symbol ID
type String Yes Default: step0: do not merge, value: step0, step1, step2, step3, step4, step5
limit String No default 150

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

VIP fee rate

Rate Limit: 10 times/1s (IP)

HTTP Request

Request Example

curl "https://api.bitget.com/api/spot/v1/market/spot-vip-level"

Response

{
    "code": "00000",
    "msg": "success",
    "requestTime": 1675759699382,
    "data": [
        {
            "level": 1,
            "dealAmount": "1000000",
            "assetAmount": "50000",
            "takerFeeRate": "0",
            "makerFeeRate": "0",
            "withdrawAmount": "300",
            "withdrawAmountUSDT": "5000000"
        }
    ]
}

Response parameter

Parameter name Parameter type Required Description
level Integer Yes VIP level
dealAmount BigDecimal Yes Transaction volume (USDT) within 30 days
assetAmount BigDecimal Yes Asset amount (USDT)
takerFeeRate BigDecimal No Taker fee rate, actual fee rate please refer to official announcement when '0'
makerFeeRate BigDecimal No Maker fee rate, actual fee rate please refer to official announcement when '0'
withdrawAmount BigDecimal Yes 24 hours withdraw amount (BTC)
withdrawAmountUSDT BigDecimal Yes 24 hours withdraw amount (USDT)

Wallet

Transfer

Rate Limit：5/sec (uid)

HTTP Request

Request Example

curl -X POST "https://api.bitget.com/api/spot/v1/wallet/transfer" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"fromType": "spot","toType": "mix_usdt","amount": "100","coin": "USDT"}'

Response:

{
    "code":"00000",
    "msg":"success"
}

Request Parameter

Parameter type Required description
fromType String Yes out account type
toType String Yes inner account type
amount String Yes transfer amount
coin String Yes transfer coin
clientOid String No custom id

fromType/toType restriction

fromType toType Desc
spot spot Good to go
spot mix_usdt Only USDT
spot mix_usd Only margin Coin like BTC, ETH, EOS, XRP, USDC
spot mix_usdc Only USDC
mix_usdt spot Only USDT
mix_usdt mix_usd Not allow
mix_usdt mix_usdc Not allow
mix_usdt mix_usdt Only USDT
mix_usd spot Only margin Coin like BTC, ETH, EOS, XRP, USDC
mix_usd mix_usdt Not allow
mix_usd mix_usdc Only USDC
mix_usd mix_usd Only margin Coin like BTC, ETH, EOS, XRP, USDC
mix_usdc spot Only USDC
mix_usdc mix_usdt Not allow
mix_usdc mix_usd Only USDC
mix_usdc mix_usdc Only USDC
xxx margin_cross Only coins that supported by spot cross-margin
xxx margin_isolated Only coins that supported by spot isolated-margin

 

 

 

 

 

 

Transfer V2

Rate Limit：5/sec (uid)

HTTP Request

Request Example

curl -X POST "https://api.bitget.com/api/spot/v1/wallet/transfer-v2" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"fromType": "spot","toType": "mix_usdt","amount": "100","coin": "USDT"}'

Response:

{
    "code":"00000",
    "msg":"success",
    "data": {
        "transferId":"123456",
        "clientOrderId":"x123"
    }
}

Request Parameter

Parameter type Required description
fromType String Yes out account type
toType String Yes inner account type
amount String Yes transfer amount
coin String Yes transfer coin
clientOid String No custom id

Response parameter

Parameter name Parameter type Required Description
transferId String Yes Transfer ID
clientOrderId String Yes Client Order ID

fromType/toType restriction

fromType toType Desc
spot spot Good to go
spot mix_usdt Only USDT
spot mix_usd Only margin Coin like BTC, ETH, EOS, XRP, USDC
spot mix_usdc Only USDC
mix_usdt spot Only USDT
mix_usdt mix_usd Not allow
mix_usdt mix_usdc Not allow
mix_usdt mix_usdt Only USDT
mix_usd spot Only margin Coin like BTC, ETH, EOS, XRP, USDC
mix_usd mix_usdt Not allow
mix_usd mix_usdc Only USDC
mix_usd mix_usd Only margin Coin like BTC, ETH, EOS, XRP, USDC
mix_usdc spot Only USDC
mix_usdc mix_usdt Not allow
mix_usdc mix_usd Only USDC
mix_usdc mix_usdc Only USDC
xxx margin_cross Only coins that supported by spot cross-margin
xxx margin_isolated Only coins that supported by spot isolated-margin

 

 

 

 

 

 

Sub Transfer

This interface supports to transfer in below ways

Transfer from Transfer to Desc
main account sub account Sub account belongs to the main account
sub account sub account Two sub account belongs to the same main account
sub account main account Sub account belongs to the main account

1). Main/Sub transfer requires IP whitelist

2). Transfer between fromUserId and toUserId should have direct/brother relationship

3). Note the risk may increase when transfer out from account with cross margin mode

 

Rate Limit：2/sec (uid)

HTTP Request

Request Example

curl -X POST "https://api.bitget.com/api/spot/v1/wallet/subTransfer" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"fromType": "spot","toType": "mix_usdt","amount": "100","coin": "USDT","clientOid":"12345","fromUserId":"1","toUserId":"2"}'

Response:

{
    "code":"00000",
    "msg":"success"
}

Request Parameter

Parameter type Required description
fromType String Yes from account type
toType String Yes to account type
amount String Yes transfer amount
coin String Yes transfer coin
clientOid String Yes unique custom id, idempotent control
fromUserId String Yes from user ID
toUserId String Yes to user ID

 

 

 

 

 

 

fromType/toType restriction

fromType toType Desc
spot spot Good to go
spot mix_usdt Only USDT
spot mix_usd Only margin Coin like BTC, ETH, EOS, XRP, USDC
spot mix_usdc Only USDC
mix_usdt spot Only USDT
mix_usdt mix_usd Not allow
mix_usdt mix_usdc Not allow
mix_usdt mix_usdt Only USDT
mix_usd spot Only margin Coin like BTC, ETH, EOS, XRP, USDC
mix_usd mix_usdt Not allow
mix_usd mix_usdc Only USDC
mix_usd mix_usd Only margin Coin like BTC, ETH, EOS, XRP, USDC
mix_usdc spot Only USDC
mix_usdc mix_usdt Not allow
mix_usdc mix_usd Only USDC
mix_usdc mix_usdc Only USDC
xxx margin_cross Only coins that supported by spot cross-margin
xxx margin_isolated Only coins that supported by spot isolated-margin

Get Coin Address

Rate Limit：5/sec (uid)

HTTP Request

Request Parameter

Parameter Type Required Description
coin String Yes currency name
chain String Yes chain name

Request Example

curl "https://api.bitget.com/api/spot/v1/wallet/deposit-address?coin=USDT&chain=trc20" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

Response:

{
  "code": "00000",
  "msg": "success",
  "data": {
    "address": "1HPn8Rx2y6nNSfagQBKy27GB99Vbzg89wv",
    "chain": "BTC-Bitcoin",
    "coin": "BTC",
    "tag": "",
    "url": "https://btc.com/1HPn8Rx2y6nNSfagQBKy27GB99Vbzg89wv"
  }
}

Response Description

Parameter Description
address currency address
chain chain name
coin currency name
tag tag
url Blockchain browser address

Withdraw

Just withdraw coins on the chain

Rate Limit：5/sec (Uid)

HTTP Request

Request Parameter

Parameter Type Required Description
coin String Yes currency name
address String Yes withdraw address
chain String Yes chain name
tag String No tag
amount String Yes Withdraw amount
remark String No remark
clientOid String No custom id

'address' should be in your main-account's address book

Request Example

curl -X POST "https://api.bitget.com/api/spot/v1/wallet/withdrawal" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"coin": "USDT","address": "TBQ2LGFysnqkscvKqLBxnVVVw7ohiDvbdZ","chain": "trc20","amount": "10"}'

Response:

{
  "code": "00000",
  "msg": "success",
  "data": "888291686266343424"
}

Response Description

Parameter Description
data Order ID

Withdraw V2

Just withdraw coins on the chain

Rate Limit：5/sec (Uid)

HTTP Request

Request Parameter

Parameter Type Required Description
coin String Yes currency name
address String Yes withdraw address
chain String Yes chain name
tag String No tag
amount String Yes Withdraw amount
remark String No remark
clientOid String No custom id

'address' should be in your main-account's address book

Request Example

curl -X POST "https://api.bitget.com/api/spot/v1/wallet/withdrawal-v2" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"coin": "USDT","address": "TBQ2LGFysnqkscvKqLBxnVVVw7ohiDvbdZ","chain": "trc20","amount": "10"}'

Response:

{
  "code": "00000",
  "msg": "success",
  "data": {
    "orderId":888291686266343424",
    "clientOrderId":"123"
  }
}

Response Description

Parameter Description
orderId Order ID
clientOrderId client order ID

Inner Withdraw

Internal withdrawal means that both users are on the Bitget platform

Withdraw money directly in the form of uid, without going on the chain, no need to pass the address

Rate Limit：5/sec (Uid)

HTTP Request

Request Parameter

Parameter Type Required Description
coin String Yes currency
toUid String Yes target uid
amount String Yes Withdraw amount
clientOid String No custom id

Request Example

curl -X POST "https://api.bitget.com/api/spot/v1/wallet/withdrawal-inner" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"coin": "USDT","toUid": "6314497154","amount": "10"}'

Response

{
  "code": "00000",
  "msg": "success",
  "data": "888291686266343424"
}

Response Description

Parameter description
data Order ID

Inner Withdraw v2

Internal withdrawal means that both users are on the Bitget platform

Withdraw money directly in the form of uid, without going on the chain, no need to pass the address

Rate Limit：5/sec (Uid)

HTTP Request

Request Parameter

Parameter Type Required Description
coin String Yes currency
toUid String Yes target uid
amount String Yes Withdraw amount
clientOid String No custom id

Request Example

curl -X POST "https://api.bitget.com/api/spot/v1/wallet/withdrawal-inner-v2" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"coin": "USDT","toUid": "6314497154","amount": "10"}'

Response

{
  "code": "00000",
  "msg": "success",
  "data": {
    "orderId":888291686266343424",
    "clientOrderId":"123"
  }
}

Response Description

Parameter description
orderId Order ID
clientOrderId client order ID

Get Withdraw list

Rate Limit：20/1s (Uid)

HTTP Request

Request Parameter

Parameter Type Required Description
coin String No currency
clientOid String No clientOid
startTime String Yes start Time (timestamp ms)
endTime String Yes end Time(timestamp ms)
pageNo String No pageNo default 1
pageSize String No pageSize default 20, max 100

Request Example

curl "https://api.bitget.com/api/spot/v1/wallet/withdrawal-list?coin=USDT&clientOid=123&startTime=1659036670000&endTime=1659076670000&pageNo=1&pageSize=20" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

Response:

{
    "code": "00000",
    "msg": "success",
    "requestTime": 1654507973411,
    "data": [
        {
            "id": "912533114861326336",
            "txId": "912533114861326336",
            "coin": "USDT",
            "clientOid": "123",
            "type": "withdraw",
            "amount": "10.00000000",
            "status": "success",
            "toAddress": "7713789662",
            "fee": "0.00000000",
            "chain": "erc20",
            "confirm": "0",
            "tag": null,
            "cTime": "1653290769222",
            "uTime": "1653290769222"
        }
    ]
}

Response Description

Parameter Description
id order Id
txId trade Id
coin currency
clientOid clientOid
type type
amount withdraw amount
status status
toAddress Withdraw address
fee Withdraw fee
chain Withdraw chain
confirm confirm times for withdraw
tag tag
cTime create time
uTime update time

Get Deposit List

Rate Limit：20/1s (Uid)

HTTP Request

Request Parameter

Parameter Type Required Description
coin String No currency
startTime String Yes start time(timestamp ms)
endTime String Yes end time(timestamp ms)
pageNo String No pageNo default 1
pageSize String No pageSize default20 Max 100

Request Example

curl "https://api.bitget.com/api/spot/v1/wallet/deposit-list?coin=USDT&startTime=1659036670000&endTime=1659076670000&pageNo=1&pageSize=20" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

Response:

{
    "code": "00000",
    "msg": "success",
    "requestTime": 1654507973411,
    "data": [
        {
            "id": "912533114861326336",
            "txId": "912533114861326336",
            "coin": "USDT",
            "type": "withdraw",
            "amount": "10.00000000",
            "status": "success",
            "toAddress": "7713789662",
            "fee":"0",
            "chain": "erc20",
            "confirm":"10",
            "tag": null,
            "cTime": "1653290769222",
            "uTime": "1653290769222"
        }
    ]
}

Response Data

Parameter Description
id order Id
txId trade Id
coin currency
type type
amount deposit amount
status status
toAddress deposit address
fee fee, might be null
confirm confirm, might be null
chain deposit chain
tag tag
cTime create time
uTime update time

Get User Fee Ratio

Rate Limit：10/sec (Uid)

HTTP Request

Request Parameter

Parameter name Parameter type Required Description
symbol String yes symbol（mix：BTCUSDT_UMCBL， spot：BTCUSDT_SPBL， spot margin：BTCUSDT）
business String yes business type（mix：mix， spot：spot， spot margin：margin）

Request Example

curl "https://api.bitget.com/api/user/v1/fee/query?symbol=BTCUSDT_UMCBL&business=mix" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

Response

{
    "code": "00000",
    "msg": "success",
    "requestTime": 1683875302853,
    "data": {
        "makerRate": "0.0002",
        "takerRate": "0.0006"
    }
}

Response Parameter

Parameter Description
makerRate maker fee
takerRate taker fee

Account

Get ApiKey Info

Rate Limit：1/sec (Uid)

HTTP Request

Request Example

curl "https://api.bitget.com/api/spot/v1/account/getInfo" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

Response

{
    "code": "00000",
    "msg": "success",
    "data": {
        "user_id": "714229403",
        "inviter_id": "682221498",
        "ips": "172.23.88.91",
        "authorities": [
            "trade",
            "readonly"
        ],
        "parentId":"566624801",
        "trader":false
    }
}

Response Parameter

Parameter Description
user_id uid
inviter_id Inviter ID
agent_inviter_code agent inviter code
channel channel
ips ip whitelist address
authorities apiKey permission
parentId Parent Uid
trader true is Trader, false is not

Get Account Assets

Rate Limit: 10 times/1s (uid)

HTTP Request 

obtain account assets

Request parameter

Parameter name Parameter type Required Description
coin String No CoinName, default query all

Request Example

curl "https://api.bitget.com/api/spot/v1/account/assets?coin=USDT" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

Response

{
  "code":"00000",
  "message":"success",
  "data":[
    {
        "coinId":"10012",
        "coinName":"usdt",
        "available":"0",
        "frozen":"0",
        "lock":"0",
        "uTime":"1622697148"
    }
]
}

Response Parameter

Parameter Description
coinId Coin ID
coinName Coin name
available Available assets
frozen Frozen: create order frozen margin
lock Locked assets, like become a fiat/p2p merchant
uTime Update timing

Get sub Account Spot Assets

Rate Limit: 1 times/10s (uid)

HTTP Request 

obtain account assets

Request parameter - N/A

Request Example

curl -X POST "https://api.bitget.com/api/spot/v1/account/sub-account-spot-assets" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d "{}"

Response

{
  "code":"00000",
  "message":"success",
  "data":[
    {
      "userId": 9165454769,
      "spotAssetsList": [
        {
          "coinId": 1,
          "coinName": "BTC",
          "available": "1.1",
          "frozen": "0",
          "lock": "1.1"
        }
      ]
    },
    {
      "userId": 1765254759,
      "spotAssetsList": [
        {
          "coinId": 2,
          "coinName": "ETH",
          "available": "12.1",
          "frozen": "0",
          "lock": "1.1"
        }
      ]
    }
]
}

Response Parameter

Parameter Description
coinId Coin ID
coinName Coin name
available Available assets
frozen Frozen assets
lock Locked assets

Get Bills

Rate Limit: 10 times/1s (uid)

HTTP Request

Obtain transaction detail flow

Request parameter

Parameter name Parameter type Required Description
coinId Integer No Coin ID
groupType String No Transaction group type groupType
bizType String No Business type bizType
after String No BillId, return the data less than this billId
before String No BillId, return the data greater than or equals to this billId
limit Integer No The number of returned results, the default is 100, the max. is 500

Request Example

curl -X POST "https://api.bitget.com/api/spot/v1/account/bills" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d '{ 
    "coinId":"2",
    "groupType":"deposit",
    "bizType":"deposit",
    "before":"987952085712531455",
    "after":"987952085712531457",
    "limit":"100"
}'

Response

{
  "code":"00000",
  "message":"success",
  "data":[{
      "cTime":"1622697148",
      "coinId":"22",
      "coinName":"usdt",
      "groupType":"deposit",
      "bizType":"transfer-in", 
      "quantity":"1",
      "balance": "1",
      "fees":"0",
      "billId":"1291"
}]
}

Response Parameter

Parameter Description
cTime Creation time
coinId Coin Id
coinName Coin name
groupType Transaction flow type
bizType Transaction bill business type
quantity Quantity
balance Assets before transfer
fees Transaction fees
billId ID

Get Transfer List

Rate Limit: 20 times/1s (uid)

HTTP Request

Request parameter

Parameter name Parameter type Required Description
coinId Integer Yes Coin ID
fromType String Yes Major type of bill accountType
after String Yes End time, seconds
before String Yes Start time, seconds
clientOid String No clientOid, match record that equals to the provided value
limit Integer No The number of returned results, the default is 100, the max. is 500

Request Example

curl "https://api.bitget.com/api/spot/v1/account/transferRecords?coinId=2&fromType=exchange&after=1659076670&before=1659076670&limit=100" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

Response

{
    "code":"00000",
    "data":[
        {
            "coinName":"btc",
            "status":"SUCCESS",
            "toType":"USD_MIX",
            "toSymbol":"",
            "fromType":"CONTRACT",
            "fromSymbol":"BTC/USD",
            "amount":"1000.00000000",
            "tradeTime":"1631070374488",
            "clientOid": "1",
            "transferId": "997381107487641600"
        }
    ],
    "msg":"success"
}

Response Parameter

Parameter Description
coinName Coin name
status Transfer status
toType Transfer in account type accountType
toSymbol Transfer to account Symbol
fromType Transfer out account type accountType
fromSymbol Transfer from account Symbol
amount Number of transfers
tradeTime Transfer time, ms
clientOid client order ID
transferId Transfer ID

Trade

Place order

Rate Limit: 10/sec (uid)

HTTP Request 

Request Example

curl -X POST "https://api.bitget.com/api/spot/v1/trade/orders" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_SPBL","side": "buy","orderType": "limit","force":"normal","price":"23222.5","quantity":"1","clientOrderId":"myorder_16569403333"}'

Response

{
    "code":"00000",
    "msg":"success",
    "data":{
        "orderId":"1001",
        "clientOrderId":"hgXjh89AsxleMSw"
    }
}

Request Body

Parameter name Parameter type Required Description
symbol String Yes Symbol Id
side String Yes Trade direction: buy or sell
orderType String Yes Order type limit/market
force String Yes force
price String No Limit pricing, null if orderType is market
quantity String Yes Order quantity, base coin when orderType is limit; quote coin when orderType is buy-market, base coin when orderType is sell-market
clientOrderId String No Custom id length: 40

Duplicate clientOrderId Response

{
    "code": "43118",
    "msg": "clientOrderId duplicate"
}

Response Parameter

Parameter Description
code "00000": success, else failure
msg "success" or failure message
data response data
> orderId Order ID
> clientOrderId Custom ID

 

 

Batch order

Rate Limit: 5/sec (uid)

HTTP Request

Request Example

curl -X POST "https://api.bitget.com/api/spot/v1/trade/batch-orders" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_SPBL","orderList":[{"side":"buy","orderType": "limit","force":"normal","price":"23222.5","quantity":"1","clientOrderId":"myorder_16569403333"}] }'

Response

{
    "code":"00000",
    "msg":"success",
    "data":{
        "orderId":"1001",
        "clientOrderId":"hgXjh89AsxleMSw"
    }
}

Request Body

Parameter name Parameter type Required Description
symbol String Yes Symbol Id
orderList List Yes order data list (max length 50)
Parameter name Parameter type Required Description
side String Yes Order side buy/sell
orderType String Yes Order type limit/market
force String Yes order time force
price String No Limit price, null if orderType is market
quantity String Yes Order quantity, base coin
clientOrderId String No Custom order ID

Response

{
    "code": "00000",
    "msg": "success",
    "requestTime": 1666336231317,
    "data": {
        "resultList": [
            {
                "orderId": "96724974842718610",
                "clientOrderId": "1"
            }
        ],
        "failure": [
            {
                "orderId": "96724974842718611",
                "clientOrderId": "1",
                "errorMsg": "clientOrderId duplicate"
            }
        ]
    }
}

Response Body

Parameter Description
resultList Success result array
> orderId Order ID
> clientOrderId client order ID
Failure Failed Array
> orderId Order ID
> clientOrderId client order ID
> errorMsg error message

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Cancel order

Rate Limit: 10 times/sec (uid)

HTTP Request

Request Body

Parameter name Parameter type Required Description
symbol String Yes Symbol Id
orderId String Yes Order ID

Request Example

curl -X POST "https://api.bitget.com/api/spot/v1/trade/cancel-order" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_SPBL","orderId": "34923828882"}'

Response

{

  "code":"00000",
   "message":"success",
  "data": "202934892814667"
}

 

 

 

 

 

 

 

Cancel order V2

Rate Limit: 10 times/sec (uid)

HTTP Request

Request Body

Parameter name Parameter type Required Description
symbol String Yes Symbol Id
orderId String No Order ID, 'clientOid' & 'orderId' must have one
clientOid String No Client Order ID, 'clientOid' & 'orderId' must have one

Request Example

curl -X POST "https://api.bitget.com/api/spot/v1/trade/cancel-order-v2" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_SPBL","orderId": "34923828882"}'

Response

{

  "code":"00000",
   "message":"success",
  "data": {
    "orderId":"34923828881",
    "clientOrderId":"xx001"
  }
}

 

 

 

 

 

Cancel order By Symbol

Rate Limit: 10 times/sec (uid)

HTTP Request

Request Body

Parameter name Parameter type Required Description
symbol String Yes Symbol Id

Request Example

curl -X POST "https://api.bitget.com/api/spot/v1/trade/cancel-symbol-order" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_SPBL"}'

Response

{

  "code":"00000",
   "message":"success",
  "data": "BTCUSDT_SPBL"
}

Final cancel result should be re-confirmed

 

 

 

 

 

Cancel order in batch (single instruments)

Rate Limit: 5 times/1s (uid)

HTTP Request

Request Body

Parameter name Parameter type Required Description
symbol String Yes Symbol Id
orderIds String[] Yes Order ID array

Request Example

curl -X POST "https://api.bitget.com/api/spot/v1/trade/cancel-batch-orders" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_SPBL","orderIds": ["34923828882"]}'

Response

{

  "code":"00000",
  "message":"success",
  "data": ["202934892814667"]
}

 

 

 

 

 

 

 

Cancel order in batch V2 (single instruments)

Rate Limit: 5 times/1s (uid)

HTTP Request

Request Body

Parameter name Parameter type Required Description
symbol String Yes Symbol Id
orderIds String[] No Order ID array, 'orderIds' or 'clientOids' must have one
clientOids String[] No clientOid array, 'orderIds' or 'clientOids' must have one

Request Example

curl -X POST "https://api.bitget.com/api/spot/v1/trade/cancel-batch-orders-v2" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_SPBL","orderIds": ["34923828882"]}'

Response

{

  "code":"00000",
  "message":"success",
  "data": {
        "resultList":[
            {
                "orderId":"34923828882",
                "clientOrderId":"xxx002"
            }
        ],
        "failure":[
            {
                "clientOrderId":"xxx001",
                "errorMsg":"duplicate clientOrderId",
                "errorCode":"40725"
            }
        ]
    }
}

 

 

 

 

 

 

 

Get order details

Rate Limit: 20 times/sec(uid)

HTTP Request

Request Body

Parameter name Parameter type Required Description
symbol String Yes Symbol Id
orderId String Yes Order ID
clientOrderId String No Custom ID

User could query cancelled/filled order details within 24 hours; Noted that after 24 hours should query via history interface

Request Example

curl -X POST "https://api.bitget.com/api/spot/v1/trade/orderInfo" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_SPBL","orderId": "34923828882"}'

Response

{
    "code": "00000",
    "msg": "success",
    "requestTime": 1684492945476,
    "data": [
        {
            "accountId": "222222222",
            "symbol": "TRXUSDT_SPBL",
            "orderId": "1041901704004947968",
            "clientOrderId": "c5e8a5e1-a07f-4202-8061-b88bd598b264",
            "price": "0",
            "quantity": "10.0000000000000000",
            "orderType": "market",
            "side": "buy",
            "status": "full_fill",
            "fillPrice": "0.0699782527055350",
            "fillQuantity": "142.9015000000000000",
            "fillTotalAmount": "9.9999972790000000",
            "enterPointSource": "API",
            "feeDetail": "{\"BGB\":{\"deduction\":true,\"feeCoinCode\":\"BGB\",\"totalDeductionFee\":-0.017118519726,\"totalFee\":-0.017118519726}}",
            "orderSource": "market",
            "cTime": "1684134644509"
        }
    ]
}

Response Parameter

Parameter Description
accountId Account ID
symbol Symbol Id
orderId Order ID
clientOrderId Custom ID
price Order price, quote coin
quantity Order quantity (base coin when orderType=limit; quote coin when orderType=market)
orderType Order type, limit/market
side Order direction, buy/sell
status Order status
fillPrice Transaction price
fillQuantity Transaction quantity
fillTotalAmount Total transaction volume
enterPointSource enterPointSource
cTime Creation time
feeDetail order fee detail
orderSource orderSource

Get order List

Rate Limit: 20 times/sec (uid)

HTTP Request

Request Body

Parameter name Parameter type Required Description
symbol String No Symbol Id. If query all, pass empty string ""

Request Example

curl -X POST "https://api.bitget.com/api/spot/v1/trade/open-orders" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_SPBL"}'

Response

{
  "code":"00000",
  "message":"success",
"data":[{
  "accountId":"10012",
  "symbol":"btcusdt_spbl",
  "orderId":"2222222",
  "clientOrderId":"xxxxxxx",
  "price":"34829.12",
  "quantity":"1",  
  "orderType":"limit",
  "side":"buy",
  "status":"new",
  "fillPrice":"0",
  "fillQuantity":"0",
  "fillTotalAmount":"0",
  "enterPointSource": "WEB",
  "cTime":"1622697148"
}]
}

Response Parameter

Parameter Description
accountId Account ID
symbol Trading pair name
orderId Order ID
clientOrderId Custom ID
price Order price
quantity Order quantity (base coin when orderType=limit; quote coin when orderType=market)
orderType Order type, limit/market
side Order direction, buy/sell
status Order status
fillPrice Transaction price
fillQuantity Transaction quantity
fillTotalAmount Total transaction volume
enterPointSource enterPointSource
cTime Creation time

Get order history

Rate Limit: 20 times/sec (uid)

HTTP Request

Request Body

Parameter name Parameter type Required Description
symbol String Yes Symbol Id
after String No orderId, return the data less than this orderId
before String No orderId, return the data greater than this orderId
limit Integer No The number of returned results, the default is 100, the max. is 500

Request Example

curl -X POST "https://api.bitget.com/api/spot/v1/trade/history" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_SPBL","after":"1659076670000","before":"1659076670000","limit":"100"}'

Response

{
  "code": "00000",
  "msg": "success",
  "requestTime": 1684493060724,
  "data": [
    {
      "accountId": "2222222222",
      "symbol": "TRXUSDT_SPBL",
      "orderId": "1041901704004947968",
      "clientOrderId": "c5e8a5e1-a07f-4202-8061-b88bd598b264",
      "price": "0",
      "quantity": "10.0000000000000000",
      "orderType": "market",
      "side": "buy",
      "status": "full_fill",
      "fillPrice": "0.0699782527055350",
      "fillQuantity": "142.9015000000000000",
      "fillTotalAmount": "9.9999972790000000",
      "enterPointSource": "API",
      "feeDetail": "{\"BGB\":{\"deduction\":true,\"feeCoinCode\":\"BGB\",\"totalDeductionFee\":-0.017118519726,\"totalFee\":-0.017118519726}}",
      "orderSource": "market",
      "cTime": "1684134644509"
    }
  ]
}

Response Parameter

Parameter Description
accountId Account ID
symbol Symbol Id
orderId Order ID
clientOrderId Custom ID
price Order price
quantity Order quantity (base coin when orderType=limit; quote coin when orderType=market)
orderType Order type, limit/market
side Order direction, buy/sell
status Order status
fillPrice Transaction price
fillQuantity Transaction quantity
fillTotalAmount Total transaction volume
enterPointSource enterPointSource
cTime Creation time
feeDetail order fee detail
orderSource orderSource

Get transaction details

Rate Limit: 20 times/sec (uid)

HTTP Request

Request Body

Parameter name Parameter type Required Description
symbol String Yes Symbol ID
orderId String No Order ID
after String No Max orderId, return data less than this 'orderId'
before String No Min orderId, return data greater or equals to this 'orderId'
limit Integer No The number of returned results, the default is 100, the max. is 500

Request Example

curl -X POST "https://api.bitget.com/api/spot/v1/trade/fills" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_SPBL","orderId":"34923828882","after":"349234552212","before":"34923775522","limit":"100"}'

Response

{
  "code":"",
  "message":"",
  "data":[{
  "accountId":"1001",
  "symbol":"btcusdt_spbl",
  "orderId":"100021",
  "fillId":"102211",
  "orderType":"limit",
  "side":"buy",
  "fillPrice":"38293.12",
  "fillQuantity":"1",
  "fillTotalAmount":"38293.12",
  "cTime":"1622697148",
  "feeCcy":"btc",
  "fees":"0.0001"
}]
}

Response Parameter

Parameter Description
accountId account ID
symbol Symbol ID
orderId order ID
fillId fill ID
orderType order type (limit/market )
side order side (buy/ sell)
fillPrice order filled price
fillQuantity order filled quantity
fillTotalAmount order filled total amount
cTime create time (milli seconds)
feeCcy fee currency
fees fees

Place plan order

Rate Limit: 20 times/sec (uid)

HTTP Request

Request Body

Parameter name Parameter type Required Description
symbol String Yes Symbol ID
side String Yes order side (buy/ sell)
triggerPrice BigDecimal Yes order trigger price
executePrice BigDecimal No order execute price
size BigDecimal Yes purchase quantity, base coin amount when orderType=limit, quote coin amount when orderType=market
triggerType String Yes order trigger type (fill_price/market_price )
orderType String Yes order type (limit/market )
clientOid String No Customized client order ID, idempotent control
timeInForceValue String No Order validity

Request Example

curl -X POST "https://api.bitget.com/api/spot/v1/plan/placePlan" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "TRXUSDT_SPBL", "side": "buy", "triggerPrice": 0.041572, "executePrice": "0.041572", "size": 151, "triggerType": "market_price", "orderType": "limit","clientOid": "12345", "timeInForceValue": "normal"}'

Response

{
  "code": "00000",
  "msg": "success",
  "requestTime": 1668134576535,
  "data": {
    "orderId": "974792555020390400",
    "clientOrderId": "974792554995224576"
  }
}

Response Parameter

Parameter Description
orderId order ID
clientOrderId Custom ID

 

 

 

 

 

 

 

 

Modify plan order

Rate Limit: 20 times/sec (uid)

HTTP Request

Request Body

Parameter name Parameter type Required Description
orderId String No Order ID, 'orderId' or 'clientOid' must have one
clientOid String No Client Order ID, 'orderId' or 'clientOid' must have one
triggerPrice BigDecimal Yes order trigger price
executePrice BigDecimal No order execute price
size String No purchase quantity
orderType String Yes order type (limit/market)

Request Example

curl -X POST "https://api.bitget.com/api/spot/v1/plan/modifyPlan" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"orderId": "974792060738441216", "triggerPrice": 0.041222, "executePrice":"0.041272", "size": 156, "orderType":"limit"}'

Response

{
  "code": "00000",
  "msg": "success",
  "requestTime": 1668136575920,
  "data": {
    "orderId": "974792060738441216",
    "clientOrderId": "974792554995224576"
  }
}

Response Parameter

Parameter Description
orderId order ID
clientOrderId Custom ID

 

 

 

 

 

 

 

 

Cancel plan order

Rate Limit: 20 times/sec (uid)

HTTP Request

Request Body

Parameter name Parameter type Required Description
orderId String No Order ID, 'orderId' or 'clientOid' must have one
clientOid String No Client Order ID, 'orderId' or 'clientOid' must have one

Request Example

curl -X POST "https://api.bitget.com/api/spot/v1/plan/cancelPlan" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"orderId": "974792060738441216"}'

Response

{
  "code": "00000",
  "msg": "success",
  "requestTime": 1668134497496,
  "data": "974792060738441216"
}

Response Parameter

Parameter Description
data orderId or clientOid, same as input param

 

 

 

 

 

 

 

 

Get current plan orders

Rate Limit: 20 times/sec (uid)

HTTP Request

Request Body

Parameter name Parameter type Required Description
symbol String Yes Symbol ID
pageSize String Yes Page Size
lastEndId String No last end ID （Pagination needs）

Request Example

curl -X POST "https://api.bitget.com/api/spot/v1/plan/currentPlan" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{ "symbol": "TRXUSDT_SPBL", "pageSize":"20" }'

Response

{
  "code": "00000",
  "msg": "success",
  "requestTime": 1668134581005,
  "data": {
    "nextFlag": false,
    "endId": 974792555020390400,
    "orderList": [
      {
        "orderId": "974792555020390400",
        "clientOid":"xxx001",
        "symbol": "TRXUSDT_SPBL",
        "size": "151",
        "executePrice": "0.041572",
        "triggerPrice": "0.041572",
        "status": "not_trigger",
        "orderType": "limit",
        "side": "buy",
        "triggerType": "fill_price",
        "enterPointSource": "API",
        "cTime": "1668134576563"
      }
    ]
  }
}

Response Parameter

Parameter Description
orderId Order ID
clientOid Client Order ID
symbol Symbol ID
size Purchase quantity, base coin amount when orderType=limit, quote coin amount when orderType=market
executePrice Order execute price
triggerPrice Order trigger price
status Order status
orderType Order type
side Buying direction
triggerType Order trigger type
enterPointSource enterPointSource
cTime Create time

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Get history plan orders

Rate Limit: 20 times/sec (uid)

HTTP Request

Request Body

Parameter name Parameter type Required Description
symbol String Yes Symbol ID
pageSize String Yes Page Size
lastEndId String No last end ID （Pagination needs）
startTime String Yes start time
endTime String Yes end time

Request Example

curl -X POST "https://api.bitget.com/api/spot/v1/plan/historyPlan" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{ "symbol": "TRXUSDT_SPBL", "pageSize":"20", "startTime":"1667889483000", "endTime":"1668134732000" }'

Response

{
  "code": "00000",
  "msg": "success",
  "requestTime": 1668134626684,
  "data": {
    "nextFlag": false,
    "endId": 974792060738441216,
    "orderList": [
      {
        "orderId": "974792060738441216",
        "clientOid":"xxx001",
        "symbol": "TRXUSDT_SPBL",
        "size": "156",
        "executePrice": "0.041272",
        "triggerPrice": "0.041222",
        "status": "cancel",
        "orderType": "limit",
        "side": "buy",
        "triggerType": "fill_price",
        "enterPointSource": "API",
        "cTime": "1668134458717"
      }
    ]
  }
}

Response Parameter

Parameter Description
orderId Order ID
clientOid Client Order ID
symbol Symbol ID
size Purchase quantity, base coin amount when orderType=limit, quote coin amount when orderType=market
executePrice Order execute price
triggerPrice Order trigger price
status Order status
orderType Order type
side Buying direction
triggerType Order trigger type
enterPointSource enterPointSource
cTime Create time

 

 

 

 

batch cancel plan orders

Rate Limit: 10 times/sec (uid)

HTTP Request

Request Body

Parameter name Parameter type Required Description
symbols List 否 symbols：["BTCUSDT_SPBL", "ETHUSDT_SPNL"], when symbols is empty, will cancel all spot plan open orders

Request Example

curl -X POST "https://api.bitget.com/api/spot/v1/plan/batchCancelPlan" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{ "symbols": ["BTCUSDT_SPBL", "ETHUSDT_SPNL"] }'

Response

{
  "code": "00000",
  "msg": "success",
  "requestTime": 1683876261117,
  "data": [
    {
      "orderId": "10401817882538259200",
      "clientOid": "10408117882913093376",
      "result": true
    },
    {
      "orderId": "10401817887238259200",
      "clientOid": "10401817882213193376",
      "result": true
    }
  ]
}

Response Parameter

Parameter Description
orderId spot plan order ID
clientOid spot plan order Client Order ID
result true is success

P2P endpoint

P2P merchant list

Limit rule 10 times/1s (uid)

HTTP Request

Request Parameter

Parameter Name Parameter Type Required Description
online String no is online (yes/no)
merchantId String no merchant ID
lastMinId String no minId
pageSize String no Page Size(default 100)

Reversal Request Example

curl "https://api.bitget.com/api/p2p/v1/merchant/merchantList?online=yes&pageSize=20" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

Reversal Response Data

{
  "code": "00000",
  "msg": "success",
  "requestTime": 1681195810516,
  "data": {
    "resultList": [
      {
        "registerTime": "1678674575000",
        "nickName": "zed-test1",
        "isOnline": "no",
        "merchantId": "3784051421",
        "averagePayment": "3",
        "averageRelease": "2",
        "totalTrades": "23",
        "totalBuy": "10",
        "totalSell": "13",
        "totalCompletionRate": "0.9",
        "thirtyTrades": "8",
        "thirtySell": "4",
        "thirtyBuy": "4",
        "thirtyCompletionRate": "0.8"
      }
    ],
    "minId": "594"
  }
}

Response Description

Parameter Description
resultList response array
> registerTime register time, ms
> nickName nick name
> isOnline is online, yes/no
> merchantId merchant ID
> averagePayment average payment time, min
> averageRealese average realese coin time, min
> totalTrades total No. of trades
> totalBuy total No. of buy
> totalSell total No. of sell
> totalCompletionRate total completion rate
> thirtyTrades thirty days total No. of trades
> thirtySell thirty days total No. of sell
> thirtyBuy thirty days total No. of buy
> thirtyCompletionRate thirty days total completion rate
minId response data minimum 'merchantId' in resultList

get merchant information

Limit rule 10 times/1s (uid)

HTTP Request

Request Parameter

Parameter Name Parameter Type Required Description

Reversal Request Example

curl "https://api.bitget.com/api/p2p/v1/merchant/merchantInfo" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

Reversal Response Data

{
  "code": "00000",
  "msg": "success",
  "requestTime": 1681194805204,
  "data": {
    "registerTime": "1672039640000",
    "nickName": "Mark",
    "realName": "M***K",
    "merchantId": "2569373299",
    "averagePayment": "2",
    "averageRealese": "3",
    "totalTrades": "2",
    "totalBuy": "1",
    "totalSell": "0",
    "totalCompletionRate": "1",
    "thirtyTrades": "12",
    "thirtySell": "4",
    "thirtyBuy": "8",
    "thirtyCompletionRate": "0.71",
    "kycFlag": true,
    "emailBindFlag": true,
    "mobileBindFlag": true,
    "email": "****@gmail.com",
    "mobile": "107****434"
  }
}

Response Description

Parameter Description
registerTime register time, ms
nickName nick name
realName kyc name
merchantId merchant ID
kycFlag is kyc: true/false
emailBindFlag is bind email: true/false
mobileBindFlag is bind mobile: true/false
email email
mobile mobile
averagePayment average payment time, min
averageRealese average realese coin time, min
totalTrades total No. of trade
totalBuy total No. of buy
totalSell total No. of sell
totalCompletionRate total completion rate
thirtyTrades thirty days total No. of trade
thirtySell thirty days total No. of sell
thirtyBuy thirty days total No. of buy
thirtyCompletionRate thirty days total completion rate

get advertisement list

Limit rule 10 times/1s (uid)

HTTP Request

Request Parameter

Parameter Name Parameter Type Required Description
advNo String no advertisement No
type String no buy/sell
status String no advertisement status
languageType String no zh-CN/en-US
coin String no coin
fiat String no fiat
orderBy String no order by desc：createTime/price (default createTime)
lastMinId String no The minId returned by the previous query, will return records with advId less than the given 'lastMinId'
startTime String yes start time, ms
endTime String no end time, ms
pageSize String no page Size(default 100)

Reversal Request Example

curl "https://api.bitget.com/api/p2p/v1/merchant/advList?startTime=1659403328000&endTime=1659410528000&pageSize=20" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

Reversal Response Data

{
  "code": "00000",
  "msg": "success",
  "requestTime": 1681198612226,
  "data": {
    "advList": [
      {
        "advId": "100",
        "advNo": "1012099637487755264",
        "type": "buy",
        "amount": "100",
        "dealAmount": "0",
        "coin": "USDT",
        "price": "1",
        "coinPrecision": "4",
        "fiatCode": "USD",
        "fiatPrecision": "2",
        "fiatSymbol": "$",
        "status": "online",
        "hide": "no",
        "maxAmount": "100",
        "minAmount": "10",
        "payDuration": "5",
        "turnoverNum": "1",
        "turnoverRate": "1.00",
        "remark": null,
        "userLimit": {
          "minCompleteNum": "10",
          "maxCompleteNum": "0",
          "placeOrderNum": "0",
          "allowMerchantPlace": "no",
          "thirtyCompleteRate": "0",
          "country": ""
        },
        "paymentMethod": [
          {
            "paymentMethod": "",
            "paymentId": "3",
            "paymentInfo": [
              {
                "name": "",
                "required": true,
                "type": "number"
              },
              {
                "name": "",
                "required": true,
                "type": "file"
              }
            ]
          }
        ],
        "ctime": "1677029278156"
      }
    ],
    "minId": "100"
  }
}

Response Description

Parameter Description
advList response array
> advId ID
> advNo advertisement No
> type sell/buy
> amount advertisement buy/sell amount
> dealAmount deal amount
> coin buy/sell coin (BGB,USDT,BTC,ETH)
> price payment fiat (USD, JPY, CNY)
> coinPrecision coin precision
> fiatCode fiat code
> fiatPrecision fiat precision
> fiatSymbol fiat symbol
> status advertisement status
> hide advertisement hide: yes/no
> maxAmount Maximum Order Quantity
> minAmount Minimum Order Quantity
> payDuration order payment duration, min
> turnoverNum merchant total trade Number
> turnoverRate merchant total trade completion
> remark remark
> ctime create time, ms
> userLimit user place order limit
>> minCompleteNum user minimum completion orders
>> maxCompleteNum user maximum completion orders
>> placeOrderNum user maximum place orders in this advertisement
>> allowMerchantPlace allow merchant place order: yes/no
>> thirtyCompleteRate thirty days completion rate
> paymentMethod payment method
>> paymentMethod payment method name
>> paymentId payment id
>> paymentInfo payment information
>>> required required: true/false
>>> name pay detail description
>>> type pay detail type, file/number, please ignore this field
minId response data minimum 'advId'

merchant get P2P order list

Limit rule 10 times/1s (uid)

HTTP Request

Request Parameter

Parameter Name Parameter Type Required Description
advNo String Yes advertisement No
type String No buy/sell
orderNo String No order No
status String No p2p order status
languageType String Yes zh-CN/en-US
coin String No coin
fiat String No fiat
lastMinId String No The minId returned by the previous query, will return records with advNo less than the given 'lastMinId'
startTime String Yes start time, ms
endTime String No end time, ms
pageSize String No page size(default 100)

Reversal Request Example

curl "https://api.bitget.com/api/p2p/v1/merchant/orderList?startTime=1659403328000&endTime=1659410528000&pageSize=20" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

Reversal Response Data

{
  "code": "00000",
  "msg": "success",
  "requestTime": 1681201761390,
  "data": {
    "orderList": [
      {
        "orderId": "557",
        "orderNo": "1029222647482966017",
        "advNo": "1027001359783845889",
        "price": "1",
        "count": "11",
        "type": "buy",
        "fiat": "USD",
        "coin": "USDT",
        "withdrawTime": "",
        "representTime": "",
        "paymentTime": "",
        "releaseCoinTime": "",
        "amount": "11",
        "buyerRealName": "Jordan",
        "sellerRealName": "Mark",
        "status": "cancelled",
        "paymentInfo": {
          "paymethodName": "paypal",
          "paymethodId": "3",
          "paymethodInfo": [
            {
              "name": "IBC",
              "required": true,
              "type": "number",
              "value": "11****"
            },
            {
              "name": "Paypal",
              "required": true,
              "type": "file",
              "value": "http://bitgetapp.com/otc/images/20230116/498ab1b8-3ba6-44bd-9570-b3e5c118233f.jpg"
            }
          ]
        },
        "ctime": "1681111722251"
      }
    ],
    "minId": "557"
  }
}

Response Description

Parameter Description
orderList response array
> orderId ID
> orderNo order No
> advNo advertisement No
> type buy/sell
> count order coin amount
> coin coin
> price price
> fiat fiat
> withdrawTime withdraw time
> representTime order appeal time
> releaseCoinTime release coin time
> paymentTime payment time
> amount order fiat amount
> status p2p order status
> buyerRealName buyer kyc name
> sellerRealName seller kyc name
> ctime create time
> paymentInfo payment information
>> paymethodName pay method name
>> paymethodId pay method ID
>> paymethodInfo pay method information
>>> name name
>>> required required: true/false
>>> type type, number/file, please ignore this field
>>> value value
minId response data minimum 'orderId'

Sub-Account Endpoints

Create Virtual Sub Account

Limit Rule：5c/1s (uid)

HTTP Request

Request Pam

Parameter Name Type Required Description
subName List Yes Virtual nickname English letters with a length of 8 characters

Request Example

curl -X POST "https://api.bitget.com/api/user/v1/sub/virtual-create" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"subName": ["bitgeton"]}'

Response

{
    "code": "00000",
    "msg": "success",
    "requestTime": 1682660169412,
    "data": {
        "failAccounts": [
            "guningfh@virtual-bitget.com"
        ],
        "successAccounts": [
            {
                "subUid": "9837924274",
                "subName": "guningfk@virtual-bitget.com",
                "status": "normal",
                "auth": [
                    "contract_trade",
                    "spot_trade"
                ],
                "remark": null,
                "cTime": "1682660169573"
            }
        ]
    }
}

Response

Parameter Description
subUid virtual sub uid
subName Virtual Email
status virtual account status
auth Virtual auth
remark account label
cTime Create time timestamp

Modify Virtual Account

Limit Rule：5c/1s (uid)

HTTP Request

Request (Request Body)

Parameter Type Required Description
subUid String Yes virtual sub uid
perm String Yes Perm ,
status String Yes Virtual account status

Request Example

curl -X POST "https://api.bitget.com/api/user/v1/sub/virtual-modify" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"subUid": "9837924274","perm":"spot_trade,contract_trade", "status":"normal"}'

Response 

{
    "code": "00000",
    "msg": "success",
    "requestTime": 1682660666458,
    "data": "success"
}

Batch Create Virtual Account And ApiKey

This interface can create a virtual sub-account and a sub-account apikey together. The created virtual sub-account has contract and spot permissions by default.

Limit Rule：1c/1s (uid)

HTTP Request

Request (Request Body)

Parameter Type Required Description
List List
-- subName String Yes Virtual nickname (letters with a length of 8 characters)
-- passphrase String Yes Password (Password length is 8~32 letters + numbers) case sensitive
-- label String Yes label limit 20
-- ip String No Virtual sub-account ApiKey ip whitelist
-- perm String No Sub-account apiKey permissions

Request Example

curl -X POST "https://api.bitget.com/api/user/v1/sub/virtual-api-batch-create" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"list":[{"subName":"armendon","passphrase":"1r1b6uX6PQ9tbKwa","perm":"spot_trade,contract_trade,readonly,spot_trade","remark":"1681808312065"}]}'

Response

{
    "code": "00000",
    "msg": "success",
    "requestTime": 1682662465346,
    "data": {
        "list": [
            {
                "subUid": "4236327146",
                "subName": "armendon@virtual-bitget.com",
                "label": "1681808312065",
                "apiKey": "bg_d32ff9d9**********c3d2bc5e23",
                "secretKey": "af22848395e3d97e08dbd9a876a1XXXXXXXXXXXXXXX",
                "perm": "readonly,spot_trade,contract_trade",
                "ip": ""
            }
        ]
    }
}

Get Virtual Account List

Limit Rule：10c/1s (uid)

HTTP Request

Request (Request Param)

Parameter Type Required Description
pageSize String No Default20 Max100
pageNo String No PageNo Default 1
status String No virtual status

Request Example

curl "https://api.bitget.com/api/user/v1/sub/virtual-list" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \

Response 

{
    "code": "00000",
    "msg": "success",
    "requestTime": 1656589586807,
    "data": {
        "hasNextPage": false,
        "lastEndId": 51,
        "list": [
            {
                "subUid": "7713789662",
                "subName": "mySub01@bgbroker6314497154",
                "status": "normal",
                "auth": [
                    "readonly",
                    "spot_trade",
                    "contract_trade"
                ],
                "remark": "mySub01",
                "cTime": "1653287983475"
            }
        ]
    }
}

Create Virtual Account ApiKey

Limit Rule：5c/1s (uid)

HTTP Request

Request (Request Body)

Paarameter Type Required Description
subUid String Yes virtual sub uid
passphrase String Yes Password (Password length is 8~32 letters + numbers) case sensitive
label String Yes label
ip String No ip，Max 30
perm String No perm，default readonly

Request Example

curl -X POST "https://api.bitget.com/api/user/v1/sub/virtual-api-create" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"subUid":"983792","passphrase":"1r1b6usadasdasd","remark":"1682396356594","perm":"spot_trade,spot_trade,spot_trade,spot_trade,spot_trade,spot_trade"}'

Response 

{
  "code": "00000",
  "msg": "success",
  "data": [
    {
      "subUid": "58281113",
      "label": "sub api",
      "apiKey": "bg_djwwwls98a1s0dLK3deq2",
      "secretKey": "Sjwwwls98a1s0dLK3deq2",
      "perm": "spot_trade,contract_trade",
      "ip": "127.127.127.127"
    }
  ]
}

Response

Paarameter Description
subUid Sub uid
label sub apikey label
apikey apikey
secretKey sub apikey secretKey
perm Perm
ip subApiKey ip whileList

Modify Virtual Account ApiKey

Limit Rule：5c/1s (uid)

HTTP Request

Request (Request Body)

Parameter Type Required Description
subUid String Yes sub account uid
subApiKey String Yes sub account apikey
passphrase String Yes subApiKey passphrase
label String Yes Sub Apikey label
ip String No Will overwrite the previous ip information(If no ip is passed, the whitelist is set to empty) Max 30
perm String No perm

Request Example

curl -X POST "https://api.bitget.com/api/user/v1/sub/virtual-api-modify" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"subUid":"983792","subApiKey":"bg_ab5735b8a90f2d4","passphrase":"1r1b6usadasdasd","remark":"1682396356594","perm":"spot_trade,spot_trade,spot_trade,spot_trade,spot_trade,spot_trade"}'

Response

{
    "code": "00000",
    "msg": "success",
    "requestTime": 1682661350849,
    "data": {
        "subUid": "9837924274",
        "label": "1682396356594",
        "apiKey": "bg_19aab20aafdb177408faf3fba6580656",
        "perm": "spot_trade",
        "ip": ""
    }
}

Response

Parameter Desciption
subUid Sub uid
label apikey lable
apikey sub apikey
perm perm
ip sub apikey ip whitelist

Get Virtual Sub ApiKey List

Limit Rule：10c/1s (uid)

HTTP Request

Request

Parameter Type Required Description
subUid String Yes Sub uid

Request Example

curl "https://api.bitget.com/api/user/v1/sub/virtual-api-list?subUid=1111111" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \

Response

{
    "code": "00000",
    "msg": "success",
    "requestTime": 1682661432874,
    "data": [
        {
            "subUid": "9837924274",
            "label": "1682396356594",
            "apiKey": "bg_ab5735b8a90f2d4c02771b36e8dbebf4",
            "perm": "spot_trade",
            "ip": ""
        }
    ]
}

Response

Parameter Desciption
subUid Sub virtual Uid
label Apikey label
apikey sub apikey
perm Perm
ip sub ApiKey ip whilelist

 

 

 

 

 

 

 

 

 

WebSocketAPI

Overview

WebSocket is a new HTML5 protocol that achieves full-duplex data transmission between the client and server, allowing data to be transferred effectively in both directions. A connection between the client and server can be established with just one handshake. The server will then be able to push data to the client according to preset rules. Its advantages include:

It is strongly recommended that developers use WebSocket API to obtain market information and transaction depth. ​

domain WebSocket API Recommended to use
domain 1 wss://ws.bitget.com/spot/v1/stream internationality

Connect

Connection instructions:

Connection limit: 100 connections per IP

When subscribing to a public channel, no login is required.

When subscribing to a private channel, MUST login before subscribe to any channel(s)

Subscription limit: 240 times per hour

If there’s a network problem, the system will automatically close the connection.

The connection will be closed automatically if the subscription is not established or, no data pushed from server for more than 30 seconds.

Client should keep ping the server in every 30 seconds. Server will close the connections which has no ping over 120 seconds(even when the client is still receiving data from the server)

To keep the connection stable:

  1. Set a timer of 30 seconds.
  2. If the timer is triggered, send the String 'ping'.
  3. Expect a 'pong' as a response. If the response message is not received within 30 seconds, please raise an error and/or reconnect.
  4. The Websocket server accepts up to 10 messages per second. The message includes:
    • PING frame
    • Messages in JSON format, such as subscribe, unsubscribe.
  5. If the user sends more messages than the limitation, the connection will be disconnected. IPs that are repeatedly disconnected may be blocked by the server;
  6. A single connection can subscribe up to 1000 Streams;
  7. A single IP can create up to 100 connections.

Login

api_key: Unique identification for invoking API. Requires user to apply one manually.

passphrase: APIKey password

timestamp: the Unix Epoch time, the unit is seconds

sign: signature string

method: always 'GET'

requestPath: always '/user/verify'

secretKey: The security key generated when the user applies for APIKey, e.g. : 22582BD0CFF14C41EDBF1AB98506286D

the signature algorithm is as follows:

Concatenate "timestamp", "method", "requestPath", and "body" as string
Encrypt the string using Hmac_SHA256 with secretKey
Base64 encode the Hmac_SHA256 output

Sign example sign=CryptoJS.enc.Base64.Stringify( CryptoJS.HmacSHA256(timestamp +'GET'+'/user/verify', secretKey) )

The request will expire 30 seconds after the timestamp. If your server time differs from the API server time, we recommended using the REST API to query the server time(noted it return milliseconds, while in websocket login you should use seconds) and then set the timestamp.

For the description of the signature method, refer to the verification section in the API overview

Steps to generate the final signature:

Step 1. Use the private key secretkey to encrypt the string to be signed with hmac sha256

Signature = hmac_sha256(secretkey, Message)

The second step is to base64 encode the Signature

Signature = base64.encode(Signature)

If login fails, it will automatically disconnect

Request format description

{
    "op": "login",
    "args": [{
        "apiKey": "<api_key>",
        "passphrase": "<passphrase>",
        "timestamp": "<timestamp>",
        "sign": "<sign>"
    }]
}

Request Example

{
    "op": "login",
    "args": [{
        "apiKey": "bg_573af5eca856acd91c230da294ce2105",
        "passphrase": "123456",
        "timestamp": "1538054050",
        "sign": "8RCOqCJAhhEh4PWcZB/96QojLDqMAg4qNynIixFzS3E="
    }]
} 

Successful Response Example

{
    "event": "login",
    "code": "0",
    "msg": ""
} 

Failure Response Example

{
    "event": "error",
    "code": "30005",
    "msg": "error"
}

Subscribe

Subscription Instructions

Request format description

{
  "op": "subscribe",
  "args": ["<SubscriptionTopic>"]
}

WebSocket channels are divided into two categories: public and private channels.

Public channels -- includes

Tickers channel

Candlesticks channel

Depth channel

Trades Channel

etc -- do not require log in.

Private channels -- including

Account Channel

Order Channel

etc -- require login.

User can choose to subscribe to one or more channels, and the total length of multiple channels cannot exceed 4096 bytes.

Request Example

{
    "op": "subscribe",
    "args": [{
        "instType": "SP",
        "channel": "ticker",
        "instId": "BTCUSDT"
    }, {
        "instType": "SP",
        "channel": "candle5m",
        "instId": "BTCUSDT"
    }]
}

Request parameters

Parameter Type Required Description
op String Yes Operation, subscribe
args Array Yes List of subscribe channels
> instType String No Instrument typeSP: Spot public channel SPBL Spot private channel
> channel String Yes Channel name, please refer to each examples below
> instId String No refer to Get Symbols in response field: symbolName; at some cases 'default'

Example response

{
    "event": "subscribe",
    "args": {
        "instType": "SP",
        "channel": "ticker",
        "instId": "BTCUSDT"
    }
}

Return parameters

Parameter Type Required Description
event String Yes Event, subscribe error
arg Object No Subscribed channel
> instType String No Instrument typeSP: Spot public channel SPBL Spot private channel
> channel String Yes Channel name, same as request
> instId String No Instrument ID
code String No Error code
msg String No Error message

Unsubscribe

Unsubscribe from one or more channels.

Request format description

{
  "op": "unsubscribe",
  "args": ["< SubscriptionTopic> "]
}

Request Example

{
    "op": "unsubscribe",
    "args": [{
        "instType": "SP",
        "channel": "ticker",
        "instId": "BTCUSDT"
    }, {
        "instType": "SP",
        "channel": "candle1m",
        "instId": "BTCUSDT"
    }]
}

Request parameters

Parameter Type Required Description
op String Yes Operation, unsubscribe
args Array Yes List of channels to unsubscribe from
> instType String Yes Instrument typeSP: Spot public channel SPBL Spot private channel
> channel String Yes Channel name, please refer to each examples below
> instId String Yes refer to Get Symbols in response field: symbolName; at some cases 'default'

Example response

{
    "event": "unsubscribe",
    "args": {
        "instType": "SP",
        "channel": "ticker",
        "instId": "BTCUSDT"
    }
} 

Return parameters

Parameter Type Required Description
event String Yes Event, unsubscribe error
arg Object Yes Unsubscribed channel
>instType String No Instrument typeSP: Spot public channel SPBL Spot private channel
> channel String Yes Channel name
> instId String Yes Instrument ID
code String No Error Code
msg String No Error Message

Checksum

This mechanism will assist users to checking the accuracy of depth data.

Merging incremental data into full data

After subscribing to the incremental push channel (such as books 400 levels) of Order Book Channel, users first receive the initial snapshot of the market depth. Afterwards the incremental data is subsequently received, you are responsible to update the snapshot locally.

  1. If there is a same price, compare the amount. If the amount is 0, delete this depth data. If the amount changes, replace the original data.
  2. If there is no same price, sort by price (bids in descending order, asks in ascending order), and insert the depth information into the local snapshot.

Calculate Checksum

Use the first 25 bids and asks in the local snapshot to build a string (where a colon connects the price and amount in an ask or a bid), and then calculate the CRC32 value (32-bit signed integer).

Calculate Checksum

1. More than 25 levels of bid and ask
A local snapshot of market depth (only 2 levels of the orderbook are shown here, while 25 levels of orderbook should actually be intercepted):
    "bids": [
      [ 43231.1, 4 ],   //bid1
      [ 43231,   6 ]    //bid2
    ]
    "asks": [
      [ 43232.8, 9 ],   //ask1
      [ 43232.9, 8 ]    //ask2
    ]
Build the string to check CRC32:
"43231.1:4:43232.8:9:43231:6:43232.9:8"
The sequence:
"bid1[price:amount]:ask1[price:amount]:bid2[price:amount]:ask2[price:amount]"

2. Less than 25 levels of bid or ask
A local snapshot of market depth:
    "bids": [
      [ 3366.1, 7 ]
    ]
    "asks": [
      [ 3366.8, 9 ],
      [ 3368  , 8 ],
      [ 3372  , 8 ]
    ]

Build the string to check CRC32:
"3366.1:7:3366.8:9:3368:8:3372:8"
The sequence:
"bid1[price:amount]:ask1[price:amount]:ask2[price:amount]:ask3[price:amount]"
  1. When the bid and ask depth data exceeds 25 levels, each of them will intercept 25 levels of data, and the string to be checked is queued in a way that the bid and ask depth data are alternately arranged. Such as: bid1[price:amount]:ask1[price:amount]:bid2[price:amount]:ask2[price:amount]...
  2. When the bid or ask depth data is less than 25 levels, the missing depth data will be ignored. Such as: bid1[price:amount]:ask1[price:amount]:ask2[price:amount]:ask3[price:amount]...
  3. If price is '0.5000', DO NOT calculate the checksum by '0.5', please DO use the original value

Public Channels

Tickers Channel

Retrieve the last traded price, bid price, ask price and 24-hour trading volume of the instruments. Data will be pushed every 200 ms.

Request Example

{
    "op": "subscribe",
    "args": [{
        "instType": "SP",
        "channel": "ticker",
        "instId": "BTCUSDT"
    }]
}

Request parameters

Parameter Type Required Description
op String Yes Operation, subscribe unsubscribe
args Array Yes List of subscribed channels
> instType String Yes Instrument typeSP: Spot public channel; MC: Contract/future channel
> channel String Yes Channel name, ticker
> instId String Yes Instrument ID, refer to Get Symbols in response field: symbolName, a sample value could be like BTCUSDT

Successful Response Example

{
    "op": "subscribe",
    "args": [{
        "instType": "SP",
        "channel": "ticker",
        "instId": "BTCUSDT"
    }]
}

Failure Response Example

{
    "event": "error",
    "code": "30001",
    "msg": "Unrecognized request: {\"op\": \"subscribe\", \"arg\":[\"instType\":\"sp\",\"channel\" : \"ticker\", \"instId\" : \"BTCUSDT\"}]}"
} 

Response parameters

Parameter Type Required Description
event String Yes Event, subscribe unsubscribe error
arg Object No Subscribed channel
> instType String Yes Instrument Type
> channel String Yes Channel name
> instId String Yes Instrument name
code String No Error Code
msg String No Error Message

Push data parameters

Parameter Type Description
arg Object Successfully subscribed channel
> instType String Instrument Type
> channel String Channel name
> instId String Instrument ID
action String Push data action, incremental or full data. update: incremental; snapshot: full, channel 'ticker' would only return 'snapshot'
data Array Subscribed data array
>instId String Instrument ID, BTCUSDT
>last String Latest traded price from the moment this data generated
>bestAsk String Best ask price or: ask1 price
>bestBid String Best bid price or: bid1 price
>open24h String Open price in the past 24 hours
>high24h String Highest price in the past 24 hours
>low24h String Lowest price in the past 24 hours
>baseVolume String 24h trading volume, with a unit of currency. BTC is base currency in BTCUSDT
>quoteVolume String 24h trading volume, with a unit of contract.USDT is quote contract in BTCUSDT
>ts String Ticker data generation time, Unix timestamp format in milliseconds
>labeId Long Label ID
>openUtc String Open price in UTC time
>chgUTC String Change rate since openUtc, that is: (last - openUtc) / openUtc, scale e-5
>bidSz String Best bid size
>askSz String Best ask size

Response Example

{
    "action": "snapshot",
    "arg": {
        "instType": "sp",
        "channel": "ticker",
        "instId": "BTCUSDT"
    },
    "data": [
        {
            "instId": "BTCUSDT",
            "last": "20193.17",
            "open24h": "19112.64",
            "high24h": "20374.29",
            "low24h": "18973.16",
            "bestBid": "20192.420000",
            "bestAsk": "20196.440000",
            "baseVolume": "13177.3815",
            "quoteVolume": "261300702.3745",
            "ts": 1664292040025,
            "labeId": 0,
            "openUtc": "19226.5300000000000000",
            "chgUTC": "0.05028",
            "bidSz": "0.06",
            "askSz": "0.0119"
        }
    ]
}

Candlesticks Channel

Retrieve the candlesticks data of an instrument. Data will be pushed every 500 ms.

Request Example

{
    "op": "subscribe",
    "args": [{
        "instType": "sp",
        "channel": "candle1m",
        "instId": "BTCUSDT"
    }]
}

Request parameters

Parameter Type Required Description
op String Yes Operation, subscribe unsubscribe
args Array Yes List of subscription channels
> instType String Yes Instrument Type SP: spot; MC: contract/future
> channel String Yes Channel Name，candle1W, candle1D, candle12H, candle4H, candle1H, candle30, candle15m, candle5m, candle1m
> instId String Yes Instrument ID for example :BTCUSDT

Successful Response Example

{
    "event": "subscribe",
    "arg": {
        "instType": "sp",
        "channel": "candle1D",
        "instId": "BTCUSDT"
    }
}

Failure Response Example

{
    "event": "error",
    "code": 30003,
    "msg": "instType:sp,channel:candle1D,instId:BTC-USDT Symbol not exists" 
} 

Response parameters

Parameter Type Required Description
event String Yes Event, subscribe unsubscribe error
arg Object No Subscribed channel
> instType String Yes Instrument Type
> channel String Yes channel name
> instId String Yes Instrument name
code String No Error Code
msg String No Error Message

Push Data Example - snapshot

{
    "action": "snapshot",
    "arg": {
        "instType": "sp",
        "channel": "candle1D",
        "instId": "BTCUSDT"
    },
    "data": [
        ["1597026383085", "8533.02", "8553.74", "8527.17", "8548.26", "45247"]
    ]
} 

Push data parameters

Parameter Type Description
arg Object Successfully subscribed channel
> instType String Instrument Type
> channel String Channel name
> instId String Instrument ID
data Array Subscription data array, format in String Array
> ts String Data generation time, Unix timestamp format in milliseconds
> o String Open price
> h String highest price
> l String Lowest price
> c String Close price
>v String Trading volume, with a unit of contact

Depth channel

Subscribe depth(order book) data

books: Push the full snapshot data for the first time, push incrementally later, that is, if there is a change in depth, the depth data that has changed will be pushed

books5: Push 5 levels of snapshot data every time

book15 15 levels of snapshot data every time

Channel Length of bids Length of asks Remark
books maximum 200 maximum 200 Snapshot and update might return less than 200 bids/asks as per symbol's orderbook various from each other; The number of bids/asks is not a fixed value and may vary in the future
books5 5 5 Top 5 order book of "books" that begins from bid1/ask1
books15 15 15 Top 15 order book of "books" that begins from bid1/ask1

For example, if the whole order book consist of 20 bids and 12 asks

channel books return 20 bids and 12 asks

channel books5 return 5 bids and 5 asks, bids return from index 15 to 19(index 19 is bid1), asks return from index 0 to index 4

channel books15 return 15 bids index from 5 to 19(index 19 is bid1), and return 12 asks index from 0 to 11

Noted that bids are in descending order, while asks are in ascending order

Request Example

{
    "op": "subscribe",
    "args": [{
        "instType": "sp",
        "channel": "books5",
        "instId": "BTCUSDT"
    }]
}

Request parameters

Parameter Type Required Description
op String Yes Operation, subscribe unsubscribe
args Array Yes List of subscribed channels
> instType String Yes Instrument Type SP
> channel String Yes Channel name, books books5 or books15
> instId String Yes Instrument ID

Example Response

{
    "event": "subscribe",
    "arg": {
        "instType": "sp",
        "channel": "books5",
        "instId": "BTCUSDT"
    }
}

Failure example

{
    "event": "error",
    "code": 30003,
    "msg": "instType:sp,channel:books5,instId:BTC-USDT Symbol not exists" 
} 

Response parameters

Parameter Type Required Description
event String Yes Event，subscribe unsubscribe error
arg Object No Subscribed channel
> instType String Yes Instrument Type
> channel String Yes Channel name
> instId String Yes Instrument ID
msg String No Error Message
code String No Error Code

Push data parameters

Parameter Type Description
arg Object Successfully subscribed channel
> instType String Instrument Type
> channel String Channel name
> instId String Instrument ID
action String Push data action, incremental push data or full push data snapshot: full update: incremental
data Array Subscribed data
> asks Array Order book on sell side, ascending order
> bids Array Order book on buy side, descending order
> ts String Order book generation time, Unix timestamp format in milliseconds
> checksum Integer Checksum, calculate and compare the checksum, re-subscribe if mis-match

An example of the array of asks and bids values: ["411.8", "10"] "411.8" is the depth price, "10" is the size

Trades Channel

Retrieve the recent trading data. Data will be pushed whenever there is a trade.

Request Example

{
    "op": "subscribe",
    "args": [{
        "instType": "sp",
        "channel": "trade",
        "instId": "BTCUSDT"
    }]
}

Request parameters

Parameter Type Required Description
op String Yes Operation, subscribe unsubscribe
args Array Yes List of subscribed channels
> instType String Yes Instrument Type, sp : spot
> channel String Yes Channel Name，trade
> instId String Yes Instrument ID, i.e. BTCUSDT

Successful Response Example

{
    "event": "subscribe",
    "arg": [{
        "instType": "sp",
        "channel": "trade",
        "instId": "BTCUSDT"
    }]
}

Failure Response Example

{
    "event": "error",
    "code": 30003,
    "msg": "instType:spbl,channel:trade,instId:BTC-USDT Symbol not exists" 
} 

Response parameters

Parameter Type Required Description
event String Yes Event，subscribe unsubscribe error
arg Object No Subscribed channel
> instType String Yes InstrumentType
> channel String Yes Channel Name
> instId String Yes Instrument ID
code String No Error Code
msg String No Error Message

Push data parameters

Parameter Type Description
arg Object Successfully subscribed channel
> instType String Instrument Type
> channel String Channel Name
> instId String Instrument ID
data Array Subscribed data
> ts String Filled time, Unix timestamp format in milliseconds
> px String Trade price
> sz String Trade size
> side String Trade direction, buy, sell

Private Channel

Account Channel

Subscribe account information. Data will be pushed when triggered by events such as placing/canceling order, and will also be pushed when transfer in/out or withdraw/deposit.

Request Example

{
    "op": "subscribe",
    "args": [{
        "instType": "spbl",
        "channel": "account",
        "instId": "default"
    }]
}

Request parameters

Parameter Type Required Description
op String Yes Operation, subscribe unsubscribe
args Array Yes List of subscribed channels
> instType String Yes Instrument Type,spbl
> channel String Yes Channel Name，account
> instId String Yes Currency, always 'default'

Successful Response Example 

{
    "event": "subscribe",
    "arg": {
        "instType": "spbl",
        "channel": "account",
        "instId": "default"
    }
} 

Failure Response Example

{
    "event": "error",
    "code": 30003,
    "msg": "instType:spbl,channel:account,instId:BTC-USDT Symbol not exists" 
}  

Response parameters

Parameter Type Required Description
event String Yes Operation, subscribe unsubscribe error
arg Object No Subscribed channel
> instType String Yes Instrument Type
> channel String Yes Channel Name
> instId String No Currency
code String No Error Code
msg String No Error Message

Push Data Example

{
    "action": "snapshot",
    "arg": {
        "instType": "spbl",
        "channel": "account",
        "instId": "default"
    },
    "data": [{
        "coinId": "2",
        "coinName": "USDT",
        "available": "1000.0000"
    }, {
        "coinId": "1",
        "coinName": "BTC",
        "available": "1.35000"
    }]
}

Push data parameters

Parameter Type Description
action String snapshot: snapshot of current account, update: incremental changes
arg Object Successfully subscribed channel
> instType String Instrument Type
> channel String Channel Name
> instId String Currency
data Array Subscribed data
> coinId String Coin Id
> coinName String Coin Name, BTC, USDT
> available String balance

First push: full push.

Incremental push: push transaction changes

Order Channel

Retrieve order information. Data will not be pushed when first subscribed. Data will only be pushed when triggered by events such as placing/canceling order.

Request Example

{
    "op": "subscribe",
    "args": [{
        "channel": "orders",
        "instType": "spbl",
        "instId": "BTCUSDT_SPBL"
    }]
}

Request parameters

Parameter Type Required Description
op String Yes Operation，subscribe unsubscribe
args Array Yes List of subscribed channels
> instType String Yes Instrument Type,spbl
> channel String Yes Channel Name, orders
> instId String Yes Instrument Id, BTCUSDT_SPBL

Successful Response Example

{
    "event": "subscribe",
    "arg": {
        "channel": "orders",
        "instType": "spbl",
        "instId": "BTCUSDT_SPBL"
    }
}

Failure Response Example

{
    "event": "error",
    "code": 30003,
    "msg": "instType:spbl,channel:orders,instId:BTC-USDT Symbol not exists"
}

Response parameters

Parameters Type Required Description
event String Yes Event，subscribe unsubscribe errror
arg Object No Subscribed Data
> channel String Yes Channel Name
> instType String Yes Instrument Type`spbl：private spot
> instId String No Instrument Id
code String No Error Code
msg String No Error Message

Push data Example

{
  "data":[
    {
      "notional":"6.290480",
      "side":"buy",
      "sz":"0.0040",
      "px":"1572.62",
      "orderFee":[

      ],
      "eps":"WEB",
      "cTime":1678789919603,
      "ordId":"10194123402951243161",
      "instId":"ETHUSDT_SPBL",
      "clOrdId":"b712d4e8-bec1-4124-ae83-e7aa44cfcdd2",
      "accFillSz":"0.0000",
      "avgPx":"0.00",
      "force":"normal",
      "uTime":1678789919603,
      "ordType":"limit",
      "status":"new"
    }
  ],
  "arg":{
    "instType":"spbl",
    "instId":"default",
    "channel":"orders"
  },
  "action":"snapshot"
}

Push data parameters

Parameter Type Description
action String 'snapshot'
arg String Subscribe arg
> channel String Channel Name
> instType String Instrument Type
> instId String Instrument Id
data Array Subscribed Data
> instId String Instrument Id
> ordId String Order Id
> clOrdId String Client customized order ID
> px String Order price
> sz String The original order quantity
> notional String The purchase amount, which will be returned when the market price is purchased
> ordType String Order Type market limit
> force String Categorynormaltwapadlfull_liquidationpartial_liquidation
> side String order side，buy sell
> fillPx String fill price
> tradeId String
> fillSz String fill size
> fillTime String fill time
> fillFee String last filled fee, negative
> fillFeeCcy String last filled fee currency
> execType String Order flow type, T: taker M: maker
> accFillSz String Accumulated fill quantity
> avgPx String Average filled price. If none is filled, it will return 0.
> status String order state init,new, partial-fill, full-fill, cancelled
> eps String enterPointSource
> cTime String Created time, Unix timestamp format in milliseconds
> uTime String Updated time, Unix timestamp format in milliseconds
> orderFee Array fee list
>> feeCcy String Fee currency
>> fee String Negative fee: the user transaction fee charged by the platform. Positive fee means rebate.

RestAPI  error code

Public error code

Error message Error code http status code
The request header "ACCESS_KEY" cannot be empty 40001 400
The request header "ACCESS_SIGN" cannot be empty 40002 400
The request header "ACCESS_TIMESTAMP" cannot be empty 40003 400
Invalid ACCESS_TIMESTAMP 40005 400
Invalid ACCESS_KEY 40006 400
Invalid Content_Type，please use“application/json”format 40007 400
Requested timestamp expired 40008 400
api verification failed 40009 400
Request is too frequent 429 429
The request header "ACCESS_PASSPHRASE" cannot be empty 40011 400
apikey/passphrase is incorrect 40012 400
User has been frozen 40013 400
Incorrect permissions 40014 400
System error 40015 400
The user must bind a mobile phone or Google authenticator 40016 400
Parameter verification failed 40017 400
Illegal IP request 40018 400
Batch processing orders can only process up to 50 40912 400
OrderId or clientId must be passed one 40913 400
The contract configuration does not exist, please check the parameters 40102 400
Server upgrade, please try again later 40200 400
client_oid length is not greater than 40, and cannot be Martian characters 40305 400
wrong format 40409 400
Only check the data of the last three months 40704 400
Start time is greater than end time 40707 400
Parameter is empty 40724 400
spot service return an error 40725 400
The order does not exist 43001 400
Pending order failed 43002 400
There is no order to cancel 43004 400
Exceeded the maximum order limit of transaction volume 43005 400
The order quantity is less than the minimum transaction quantity 43006 400
The order quantity is greater than the maximum transaction quantity 43007 400
The current order price cannot be less than {0} 43008 400
The current commission price exceeds the limit {0} 43009 400
The transaction amount cannot be less than {0} 43010 400
The current order price cannot be less than {0} 43011 400
clientOrderId duplicate 43118 400
The purchase limit of this currency is {0}, and there is still {1} left 43122 400

WebSocket error code

Error Message Error Code
Channel does not exist 30001
Illegal request 30002
Invalid op 30003
User needs to log in 30004
Login failed 30005
request too many 30006
request over limit,connection close 30007
Invalid ACCESS_KEY 30011
Invalid ACCESS_PASSPHRASE 30012
Invalid ACCESS_TIMESTAMP 30013
Request timestamp expired 30014
Invalid signature 30015
console