Welcome
Welcome to Bitget ApiDoc! Click here for quick start
Update Log
28/12/2022
- Provide brand new telegram group for Openapi technical support
16/12/2022
- added new enums on 'bizType'
06/12/2022
- RestAPI -> Account -> added Get sub Account Spot Assets
- RestAPI -> Public -> added Get Coin List rateLimit updated to 3/s(IP)
- RestAPI -> Public -> added Get Single Ticker add response parameter: 'bidSz', 'askSz'
- WebsocketAPI -> Private Channel -> Order Channel -> Push data parameters -> 'status' supplement enum: 'init'
- WebsocketAPI -> Public Channel -> Ticker Channel -> Push data parameters -> added 'bidSz', 'askSz'
15/11/2022
- RestAPI -> Trade -> added
18/10/2022
Wallet
-> add Sub Transfer
19/09/2022
Account
->Get ApiKey Info
add Responsetrader
13/09/2022
Account
->Get ApiKey Info
add ResponseparentId
19/08/2022
Market
->Get Candles Data
add request parameter UTC0Market
->Get All Tickers
,Get Single Ticker
add responseopenUtc0
15/08/2022
- GET request It is forbidden to transmit parameters in the
Request Body
, please pass the parameters inQueryString
08/08/2022
add
Signature Demo Code
Example06/08/2022
add PostMan Example
03/08/2022
- add Request Example
21/07/2022
- Websocket connection addition rules, please refer to the Connection directory
24/06/2022
Added getInfo interface
assets
addcoin
parameter
05/05/2022
- Added wallet interface
12/02/2022 【Ticker】
- ticker add
buyOne
,sellOne
07/1/2022
- Removed domain name https://capi.bitgetapi.com
Add main domain name https://api.bitget.com
Add error code
Frequency limiting rules
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 】
- WebSocket Public Channel and Private Channel Online
15/09/2021 【Add transfer record interface】
- Added transfer record interface
05/07/2021【New creation v1 Spot trading document】
- New creation of V1 document
- Supporting of error message
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:
- Email API@bitget.com
- Telegram Join
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:
- Read-Only permission: Read permission authorized to query data, such as market data.
- Trade permission: Transaction permission authorized to call the interface of placing and cancelling orders.
- Transfer permission: With this permission it authorized to transfer coins between accounts inside Bitget.
- Withdraw permission: Authorized to withdraw assets from bitget account,
noted that you can only withdraw coins through an IP address bound to the platform
After successfully created the API Key, please remember the following information:
APIKey
The identity of API transactions, it is generated by a random algorithm.Secretkey
The private key is randomly generated by the system and used for Signature generation.Passphrase
Passphrase is set by the user. It should be noted that if the Passphrase is forgotten, it cannot be retrieved, and the API Key needs to be recreated.
SDK / Code example
SDK(Recommended)
Java | Python | Node Js | Golang | PHP
PostMan Demo
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
- Private interface
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 when the access exceeds the frequency limit, it will return the 429 status: the request is too frequent.
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 |
OTC_SGD | Otc account |
CONTRACT | contract account |
USD_MIX | Mix account |
USDT_MIX | USDT Future account |
Candlestick line timeframe
granularity
- 1min (1 minute)
- 5min (5 minutes)
- 15min (15 minutes)
- 30min (30 minutes)
- 1h (1 hour)
- 4h (4 hours)
- 6h (6 hours)
- 12h (12 hours)
- 1day (1 day)
- 3day (3 days)
- 1week (1 week)
- 1M (monthly line)
- 6Hutc (UTC0 6 hour)
- 12Hutc (UTC0 12 hour)
- 1Dutc (UTC0 1day)
- 3Dutc (UTC0 3rd)
- 1Wutc (UTC0 weekly)
- 1Mutc (UTC0 monthly)
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 |
API Verification
Initiating request
The header of all REST requests must contain the following keys:
- ACCESS-KEY:API KEY as a string.
- ACCESS-SIGN: Sign with base64 encoding (see Signature).
- ACCESS-TIMESTAMP: The timestamp of your request. Value equals to milliseconds since Epoch.
- ACCESS-PASSPHRASE:The passphrase you set when creating the API KEY.
- Content-Type:Standardized setting to application/json.
- locale: Support multiple languages, such as: Chinese (zh-CN), English (en-US)
//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
- timestamp: Same as ACCESS-TIMESTAMP request header. Value equals to milliseconds since Epoch.
- method:Request method (POST/GET), all uppercase letters.
- requestPath:Request interface path.
- queryString:The query string in the request URL (the request parameter after the ?).
- body: The string corresponding to the request body. If the request has no body (usually a GET request), the body can be omitted.
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:
- timestamp = 1591089508404
- method = "GET"
- requestPath = "/api/spot/v1/market/depth"
- queryString= "?symbol=btcusdt_spbl&limit=20"
Generate the string to be signed:
'1591089508404GET/api/spot/v1/market/depth?symbol=btcusdt_spbl&limit=20'
Place order,take BTCUSDT as an example:
- timestamp = 1561022985382
- method = "POST"
- requestPath = "/api/spot/v1/order/order"
- body = {"symbol":"btcusdt_spbl","quantity":"8","side":"buy","price":"1","orderType":"limit","clientOrderId":"bitget#123456"}
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 request header information needs to be standardized as:'application/json'.
Request interaction description
- Request parameters: encapsulate parameters according to the interface request parameters.
- Submit request parameters: submit the encapsulated request parameters to the server through GET/POST.
- Server response: the server first performs parameter security verification on the user's requested data, and then returns the response data to the user in JSON format according to the business logic after passing the verification.
- Data processing: processing the server response data.
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
- 400 Bad Request – Invalid request format
- 401 Unauthorized – Invalid API Key
- 403 Forbidden – You do not have access to the requested resource
- 404 Not Found - The request is not found
- 429 Too Many Requests - Requests are too frequent and are limited by the system
- 500 Internal Server Error – Internal Server Error
- If it is failed, return body usually have an error message
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
- GET: The parameters are transmitted to the server in the path through queryString.
- POST: The parameters are sending to the server in json format.
RestAPI
Public
Get Server Time
Rate Limit: 20 times/1s (IP)
HTTP Request
Obtain server time
- GET /api/spot/v1/public/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
- GET /api/spot/v1/public/currencies
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
- GET /api/spot/v1/public/products
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"
}
]
}
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 |
Get Single Symbol
Rate Limit: 20 times/1s (IP)
HTTP Request
obtain all ticker information
- GET /api/spot/v1/public/product
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"
}
]
}
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 |
Market
Get Single Ticker
Rate Limit: 20 times/1s (IP)
HTTP Request
- GET /api/spot/v1/market/ticker
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
- GET /api/spot/v1/market/tickers
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 Market Trades
Rate Limit: 20 times/1s (IP)
HTTP Request
- GET /api/spot/v1/market/fills
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 Candle Data
Rate Limit: 20 times/1s (IP)
HTTP Request
obtain candlestick line data
- GET /api/spot/v1/market/candles
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 |
before | String | No | Time before, milliseconds |
limit | String | No | Default 100, max 100 |
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
- 1min (1 minute)
- 5min (5 minutes)
- 15min (15 minutes)
- 30min (30 minutes)
- 1h (1 hour)
- 4h (4 hours)
- 6h (6 hours)
- 12h (12 hours)
- 1day (1 day)
- 3day (3 days)
- 1week (1 week)
- 1M (monthly line)
- 6Hutc (UTC0 6 hour)
- 12Hutc (UTC0 12 hour)
- 1Dutc (UTC0 1day)
- 3Dutc (UTC0 3rd)
- 1Wutc (UTC0 weekly)
- 1Mutc (UTC0 monthly)
Get Depth
Rate Limit: 20 times/1s (IP)
HTTP Request
- GET /api/spot/v1/market/depth
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 |
Wallet
Transfer
Rate Limit:5/sec (uid)
HTTP Request
- POST /api/spot/v1/wallet/transfer
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
- spot Accept all kinds of coins
- mix_usdt Only USDT
- mix_usd Coins like BTC, ETH, EOS, XRP, USDC
- mix_usdc Only USDC
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 |
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
- POST /api/spot/v1/wallet/subTransfer
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
- spot Accept all kinds of coins
- mix_usdt Only USDT
- mix_usd Coins like BTC, ETH, EOS, XRP, USDC
- mix_usdc Only USDC
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 |
Get Coin Address
Rate Limit:5/sec (uid)
HTTP Request
- GET /api/spot/v1/wallet/deposit-address
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
- POST /api/spot/v1/wallet/withdrawal
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 |
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 |
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
- POST /api/spot/v1/wallet/withdrawal-inner
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 |
Get Withdraw list
Rate Limit:20/1s (Uid)
HTTP Request
- GET /api/spot/v1/wallet/withdrawal-list
Request Parameter
Parameter | Type | Required | Description |
---|---|---|---|
coin | String | Yes | 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 default 20, max 100 |
Request Example
curl "https://api.bitget.com/api/spot/v1/wallet/withdrawal-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.00000000",
"chain": "erc20",
"confirm": "0",
"cTime": "1653290769222",
"uTime": "1653290769222"
}
]
}
Response Description
Parameter | Description |
---|---|
id | order Id |
txId | trade Id |
coin | currency |
type | type |
amount | withdraw amount |
status | status |
toAddress | Withdraw address |
fee | Withdraw fee |
chain | Withdraw chain |
confirm | confirm times for withdraw |
cTime | create time |
uTime | update time |
- status
- Pending
- pending_review
- pending_fail
- pending_review_fail
- reject
- success
Get Deposit List
Rate Limit:20/1s (Uid)
HTTP Request
- GET /api/spot/v1/wallet/deposit-list
Request Parameter
Parameter | Type | Required | Description |
---|---|---|---|
coin | String | Yes | 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":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 |
cTime | create time |
uTime | update time |
- status
- Pending
- pending_review
- pending_fail
- pending_review_fail
- reject
- success
- wallet_processing
Account
Get ApiKey Info
Rate Limit:1/sec (Uid)
HTTP Request
- GET /api/spot/v1/account/getInfo
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
- GET /api/spot/v1/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
- POST /api/spot/v1/account/sub-account-spot-assets
Request parameter - N/A
Request Example
curl "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
- POST /api/spot/v1/account/bills
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 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
- GET /api/spot/v1/account/transferRecords
Request parameter
Parameter name | Parameter type | Required | Description |
---|---|---|---|
coinId | Integer | No | Coin ID |
fromType | String | No | Major type of bill accountType |
after | String | No | BillId, the data less or equals or equals to 'tradeTime', seconds |
before | String | No | BillId, the data greater than or equals 'tradeTime', seconds |
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=1659076670000&before=1659076670000&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"
}
],
"msg":"success"
}
Response Parameter
Parameter | Description |
---|---|
coinName | Coin name |
status | Transfer status |
toType | Transfer in account type |
toSymbol | Transfer to account Symbol |
fromType | Transfer out account type |
fromSymbol | Transfer from account Symbol |
amount | Number of transfers |
tradeTime | Transfer time |
- fromType
- exchange: spot
- usdt_mix: future USDT
- usd_mix: future coins
Trade
Place order
Rate Limit: 10/sec (uid)
HTTP Request
- POST /api/spot/v1/trade/orders
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 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
- POST /api/spot/v1/trade/batch-orders
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) |
- orderList
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
- POST /api/spot/v1/trade/cancel-order
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 in batch (single instruments)
Rate Limit: 5 times/1s (uid)
HTTP Request
- POST /api/spot/v1/trade/cancel-batch-orders
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"]
}
Get order details
Rate Limit: 20 times/sec(uid)
HTTP Request
- POST /api/spot/v1/trade/orderInfo
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",
"message":"success",
"data":[{
"accountId":"10012",
"symbol":"btcusdt_spbl",
"orderId":"2222222",
"clientOrderId":"xxxxxxx",
"price":"34245.12",
"quantity":"1",
"orderType":"limit",
"side":"buy",
"status":"new",
"fillPrice":"0",
"fillQuantity":"0",
"fillTotalAmount":"0",
"cTime":"1622697148"
}]
}
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 |
orderType | Order type, limit/market |
side | Order direction, buy/sell |
status | Order status |
fillPrice | Transaction price |
fillQuantity | Transaction quantity |
fillTotalAmount | Total transaction volume |
cTime | Creation time |
Get order List
Rate Limit: 20 times/sec (uid)
HTTP Request
- POST /api/spot/v1/trade/open-orders
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",
"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 |
orderType | Order type, limit/market |
side | Order direction, buy/sell |
status | Order status |
fillPrice | Transaction price |
fillQuantity | Transaction quantity |
fillTotalAmount | Total transaction volume |
cTime | Creation time |
Get order history
Rate Limit: 20 times/sec (uid)
HTTP Request
- POST /api/spot/v1/trade/history
Request Body
Parameter name | Parameter type | Required | Description |
---|---|---|---|
symbol | String | Yes | Symbol Id |
after | String | No | orderId, return the data less than or equals this orderId |
before | String | No | orderId, return the data greater than 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/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",
"message":"success",
"data":[{
"accountId":"10012",
"symbol":"btcusdt_spbl",
"orderId":"2222222",
"clientOrderId":"xxxxxxx",
"price":"34982.12",
"quantity":"1",
"orderType":"limit",
"side":"buy",
"status":"new",
"fillPrice":"34982.12",
"fillQuantity":"1",
"fillTotalAmount":"34982.12",
"cTime":"1622697148"
}]
}
Response Parameter
Parameter | Description |
---|---|
accountId | Account ID |
symbol | Symbol Id |
orderId | Order ID |
clientOrderId | Custom ID |
price | Order price |
quantity | Order quantity |
orderType | Order type, limit/market |
side | Order direction, buy/sell |
status | Order status |
fillPrice | Transaction price |
fillQuantity | Transaction quantity |
fillTotalAmount | Total transaction volume |
cTime | Creation time |
Get transaction details
Rate Limit: 20 times/sec (uid)
HTTP Request
- POST /api/spot/v1/trade/fills
Request Body
Parameter name | Parameter type | Required | Description |
---|---|---|---|
symbol | String | Yes | Symbol ID |
orderId | String | No | Order ID |
after | String | No | Send in orderId, the data before this orderId desc |
before | String | No | Send in the orderId, the data after this orderId asc |
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
- POST /api/spot/v1/plan/placePlan
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
- POST /api/spot/v1/plan/modifyPlan
Request Body
Parameter name | Parameter type | Required | Description |
---|---|---|---|
orderId | String | Yes | order ID |
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
- POST /api/spot/v1/plan/cancelPlan
Request Body
Parameter name | Parameter type | Required | Description |
---|---|---|---|
orderId | String | Yes | order ID |
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 | order ID |
Get current plan orders
Rate Limit: 20 times/sec (uid)
HTTP Request
- POST /api/spot/v1/plan/currentPlan
Request Body
Parameter name | Parameter type | Required | Description |
---|---|---|---|
symbol | String | Yes | Symbol ID |
pageSize | String | No | 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",
"symbol": "TRXUSDT_SPBL",
"size": "151",
"executePrice": "0.041572",
"triggerPrice": "0.041572",
"status": "not_trigger",
"orderType": "limit",
"side": "buy",
"triggerType": "fill_price",
"cTime": "1668134576563"
}
]
}
}
Response Parameter
Parameter | Description |
---|---|
orderId | Order ID |
symbol | Symbol ID |
size | Purchase quantity |
executePrice | Order execute price |
triggerPrice | Order trigger price |
status | Order status |
orderType | Order type |
side | Buying direction |
triggerType | Order trigger type |
cTime | Create time |
Get history plan orders
Rate Limit: 20 times/sec (uid)
HTTP Request
- POST /api/spot/v1/plan/historyPlan
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",
"symbol": "TRXUSDT_SPBL",
"size": "156",
"executePrice": "0.041272",
"triggerPrice": "0.041222",
"status": "cancel",
"orderType": "limit",
"side": "buy",
"triggerType": "fill_price",
"cTime": "1668134458717"
}
]
}
}
Response Parameter
Parameter | Description |
---|---|
orderId | Order ID |
symbol | Symbol ID |
size | Purchase quantity |
executePrice | Order execute price |
triggerPrice | Order trigger price |
status | Order status |
orderType | Order type |
side | Buying direction |
triggerType | Order trigger type |
cTime | Create time |
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:
- The WebSocket request header size for data transmission between client and server is only 2 bytes.
- Either the client or server can initiate data transmission.
- There's no need to repeatedly create and delete TCP connections, saving resources on bandwidth and server.
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: 1 time per second
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:
- Set a timer of 30 seconds.
- If the timer is triggered, send the String 'ping'.
- Expect a 'pong' as a response. If the response message is not received within 30 seconds, please raise an error and/or reconnect.
- The Websocket server accepts up to 10 messages per second. The message includes:
- PING frame
- Messages in JSON format, such as subscribe, unsubscribe.
- 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;
- A single connection can subscribe up to 1000 Streams;
- 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
etc -- do not require log in.
instId
refer to Get Symbols in response field:symbolName
Private channels
-- including
etc -- require login.
- User account channel
instId
isdefault
: Get all currency assets
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.
- 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.
- 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]"
- 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]
... - 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]
...
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 100 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
Retrieve account information. Data will be pushed when triggered by events such as placing/canceling order, and will also be pushed in regular interval according to subscription granularity.
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 parameters
Parameter | Type | Description |
---|---|---|
> 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 | Categorynormal twap adl full_liquidation partial_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 |
> 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 |
> 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 |
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 |
Invalid ACCESS_KEY | 30011 |
Invalid ACCESS_PASSPHRASE | 30012 |
Invalid ACCESS_TIMESTAMP | 30013 |
Request timestamp expired | 30014 |
Invalid signature | 30015 |