Welcome

Welcome to Bitget API Document! Click here for a quick start

Update log

Aug 15, 2024

• API rate limit adjustment

Aug 17, 2023

• New Interfaces
  • query sub account transfer record
  • query sub account deposit record
  • query sub account withdrawal record

Jul 5, 2023

• Update the enum of 'perm' in Create Sub ApiKey (Only Broker)

Dec 28, 2022

• Provide brand new telegram group for Openapi technical support

September 28, 2022

• Add Sub Account Interface -> Sub Deposit Auto Transfer

September 27, 2022

• Add sub-account binding email
• Add sub-account to get email

July 01, 2022 [Added Broker Sub List]

• Added Sub List Interface

May 27, 2022 [Added Broker document]

• Added V1 documentation
• Error message support in Chinese/English

Introduction

API Introduction

Welcome to Bitget Developer document!

This document is the only official API document of Bitget API. We will constantly update the functionalities of Bitget API here. Please pay attention to it regularly.

You can switch to access different API products by clicking the upper menu, and you can switch a preferred language by clicking the language button on the upper right.

On the right side of the document will display examples of request parameters and response results.

Updates

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

You can click here to subscribe to announcements.

Contact Us

If you have any questions or suggestions, you can contact us here:

• Send an email to API@bitget.com.
• Telegram Join

Quick Start

Access Preparation

This document is intended to clarify the API usage for brokers . If you have certain R&D and operation capabilities, and want to build a trading platform and manage your user independently, the independent broker service Yes is the best choice. You are responsible for front-end development and user operations, while Bitget provides you with back-end technology and market liquidity to empower your transaction value-added services.

• The broker could send an email to apply to become a Bitget broker
• Brokers could create APIKey at here after login, make sure to set an IP whitelist while creating the APIKey
• Brokers can create their own sub-accounts through this API, control permissions, create sub-account APIKeys, and place orders through sub-account APIKey.

Interface Type

This chapter mainly divides the interface types into the following two aspects：

• Sub Account Interface
• Sub API Interface

Sub Account Interface

Create sub-accounts, modify permissions and query the list of sub-account information。

Sub API Interface

Create the APIKey for the sub-account, and set the permissions。

Access Restriction

This chapter mainly focuses on access restrictions:

• Rest API will return 429 status when the access exceeds the frequency limit: the request is too frequent.

Rest API

If the APIKey is valid, you can use the APIKey to limit the speed; if not, use the public network IP to limit the speed.

Speed limit rules: There are separate instructions on each interface. If there is no general interface, the speed limit is 10 times per second.

Special note: When placing orders in batches, 10 orders per currency pair will be counted as one request.

API Domain Name

You can use the Rest API access method to operate by yourself.

API Verification

Initiate a request

The header of all REST requests must contain the following key：

• ACCESS-KEY：apiKey as a string, click to apply here after login
• ACCESS-SIGN：hmac SHA256 encrypt and base64 encoding(see signature )
• ACCESS-TIMESTAMP：Timestamp of your request, milliseconds since epoch
• ACCESS-PASSPHRASE：The passphrase you set while create the apiKey
• Content-Type：Set to application/json for POST request
• locale: Support languages such as: English (en-US), Chinese (zh-CN)

//Java
Long timestamp = 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

Signature - build content

//timestamp: milliseconds
//method: GET or POST
//requestPath: url path
//queryString: '?uid=123&startTime=16800001234&endTime=16800004321'
String content = timestamp + method.toUpperCase() + requestPath + queryString + body;

The request header of ACCESS-SIGN is generated as follows

1). Concatenate a string content like in the right console:

Signature - encrypt and encode

String encryptedString = hmacSHA256(content, secretKey);
String signature = Base64.encode(encryptedString);

2). Encrypt the content by HMAC SHA256 algorithm with the secretKey, at the end use BASE64 to encode the hmac sha256 output.

Description of each fields in the signature

• timestamp：Same as ACCESS-TIMESTAMP request header, milliseconds since epoch
• method：Request http method (POST/GET), uppercase
• requestPath：Request url path
• queryString：The query string in the request URL (Usually the GET request parameters after the ?).
• body：The request body json string. If the request has no body (usually a GET request), the body can be omitted.

When the queryString is empty, signature content

String content = timestamp + method.toUpperCase() + requestPath + body;

When the queryString not empty, signature content

String content = timestamp + method.toUpperCase() + requestPath + "?" + queryString + body;

For example

Get Broker Info :

• Timestamp = 16273667805456
• Method = "GET"
• requestPath = "/api/broker/v1/account/sub-list"
• queryString= "?pageSize=10&lastEndId=0&status=normal"

Generate the content string to be encrypted and encoded:

'16273667805456GET/api/broker/v1/account/sub-list?pageSize=10&lastEndId=0&status=normal'

Create Sub Account :

• timestamp = 16273667805456
• method = "POST"
• requestPath = "/api/broker/v1/account/sub-create"
• body = {"subName":"mySub01","remark":"myBitgetSub"}

Generate the string to be signed:

'16273667805456POST/api/broker/v1/account/sub-create{"subName":"mySub01","remark":"myBitgetSub"}'

Steps to generate the final signature

HMAC

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);

RSA

Step 1. Use the RSA privateKey privateKey to encrypt the string to be signed with SHA-256

Step 2. Base64 encoding for Signature.

Request Interaction

All requests are based on the Https protocol, and the Content-Type in the request header information needs to set to:'application/json' for all POST methods.

Request Interaction Description

• Request parameters: Encapsulate parameters according to the interface request method: queryString for GET and json body for POST.
• 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 request parameters, and returns the response data to the user in JSON format according to the business logic afterwards.
• Data processing：Process 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 json field.

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 – No request found

• 429 Too Many Requests – Requests are too frequent and are limited by the system

• 500 Internal Server Error – We had a problem within our server

• If it fails, the 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 server 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 http header by querying the API server time.

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 in request body.

API Common parameters

account status

• normal
• freeze
• del

auth

• withdraw
• recharge
• transfer
• spot_trade
• contract_trade
• readonly: read permission (not actually readonly)

perm

• recharge
• transfer
• spot_trade
• contract_trade
• readonly: read permission (not actually readonly)

productType

• umcbl USDT perpetual contract
• dmcbl Universal margin perpetual contract
• cmcbl USDC perpetual contract
• sumcbl USDT simulation perpetual contract
• sdmcbl Universal margin simulation perpetual contract
• scmcbl USDC simulation perpetual contract

marginMode

Position Mode

• fixed Isolated margin crossed Cross margin

toAccountType

• spot
• mix_usdt
• mix_usd
• mix_usdc

RestAPI

Sub Account Interface

Get Broker Info

Limit rule：10/sec (uid)

HTTP Request

• GET /api/broker/v1/account/info

Response

{
    "code":"00000",
    "msg":"success",
    "data":{
        "subAccountQty":"2311",
        "maxSubAccountQty":"5000"
    }
}

Response Parameter

Create Sub Account

Limit rule：1/sec (uid)

HTTP Request

• POST /api/broker/v1/account/sub-create

Request Parameter(Request Body)

Response

{
    "code":"00000",
    "msg":"success",
    "data":{
        "subUid":"293848922",
        "subName":"subEmail@hyc.com",
        "status":"normal",
        "auth":["spot_trade","transfer"],
        "remark":"mySub01",
        "cTime":"1651130117853"
    }
}

Response Parameter

Get Sub List

Limit rule：1/sec (uid)

HTTP Request

• GET /api/broker/v1/account/sub-list

Request Parameter(Request Param)

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",
                    "transfer",
                    "withdraw",
                    "recharge"
                ],
                "remark": "mySub01",
                "cTime": "1653287983475"
            }
        ]
    }
}

 Response Parameter

Modify Sub Account

Limit rule：1/sec/UID

HTTP Request

• POST /api/broker/v1/account/sub-modify

Request Parameter(Request Body)

Response

{
    "code":"00000",
    "msg":"success",
    "data":{
        "subUid":"293848922",
        "subName":"subEmail@hyc.com",
        "status":"normal",
        "auth":["spot_trade","transfer"],
        "remark":"mySub01",
        "cTime":"1651130117853"
    }
}

 Response Parameter

Modify Sub Email

Limit rule：1/sec (ApiKey)

HTTP Request

• POST /api/broker/v1/account/sub-modify-email

Request Parameter(Request Body)

Response

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

Response Parameter

GET Sub Email

Limit rule：1/sec (ApiKey)

HTTP Request

• GET /api/broker/v1/account/sub-email

Request Parameter(Request Parameter)

Response

{
    "code": "00000",
    "msg": "success",
    "requestTime": 0,
    "data": {
        "subUid": 7713789662,
        "subName": "demo@bitget.com",
        "subEmail": "demo@bitget.com"
    }
}

Response Parameter

Get Sub Spot Assets

Limit rule：10/sec (uid)

HTTP Request

• GET /api/broker/v1/account/sub-spot-assets

Request Parameter(Request Body)

Response

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

Response Parameter

Get Sub Future Assets

Limit rule：10/sec (uid)

HTTP Request

• GET /api/broker/v1/account/sub-future-assets

Request Parameter(Request Body)

Response

{
    "code":"00000",
    "data":[
        {
            "marginCoin":"USDT",
            "locked":"0.31876482",
            "available":"10575.26735771",
            "crossMaxAvailable":"10580.56434289",
            "fixedMaxAvailable":"10580.56434289",
            "maxTransferOut":"10572.92904289",
            "equity":"10582.90265771",
            "usdtEquity":"10582.902657719473",
            "btcEquity":"0.204885807029"
        }
    ],
    "msg":"success",
    "requestTime":1630901215622
}

Response Parameter

Get Sub Deposit Address (Only Broker)

Limit rule：10/sec (uid)

HTTP Request

• POST /api/broker/v1/account/sub-address

Request Parameter(Request Body)

Response:

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

Response Parameter

Sub Withdrawal (Only Broker)

Limit rule：1/sec (uid)

HTTP Request

• POST /api/broker/v1/account/sub-withdrawal

Request Parameter(Request Body)

Response:

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

Sub Deposit Auto Transfer (Only Broker)

Limit rule：5/sec (uid)

HTTP Request

• POST /api/broker/v1/account/sub-auto-transfer

Request Parameter(Request Body)

Response:

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

query sub account transfer record

Rate Limit times/sec (uid)

HTTP Request

• GET /api/broker/v1/subaccount-transfer

Request Example

curl "https://api.bitget.com/api/broker/v1/subaccount-transfer?orderId=123" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" 

Request Body

Response

{
    "code": "00000",
    "msg": "success",
    "requestTime": 1689833233282,
    "data": {
        "coin": "USDT",
        "status": "Successful",
        "toType": "spot",
        "toSymbol": null,
        "fromType": "usdt_m_futures",
        "fromSymbol": null,
        "amount": "10",
        "transferTime": "1689833233282",
        "orderId": "XXXXX",
        "clientOid": "XXXXX",
        "subUid": "123123",
        "transferId": "XXXXX"
    }
}

Response Parameter

• status

  • Successful
  • Failed
  • Processing

• toType/fromType

  • spot
  • p2p
  • coin_m_futures
  • usdt_m_futures
  • usdc_m_futures
  • cross_margin
  • isolated_margin

query sub account deposit record

Rate Limit times/sec (uid)

HTTP Request

• GET /api/broker/v1/subaccount-deposit

Request Example

curl "https://api.bitget.com/api/broker/v1/subaccount-deposit?orderId=123" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" 

Request Body

Response

{
    "code": "00000",
    "msg": "success",
    "requestTime": 1689833233282,
    "data": {
        "orderId": "XXXXX",
        "txId": "XXXXXXX",
        "coin": "USDT",
        "type": "deposit",
        "dest": "internal_transfer",
        "amount": "10",
        "status": "success",
        "fromAddress": "123123",
        "toAddress": "456456",
        "fee": "1",
        "chain": "erc20",
        "confirm": "3",
        "tag": "xx",
        "cTime": "1689833233282",
        "uTime": "1689833233282"
    }
}

Response Parameter

• dest

  • on_chain
  • internal_transfer

• status

  • pending
  • pending_review
  • pending_fail
  • pending_review_fail
  • reject
  • success

query sub account withdrawal record

Rate Limit times/sec (uid)

HTTP Request

• GET /api/broker/v1/subaccount-withdrawal

Request Example

curl "https://api.bitget.com/api/broker/v1/subaccount-withdrawal?orderId=123" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" 

Request Body

Response

{
    "code": "00000",
    "msg": "success",
    "requestTime": 1689833233282,
    "data": {
        "orderId": "XXXXX",
        "txId": "XXXXXXX",
        "coin": "USDT",
        "type": "withdraw",
        "dest": "internal_transfer",
        "amount": "10",
        "status": "success",
        "fromAddress": "123123",
        "toAddress": "456456",
        "fee": "1",
        "chain": "erc20",
        "confirm": "3",
        "tag": "xx",
        "cTime": "1689833233282",
        "uTime": "1689833233282"
    }
}

Response Parameter

• dest

  • on_chain
  • internal_transfer

• status

  • pending
  • pending_review
  • pending_fail
  • pending_review_fail
  • reject
  • success

Sub API Interface

Create Sub ApiKey (Only Broker)

Limit rule：10/sec (uid)

HTTP Request

• POST /api/broker/v1/manage/sub-api-create

Request Parameter(Request Body)

Response:

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

Response Parameter

Get Sub ApiKey List

Limit rule：10/sec (uid)

HTTP Request

• GET /api/broker/v1/manage/sub-api-list

Request Parameter

Response:

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

Response Parameter

Modify Sub ApiKey (Only Broker)

Limit rule：10/sec (uid)

HTTP Request

• POST /api/broker/v1/manage/sub-api-modify

Request Parameter(Request Body)

Response:

{
  "code": "00000",
  "msg": "success",
  "data": {
      "subUid": "58281113",
      "label": "sub api",
      "apiKey": "bg_djwwwls98a1s0dLK3deq2",
      "perm": "read_only,contract_trade",
      "ip": "127.127.127.127"
    }
}

Response Parameter

Error Codes