Skip to main content

Integration Guidance

tip

To learn more about the V5 API, please read the Introduction.

API Resources and Support Channels​

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
important
  • Netherland users: use https://api.bybit.nl for mainnet
  • Hong Kong users: use https://api.byhkbit.com for mainnet
  • Turkey users: use https://api.bybit-tr.com for mainnet
  • Kazakhstan users: use https://api.bybit.kz for mainnet
    Bybit cannot promise the stability and performance if you are still using api.bybit.com, and this domain has the possibility to be shutdown at any time for users from these countries/areas.

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 keys
  2. Follow the RSA sample scripts to complete encryption procedures.

Parameters for Authenticated Endpoints​

The following HTTP header keys 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
which means your timestamp should lie in range: [server_time - recv_window; server_time + 1000)
server_time stands for Bybit server time, which can be queried via the Server Time endpoint. Keep in mind it's highly recommended that you use local device time for timestamp and keep it NTP-synchronized at all times.

Create A Request​

tip

To assist in diagnosing advanced network problems, you may consider adding cdn-request-id to your request headers. Its value should be unique for each request.

Basic steps:

  1. Calculate the string you want to sign as follows: For GET requests: timestamp + API key + recv_window + queryString For POST requests: timestamp + API key + recv_window + jsonBodyString
  2. Use the HMAC_SHA256 or RSA_SHA256 algorithm to sign the string in step 1, and convert it to a lowercase HEX string for HMAC_SHA256, or base64 for RSA_SHA256 to obtain the string value of your signature.
  3. Add your signature to X-BAPI-API-KEY header send the HTTP request. You can refer to examples below for more info
info
Example signature algorithms can be found here.

An example for how to generate plain text to encrypt

# rule:
timestamp+api_key+recv_window+queryString

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

# resulting string that needs to be signed:
"1658384314791XXXXXXXXXX5000category=option&symbol=BTC-29JUL22-25000-C"

# resulting example signature for HMAC:
"410e0f387bafb7afd0f1722c068515e09945610124fa11774da1da857b72f30b"

HTTP request examples

GET /v5/order/realtime?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'

Common response parameters​

ParameterTypeComments
retCodenumberSuccess/Error code
retMsgstringSuccess/Error msg. OK, success, SUCCESS, "" indicates a successful response
resultObjectBusiness data result
retExtInfoObjectExtend info. Most of the time it is {}
timenumberCurrent timestamp (ms)
{
    "retCode": 0,
    "retMsg": "OK",
    "result": {
    },
    "retExtInfo": {},
    "time": 1671017382656
}