Introduction
Introduction
The BitVenus API allows users to access real-time and historical data for spot and contract markets. This document outlines the available endpoints, required parameters, and expected responses for each API call.
All API calls require an API key and secret to be included in the request header. Please see the BitVenus website for instructions on obtaining an API key.
General API Information
- All endpoints return either a JSON object or array.
- Data is returned in ascending order. Oldest first, newest last.
- All time and timestamp related fields are in milliseconds.
- HTTP 4XX return codes are used for for malformed requests; the issue is on the sender's side.
- HTTP 429 return code is used when breaking a request rate limit.
- HTTP 418 return code is used when an IP has been auto-banned for continuing to send requests after receiving 429 codes.
- HTTP 5XX return codes are used for internal errors; the issue is on broker's side. It is important to NOT treat this as a failure operation; the execution status is UNKNOWN and could have been a success.
- Any endpoint can return an ERROR; the error payload is as follows:
{
"code": -1121,
"msg": "Invalid symbol."
}
- Specific error codes and messages defined in another document.
- For GET endpoints, parameters must be sent as a query string.
- For POST, PUT, and DELETE endpoints, the parameters may be sent as a query string or in the request body with content type application/x-www-form-urlencoded. You may mix parameters between both the query string and request body if you wish to do so.
- Parameters may be sent in any order.
- If a parameter sent in both the query string and request body, the query string parameter will be used.
LIMITS
The
/openapi/v1/brokerInfo
rateLimits
array contains objects related to the broker'sREQUEST_WEIGHT
andORDER
rate limits.A 429 will be returned when either rate limit is violated.
Each route has a
weight
which determines for the number of requests each endpoint counts for. Heavier endpoints and endpoints that do operations on multiple symbols will have a heavierweight
.When a 429 is recieved, it's your obligation as an API to back off and not spam the API.
Repeatedly violating rate limits and/or failing to back off after receiving 429s will result in an automated IP ban (http status 418).
IP bans are tracked and scale in duration for repeat offenders, from 2 minutes to 3 days.
Endpoint security type
- Each endpoint has a security type that determines the how you will interact with it.
- API-keys are passed into the Rest API via the
X-BH-APIKEY
header. - API-keys and secret-keys are case sensitive.
- API-keys can be configured to only access certain types of secure endpoints. For example, one API-key could be used for TRADE only, while another API-key can access everything except for TRADE routes.
- By default, API-keys can access all secure routes.
Security Type | Description |
---|---|
NONE | Endpoint can be accessed freely. |
TRADE | Endpoint requires sending a valid API-Key and signature. |
USER_DATA | Endpoint requires sending a valid API-Key and signature. |
USER_STREAM | Endpoint requires sending a valid API-Key. |
MARKET_DATA | Endpoint requires sending a valid API-Key. |
TRADE
andUSER_DATA
endpoints areSIGNED
endpoints.
SIGNED (TRADE and USER_DATA) Endpoint security
SIGNED
endpoints require an additional parameter,signature
, to be sent in thequery string
orrequest body
.- Endpoints use
HMAC SHA256
signatures. TheHMAC SHA256 signature
is a keyedHMAC SHA256
operation. Use yoursecretKey
as the key andtotalParams
as the value for the HMAC operation. - The
signature
is not case sensitive. totalParams
is defined as thequery string
concatenated with therequest body
.
Timing security
A
SIGNED
endpoint also requires a parameter,timestamp
, to be sent which should be the millisecond timestamp of when the request was created and sent.An additional parameter,
recvWindow
, may be sent to specify the number of milliseconds aftertimestamp
the request is valid for. IfrecvWindow
is not sent, it defaults to 5000.Currently,
recvWindow
is only used when creates order.The logic is as follows:
if (timestamp < (serverTime + 1000) && (serverTime - timestamp) <= recvWindow) {
// process request
} else {
// reject request
}
Serious trading is about timing. Networks can be unstable and unreliable, which can lead to requests taking varying amounts of time to reach the servers. With recvWindow
, you can specify that the request must be processed within a certain number of milliseconds or be rejected by the server.
It recommended to use a small recvWindow of 5000 or less!
SIGNED Endpoint Examples for POST /openapi/v1/order
Here is a step-by-step example of how to send a vaild signed payload from the Linux command line using echo
, openssl
, and curl
.
Key | Value |
---|---|
apiKey | tAQfOrPIZAhym0qHISRt8EFvxPemdBm5j5WMlkm3Ke9aFp0EGWC2CGM8GHV4kCYW |
secretKey | lH3ELTNiFxCQTmi9pPcWWikhsjO04Yoqw3euoHUuOLC3GYBW64ZqzQsiOEHXQS76 |
Parameter | Value |
---|---|
symbol | ETHBTC |
side | BUY |
type | LIMIT |
timeInForce | GTC |
quantity | 1 |
price | 0.1 |
recvWindow | 5000 |
timestamp | 1538323200000 |
Example 1: As a query string
- queryString: symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000×tamp=1538323200000
- HMAC SHA256 signature:
[linux]$ echo -n "symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000×tamp=1538323200000" | openssl dgst -sha256 -hmac "lH3ELTNiFxCQTmi9pPcWWikhsjO04Yoqw3euoHUuOLC3GYBW64ZqzQsiOEHXQS76"
(stdin)= 5f2750ad7589d1d40757a55342e621a44037dad23b5128cc70e18ec1d1c3f4c6
- curl command:
(HMAC SHA256)
[linux]$ curl -H "X-BH-APIKEY: tAQfOrPIZAhym0qHISRt8EFvxPemdBm5j5WMlkm3Ke9aFp0EGWC2CGM8GHV4kCYW" -X POST 'https://$HOST/openapi/v1/order?symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000×tamp=1538323200000&signature=5f2750ad7589d1d40757a55342e621a44037dad23b5128cc70e18ec1d1c3f4c6'
Example 2: As a request body
- requestBody: symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000×tamp=1538323200000
- HMAC SHA256 signature:
[linux]$ echo -n "symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000×tamp=1538323200000" | openssl dgst -sha256 -hmac "lH3ELTNiFxCQTmi9pPcWWikhsjO04Yoqw3euoHUuOLC3GYBW64ZqzQsiOEHXQS76"
(stdin)= 5f2750ad7589d1d40757a55342e621a44037dad23b5128cc70e18ec1d1c3f4c6
- curl command:
(HMAC SHA256)
[linux]$ curl -H "X-BH-APIKEY: tAQfOrPIZAhym0qHISRt8EFvxPemdBm5j5WMlkm3Ke9aFp0EGWC2CGM8GHV4kCYW" -X POST 'https://$HOST/openapi/v1/order' -d 'symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000×tamp=1538323200000&signature=5f2750ad7589d1d40757a55342e621a44037dad23b5128cc70e18ec1d1c3f4c6'
Example 3: Mixed query string and request body
- queryString: symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC
- requestBody: quantity=1&price=0.1&recvWindow=5000×tamp=1538323200000
- HMAC SHA256 signature:
[linux]$ echo -n "symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTCquantity=1&price=0.1&recvWindow=5000×tamp=1538323200000" | openssl dgst -sha256 -hmac "lH3ELTNiFxCQTmi9pPcWWikhsjO04Yoqw3euoHUuOLC3GYBW64ZqzQsiOEHXQS76"
(stdin)= 885c9e3dd89ccd13408b25e6d54c2330703759d7494bea6dd5a3d1fd16ba3afa
- curl command:
(HMAC SHA256)
[linux]$ curl -H "X-BH-APIKEY: tAQfOrPIZAhym0qHISRt8EFvxPemdBm5j5WMlkm3Ke9aFp0EGWC2CGM8GHV4kCYW" -X POST 'https://$HOST/openapi/v1/order?symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC' -d 'quantity=1&price=0.1&recvWindow=5000×tamp=1538323200000&signature=885c9e3dd89ccd13408b25e6d54c2330703759d7494bea6dd5a3d1fd16ba3afa'
Note that the signature is different in example 3. There is no & between "GTC" and "quantity=1".
Terminology
base asset
refers to the asset that is thequantity
of a symbol.quote asset
refers to the asset that is theprice
of a symbol.
ENUM definitions
Symbol status:
- TRADING
- HALT
- BREAK
Symbol type:
- SPOT
Asset type:
- CASH
- MARGIN
Order status:
- NEW
- PARTIALLY_FILLED
- FILLED
- CANCELED
- PENDING_CANCEL
- REJECTED
Order types:
- LIMIT
- MARKET
- LIMIT_MAKER
- STOP_LOSS (unavailable now)
- STOP_LOSS_LIMIT (unavailable now)
- TAKE_PROFIT (unavailable now)
- TAKE_PROFIT_LIMIT (unavailable now)
- MARKET_OF_PAYOUT (unavailable now)
Order side:
- BUY
- SELL
Time in force:
- GTC
- IOC
- FOK
Kline/Candlestick chart intervals:
m -> minutes; h -> hours; d -> days; w -> weeks; M -> months
- 1m
- 3m
- 5m
- 15m
- 30m
- 1h
- 2h
- 4h
- 6h
- 8h
- 12h
- 1d
- 3d
- 1w
- 1M
Rate limiters (rateLimitType)
- REQUESTS_WEIGHT
- ORDERS
Rate limit intervals
- SECOND
- MINUTE
- DAY
Api Endpoints
Name | base endpoint |
---|---|
rest-api | https://www.bitvenus.me/openapi/ |
web-socket-streams | wss://wsapi.bitvenus.me |
Remarks
When using our API, please ensure that you adhere to the following guidelines:
- Carefully read and comply with our terms of service and privacy policy.
- Do not attempt to modify, copy, tamper with, crack, damage, or attempt to obtain any part of the source code or any other related information of our API without authorization.
- Ensure that your application complies with applicable laws, regulations, and industry standards and is not used for any illegal purposes.
- Ensure that your application can effectively handle and process all responses and error codes provided by us when using the API.
- If you have any questions or concerns, please contact us through our support email, and we will be happy to assist you.
- Please Description that we reserve the right to update and change these guidelines at any time. If you violate these guidelines, we may suspend or terminate your permission to use the API and reserve the right to take further legal action.
Thank you for using our API, and we look forward to your success in developing applications!