> For the complete documentation index, see [llms.txt](https://docs.coinflare.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coinflare.com/authentication.md). # Authentication ### General API Information * Some endpoints require you have a valid API-key and secret. You can generate your API key and secret under User Settings. * 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. #### Endpoints | Name (SECURITY TYPE) | Basic Endpoints | | -------------------- | ------------------------------- | | rest-api | **** | | web-socket-streams | **wss\://wsapi.coinflare.com** | | user-data-stream | **wss\://wsapi.coinflare.com** | #### HTTP Error Codes * HTTP `4XX` return codes are used 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 HBTC's side. With using `/wapi/v3` , HTTP `504` return code is used when the API successfully sent the message but not get a response within the timeout period. It is important to **NOT** treat this as a failure operation; the execution status is **UNKNOWN** and could have been a success. * All endpoints can possibly return an ERROR, the error payload is as follows: ```javascript { "code": -1121, "msg": "Invalid symbol." } ``` * Specific error codes and messages defined in another page. #### General Information on endpoints * For `GET`endpoints, parameters must be sent as `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's `REQUEST_WEIGHT` and `ORDER` 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 heavier `weight`. * When a 429 is received, 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. | #### SIGNED(TRADE and USER\_DATA) endpoint security * `SIGNED` endpoints require an additional parameter, `signature`, to be sent in the `query string` or `request body`. * Endpoints use `HMAC SHA256` signatures. The `HMAC SHA256 signature` is a keyed `HMAC SHA256` operation. Use your `secretKey` as the key and `totalParams` as the value for the HMAC operation. * The `signature` is **not case sensitive**. * `totalParams` is defined as the `query string` concatenated with the `request 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 after `timestamp` the request is valid for. If `recvWindow` is not sent, **it defaults to 5000**. * Currently, `recvWindow` is only used when creates order. * The logic is as follows: ```javascript 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`. | Parameter | Value | | ----------- | ------------- | | symbol | ETHBTC | | side | BUY | | type | LIMIT | | timeInForce | GTC | | quantity | 1 | | price | 0.1 | | recvWindow | 5000 | | timestamp | 1538323200000 | | Key | Value | | --------- | ---------------------------------------------------------------- | | apiKey | tAQfOrPIZAhym0qHISRt8EFvxPemdBm5j5WMlkm3Ke9aFp0EGWC2CGM8GHV4kCYW | | secretKey | lH3ELTNiFxCQTmi9pPcWWikhsjO04Yoqw3euoHUuOLC3GYBW64ZqzQsiOEHXQS76 | **Example 1: As a queryString** **queryString:** symbol=ETHBTC\&side=BUY\&type=LIMIT\&timeInForce=GTC\&quantity=1\&price=0.1\&recvWindow=5000×tamp=1538323200000 * **HMAC SHA256 signature:** ```bash [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:** ```bash (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:** ```bash [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:** ```bash (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:** ```bash [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:** ```bash (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".*** --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.coinflare.com/authentication.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.