简体中文
NAV
console python

Group And Resources

Bybit API and WebSocket documentation provides guidance to help you access Bybit's endpoints, their expected outputs, and common errors.

For further assistance or feedback, please join the API Telegram chat! API discussion group on Telegram.

Group And Bybit API Resources

Changelog

2021-08-26

REST API

Authentication

All requests made to private endpoints must be authenticated. Requests made to public endpoints do not require additional authentication.

Parameters for Authenticated Endpoints

The following parameters must be used for authentication:

We also provide recv_window (unit in millisecond and default value is 5,000) to specify how long an HTTP request is valid. It is also used to prevent replay attacks.

A smaller recv_window is more secure, but your request may fail if the transmission time is greater than your recv_window.

Please make sure that your timestamp is in sync with our server time. You can use the Server Time endpoint.

Create A Request

An example for adjusting leverage

param_str = "api_key=B2Rou0PLPpGqcU0Vu2&leverage=100&symbol=BTCUSDH21&timestamp=1542434791747"

# api_key=B2Rou0PLPpGqcU0Vu2&
# leverage=100&
# symbol=BTCUSDH21&
# timestamp=1542434791747

Note how the parameters are ordered in alphabetical order, with api_key first followed by leverage, then symbol, then timestamp.

1. Concatenate all the public parameters in the query string format. The parameters must be ordered in alphabetical order. This will be used to generate the sign.

2. Use the HMAC_SHA256 algorithm to sign the query string in step 1, and convert it to a hex string to obtain the sign parameter.

Different requests need different message formats. Message format for GET requests:

GET /asset/v1/private/transfer/list?api_key=q1ksyOX2T0G2SkK8nu&recvWindow=5000&timestamp=1623208423972&sign=b452640c21a2c9eaec30d24a9bce1a9660d1fb9d07ccc0d623a2a4fca0940095 HTTP/1.1
Host: api-testnet.bybit.com

Message format for POST requests:

POST /asset/v1/private/transfer HTTP/1.1
Host: api-testnet.bybit.com
Content-Type: application/json

{
    "from_account_type": "SPOT",
    "to_account_type": "CONTRACT",
    "amount": "0.01",
    "coin": "USDT",
    "transfer_id": "11ff9b44-2d5d-4293-913d-4597c9ad2170",
    "sign": "{{signature}}",
    "timestamp": "{{timestamp}}",
    "api_key": "{{bybit-api-key}}",
    "recv_window": "50000"
}

Transfer Data Endpoints

The following API data endpoints require authentication.

Create Internal Transfer

Request Example

curl --location --request POST 'https://api-testnet.bybit.com/asset/v1/private/transfer' \
--header 'Content-Type: application/json' \
--data-raw '{
    "from_account_type": "SPOT",
    "to_account_type": "CONTRACT",
    "amount": "0.1",
    "coin": "BTC",
    "transfer_id": "b668ce35-db92-4db4-9f81-0b5da57d4df6",
    "api_key": "YtcjswsO9WjAmQVUx7",
    "sign": "{{sign}}",
    "timestamp": "{{timestamp}}",
    "recv_window": "{{recvWindow}}"
}'

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "result": {
        "transfer_id": "b668ce35-db92-4db4-9f81-0b5da57d4df6"
    },
    "ext_info": null,
    "time_now": 1629951080227,
    "rate_limit_status": 17,
    "rate_limit_reset_ms": 1629951080227,
    "rate_limit": 3
}

Transfers funds between the different sections of an individuals account (not between subaccounts). For example, between the spot and derivatives accounts.

HTTP Request

POST /asset/v1/private/transfer

Request Parameters

Parameter Required Type Comment
transfer_id true string UUID, which is unique across the platform
coin true string Currency type
amount true string Exchange to amount
from_account_type true string Account type
to_account_type true string Account type

Response Parameters

Parameter Type Comment
transfer_id string UUID, which is unique across the platform

Create Subaccount Transfer

Request Example

curl --location --request POST 'https://api-testnet.bybit.com/asset/v1/private/sub-member/transfer' \
--header 'Content-Type: application/json' \
--data-raw '{
    "transfer_id": "5f95de18-b10f-43be-9746-7b95c4a37d97",
    "amount": "0.1",
    "coin": "BTC",
    "sub_user_id":"251711",
    "type": "IN",
    "api_key": "YtcjswsO9WjAmQVUx7",
    "sign": "{{sign}}",
    "timestamp": "{{timestamp}}",
    "recv_window": "{{recvWindow}}"
}'

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "result": {
        "transfer_id": "5f95de18-b10f-43be-9746-7b95c4a37d97"
    },
    "ext_info": null,
    "time_now": 1629966770894,
    "rate_limit_status": 18,
    "rate_limit_reset_ms": 1629966770894,
    "rate_limit": 2
}

Transfers funds between the parent and child (sub) accounts.

HTTP Request

POST /asset/v1/private/sub-member/transfer

Request Parameters

Parameter Required Type Comment
transfer_id true string UUID, which is unique across the platform
coin true string Currency type
amount true string Exchange to amount
sub_user_id true string Subaccount
type true string Determines the direction of transfer

Response Parameters

Parameter Type Comment
transfer_id string UUID, which is unique across the platform

Query Transfer List

Request Example

curl --location --request GET 'https://api-testnet.bybit.com/asset/v1/private/transfer/list'

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "result": {
        "list": [
            {
                "transfer_id": "selfTransfer_c5ae452d-43e8-47e6-aa7c-d2bab57c0958",
                "coin": "BTC",
                "amount": "1",
                "from_account_type": "CONTRACT",
                "to_account_type": "SPOT",
                "timestamp": "1629965054",
                "status": "SUCCESS"
            },
            {
                "transfer_id": "selfTransfer_9a183347-152d-4bdc-990d-8b20284385f9",
                "coin": "BTC",
                "amount": "1",
                "from_account_type": "SPOT",
                "to_account_type": "CONTRACT",
                "timestamp": "1629963043",
                "status": "SUCCESS"
            },
            {
                "transfer_id": "selfTransfer_5f9bfd6e-1718-4a16-814e-1d1bff4b01eb",
                "coin": "BTC",
                "amount": "20",
                "from_account_type": "SPOT",
                "to_account_type": "CONTRACT",
                "timestamp": "1629874294",
                "status": "SUCCESS"
            }
        ],
        "cursor": "eyJtaW5JRCI6Nzg5NTcsIm1heElEIjo3OTM2NH0="
    },
    "ext_info": null,
    "time_now": 1629971474462,
    "rate_limit_status": 59,
    "rate_limit_reset_ms": 1629971474462,
    "rate_limit": 1
}

HTTP Request

GET /asset/v1/private/transfer/list

Request Parameters

Parameter Required Type Comment
transfer_id false string UUID, which is unique across the platform
coin false string Currency type
status false string Transfer status
start_time false integer Start timestamp point for result, in milliseconds
end_time false integer End timestamp point for result, in milliseconds
direction false string Turn page
limit false integer Number of records
cursor false string Page turning mark. Use return cursor. Sign using origin data, in request please use urlencode

Response Parameters

Parameter Type Comment
transfer_id string UUID, which is unique across the platform
coin string Currency type
amount string Exchange to amount
from_account_type string Account type
to_account_type string Account type
timestamp integer timestamp
status string Transfer status
cursor string Page turning mark. Use return cursor. Sign using origin data, in request please use urlencode

Query Subaccount Transfer List

Request Example

curl --location --request GET 'https://api-testnet.bybit.com/asset/v1/private/sub-member/transfer/list'

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "result": {
        "list": [
            {
                "transfer_id": "5f95de18-b10f-43ba-9756-0b95c4a37d07",
                "coin": "BTC",
                "amount": "0.1",
                "user_id": 229988,
                "sub_user_id": 251711,
                "timestamp": "1629968375",
                "status": "SUCCESS",
                "type": "IN"
            },
            {
                "transfer_id": "5f95de18-b10f-43be-9756-0b95c4a37d07",
                "coin": "BTC",
                "amount": "0.1",
                "user_id": 229988,
                "sub_user_id": 251711,
                "timestamp": "1629968351",
                "status": "SUCCESS",
                "type": "IN"
            },
            {
                "transfer_id": "5f95de18-b10f-43be-9746-0b95c4a37d07",
                "coin": "BTC",
                "amount": "0.1",
                "user_id": 229988,
                "sub_user_id": 251711,
                "timestamp": "1629967817",
                "status": "SUCCESS",
                "type": "IN"
            },
            {
                "transfer_id": "5f95de18-b10f-43be-9746-7b95c4a37d97",
                "coin": "BTC",
                "amount": "0.1",
                "user_id": 229988,
                "sub_user_id": 251711,
                "timestamp": "1629966772",
                "status": "SUCCESS",
                "type": "IN"
            }
        ],
        "cursor": "eyJtaW5JRCI6NzkzNzgsIm1heElEIjo3OTQwMH0="
    },
    "ext_info": null,
    "time_now": 1629978073116,
    "rate_limit_status": 59,
    "rate_limit_reset_ms": 1629978073116,
    "rate_limit": 1
}

HTTP Request

GET /asset/v1/private/sub-member/transfer/list

Request Parameters

Parameter Required Type Comment
transfer_id false string UUID, which is unique across the platform
coin false string Currency type
status false string Transfer status
start_time false integer Start timestamp point for result, in milliseconds
end_time false integer End timestamp point for result, in milliseconds
direction false string Turn page
limit false integer Number of records
cursor false string Page turning mark. Use return cursor. Sign using origin data, in request please use urlencode

Response Parameters

Parameter Type Comment
transfer_id string UUID, which is unique across the platform
coin string Currency type
amount string Exchange to amount
user_id integer Subaccount
sub_user_id integer Subaccount
timestamp integer timestamp
status string Transfer status
type string Determines the direction of transfer
cursor string Page turning mark. Use return cursor. Sign using origin data, in request please use urlencode

Query Subaccount List

Request Example

curl --location --request GET 'https://api-testnet.bybit.com/asset/v1/private/sub-member/member-ids'

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "result": {
        "sub_user_id": [
            251711
        ]
    },
    "ext_info": null,
    "time_now": 1629979703311,
    "rate_limit_status": 59,
    "rate_limit_reset_ms": 1629979703311,
    "rate_limit": 1
}

HTTP Request

GET /asset/v1/private/sub-member/member-ids

Request Parameters

Parameter Required Type Comment

Response Parameters

Parameter Type Comment
sub_user_id integer Subaccount

API Data Endpoints

The following API data endpoints do not require authentication.

Server Time

Request Example

curl https://api-testnet.bybit.com/v2/public/time
import bybit
client = bybit.bybit(test=True, api_key="api_key", api_secret="api_secret")
print(client.Common.Common_getTime().result())

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": {},
    "time_now": "1577444332.192859"
}

Get Bybit server time.

HTTP Request

GET /v2/public/time

Request Parameters

Parameter Required Type Comment

Announcement

Request Example

curl https://api.bybit.com/v2/public/announcement

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": [
        {
            "id": 2,
            "title": "2019-12-02 RELEASE",
            "link": "https://github.com/bybit-exchange/bybit-official-api-docs/blob/master/en/CHANGELOG.md",
            "summary": "<p>New `cancel all` endpoint is here now!</p><p>Additionally, we strongly recommend that you use the new released place and cancel active V2 endpoints, which are more stable and efficient.The old ones are deprecated (although still working for the time be",
            "created_at": "2019-12-02T11:33:42Z"
        }
    ],
    "time_now": "1577444818.227082"
}

Get Bybit OpenAPI announcements in the last 30 days in reverse order.

HTTP Request

GET /v2/public/announcement

Request Parameters

Parameter Required Type Comment

API Rate Limits

IP Rate Limit

The IP limits are shared across all endpoints: futures, spot, and account asset. However, the mainent and testnet IP limits are separate.

Bybit has different IP frequency limits for GET and POST method:

Rate Limits For Transfer Endpoints

Limit Path Consume
20/min /asset/v1/private/transfer 1 / request
/asset/v1/private/sub-member/transfer 1 / request
60/min /asset/v1/private/sub-member/member-ids 1 / request
/asset/v1/private/transfer/list 1 / request
/asset/v1/private/sub-member/transfer/list 1 / request

Enums Definitions

The following lists enumerator names for the request and response parameters of each endpoint.

Account type (from_account_type/to_account_type)

Currency (currency/coin)

Operator type

Transfer type (type)

Transfer status (status)

Page direction (direction)

Errors

The Bybit API uses the following HTTP codes and error codes:

HTTP Code Meaning
200 Request is valid
403 Access denied
404 Request path not found
Error Code Meaning
0 SUCCESS
10001 ParamErr
10016 SvcErr
38000 Processing
38001 AvailableBalanceRunningLow
38002 CannotBeTransfer
90001 TransferAmountLessThanZero
90002 TransferAmountScaleMore
90003 TransferLTVCheckError
90004 AccountNotFound
90005 AccountNotFound
90006 QueryTransferError
90007 QuerySubMemberTransferError
90008 QueryTransferIDRedisError
90009 TransferIDExist
90010 AccountTypeError
90011 GetSubMemberRelationError