Introduction
Bybit V3 Open API allow users to select different collections to build their API model.
- Derivatives - unified margin: You could trade USDT Perpetual, USDC Perpetual, USDC Option with
unified/v3
endpoints. - Derivatives - contract: You could trade USDT Perpetual, Inverse Perpetual, Inverse Future with
contract/v3
endpoints. - Spot: You could trade Spot with
spot/v3
endpoints. - Copy Trade: You must be Principle Trader to use this API.
- Account Asset: Containing transfer, withdraw and Api Key operation, etc.
- Tax: You can get tax report via these endpoints
Authentication
REST API Base Endpoint:
- Testnet:
https://api-testnet.bybit.com - Mainnet(both endpoints are available):
https://api.bybit.com
https://api.bytick.com
- All requests made to private endpoints MUST be authenticated.
- Requests made to public endpoints DO NOT require additional authentication.
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 keyX-BAPI-TIMESTAMP
- UTC timestamp in millisecondsX-BAPI-SIGN
- a signature derived from the request's parameters
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
.
Please make sure that the timestamp parameter adheres to the following rule:
server_time - recv_window <= timestamp < server_time + 1000
server_time stands for Bybit server time, which can be queried via the Server Time endpoint.
Create A Request
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.
Example signature algorithms can be found here
Basic steps:
- timestamp + api-key + (recv_window) + (queryString | jsonBodyString)
- 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.
- 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
- POST
# 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"
# 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
- http-post
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'
POST /unified/v3/private/order/cancel-all HTTP/1.1
Host: api-testnet.bybit.com
-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
}