Introduction

Authentication

info

Please visit Bybit's testnet or mainnet to generate an API key

REST API Base Endpoint:

• Testnet:
  https://api-testnet.bybit.com
• Mainnet(both endpoints are available):
  https://api.bybit.com
  https://api.bytick.com

info

• All requests made to private endpoints MUST be authenticated.

Select Your API Key Type

• System-generated API Keys: The API key generated by the Bybit system operates with HMAC encryption. You will be provided with a pair of public and private keys. Please treat this pair of keys as passwords and keep them safe.

  Follow HMAC sample scripts to complete encryption procedures.

• Auto-generated API Keys: Self-generated API keys operate with RSA encryption. You must create your public and private keys through the software, and then only provide the public key to Bybit, we will never hold your private key.

  1.Use api-rsa-generator to create RSA private and public key
  2.Follow RSA sample scripts to complete encryption procedures.

Parameters for Authenticated Endpoints

The following parameters must be used for authentication:

• X-BAPI-API-KEY - api key
• X-BAPI-TIMESTAMP - UTC timestamp in milliseconds
• X-BAPI-SIGN - a signature derived from the request's parameters
• X-Referer or Referer - the header for broker users only
  

We also provide X-BAPI-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 X-BAPI-RECV-WINDOW is more secure, but your request may fail if the transmission time is greater than your X-BAPI-RECV-WINDOW.

caution

Please make sure that the timestamp parameter adheres to the following rule:
server_time - recv_window <= timestamp < server_time + 1000

Create A Request

info

Example signature algorithms can be found here

Basic steps:

1. timestamp + api-key + (recv_window) + (queryString | jsonBodyString)
   
2. Use the HMAC_SHA256 or RSA_SHA256 algorithm to sign the string in step 1, and convert it to a hex string (HMAC_SHA256) / base64 (RSA_SHA256) to obtain the sign parameter.
   
3. Append the sign parameter to request header, and send the HTTP request. Note: the plain text for GET and POST requests is different. Please refer to blew examples.

An example for how to generate plain text to encrypt

GET

# rule:
timestamp+api_key+recv_window+queryString

# param_str
"1658384314791XXXXXXXXXX5000category=option&symbol=BTC-29JUL22-25000-C"

# parse
timestamp = "1658384314791"
api_key = "XXXXXXXXXX"
recv_window = "5000"
queryString = "category=option&symbol=BTC-29JUL22-25000-C"

POST

# rule:
timestamp+api_key+recv_window+raw_request_body

# param_str
1658385579423XXXXXXXXXX5000{
    "category": "linear"
}

# parse
timestamp = 1658385579423
api_key = XXXXXXXXXX
recv_window = 5000
raw_request_body = {"category": "linear"}

http request examples

http-get

GET /unified/v3/private/order/list?category=option&symbol=BTC-29JUL22-25000-C HTTP/1.1
Host: api-testnet.bybit.com
-H 'X-BAPI-SIGN: XXXXXXXXXX' \
-H 'X-BAPI-API-KEY: XXXXXXXXXX' \
-H 'X-BAPI-TIMESTAMP: 1658384431891' \
-H 'X-BAPI-RECV-WINDOW: 5000'
-H 'cdn-request-id: test-001'

http-post

POST /unified/v3/private/order/cancel-all HTTP/1.1
Host: api-testnet.bybit.com
-H 'X-Referer: XXXXXXXXXX' \ [the header for broker users only]
-H 'X-BAPI-SIGN: XXXXXXXXXX' \
-H 'X-BAPI-API-KEY: XXXXXXXXXX' \
-H 'X-BAPI-TIMESTAMP: 1658385589135' \
-H 'X-BAPI-RECV-WINDOW: 5000' \
-H 'Content-Type: application/json' \
-H 'cdn-request-id: test-002'
-d '{
"category": "option"
}'

Common response parameters

Derivatives

Parameter	Type	Comments
retCode	number	Success/Error code
retMsg	string	Success/Error msg. Can be OK,success,Success for Success message
result	Object	Business data result
retExtInfo	Object	Extend info. Most of time, it is {}
time	number	Current timestamp (ms)

{
    "retCode": 0,
    "retMsg": "OK",
    "result": {
    },
    "retExtInfo": {},
    "time": 1671017382656
}

{
    "retCode": 0,
    "retMsg": "success",
    "result": {
    },
    "retExtInfo": {},
    "time": 1671017473888
}

{
    "retCode": 0,
    "retMsg": "Success",
    "result": {
    },
    "retExtInfo": {},
    "time": 1671017572923
}

Spot

Parameter	Type	Comments
retCode	number	Success/Error code
retMsg	string	Success/Error msg. Can be OK,success,Success for Success message
result	Object	Business data result
retExtInfo	Object	Extend info. Most of time, it is {}
time	number	Current timestamp (ms)

{
    "retCode": 0,
    "retMsg": "OK",
    "result": {
    },
    "retExtInfo": {},
    "time": 1671017382656
}

{
    "retCode": 0,
    "retMsg": "success",
    "result": {
    },
    "retExtInfo": {},
    "time": 1671017473888
}

{
    "retCode": 0,
    "retMsg": "Success",
    "result": {
    },
    "retExtInfo": {},
    "time": 1671017572923
}

Account Asset

Parameter	Type	Comments
retCode	number	Success/Error code
retMsg	string	Success/Error msg. Can be OK,success,Success for Success message
result	Object	Business data result
retExtInfo	Object	Extend info. Most of time, it is {}
time	number	Current timestamp (ms)

{
    "retCode": 0,
    "retMsg": "OK",
    "result": {
    },
    "retExtInfo": {},
    "time": 1671017382656
}

{
    "retCode": 0,
    "retMsg": "success",
    "result": {
    },
    "retExtInfo": {},
    "time": 1671017473888
}

{
    "retCode": 0,
    "retMsg": "Success",
    "result": {
    },
    "retExtInfo": {},
    "time": 1671017572923
}