Private endpoints require a Connection to be provisioned in order to sign a request. To provision a connection, visit the customer portal. The connection allows access to data for all accounts associated with the connection.
All HTTP requests to private API endpoints must contain the following headers:
Header | Description |
---|---|
BTNL-AUTH-TIMESTAMP |
ISO 8601 timestamp. Must be within 30 seconds of API time |
BTNL-CONNECTION-ID |
Hex-encoded ConnectionId |
BTNL-SIGNATURE |
Base64-encoded HMAC-SHA256 signature |
The BTNL-SIGNATURE
header is the base64-encoded signature generated by using HMAC-SHA256 to sign
the concatenated string method + requestPath + queryString + headers + body
using the
ConnectionId
’s hex-encoded AuthToken
as the secret. Each individual string value is described
here:
String | Description |
---|---|
method |
Upper case http method of request. (e.g. GET POST ) |
requestPath |
API endpoint path (e.g. /exchange/api/v1/prod/fills ) |
queryString |
Query string of request, which is not HTML encoded. Expects ? for an empty query string. (e.g. ?order=asc&limit=10 ) |
headers |
BTNL-AUTH-TIMESTAMP<iso8601 timestamp>BTNL-CONNECTION-ID<hex-encoded connectionId> |
body |
Request body string. Empty when the body is empty. |
The timestamp format is not as general as the ISO-8601 specification. The timestamp must be
formatted the following way YYYY-MM-DDTHH:MM:SS.SSSZ
.
For example, the BTNL-SIGNATURE
prehash string to get all fills for ConnectionId
3f
would be:
GET/exchange/api/v1/prod/fills?BTNL-AUTH-TIMESTAMP2023-08-08T17:34:48.348ZBTNL-CONNECTION-ID3f
Note that the queryString
= ?
and body
is an empty string.
The following Javascript code shows how to generate the signature for the above request:
var CryptoJS = require("crypto-js");
var btnlAuthTimestamp = new Date().toISOString();
// connection id hex string
var btnlConnectionId = '3f'
// 64 character auth token hex string
var btnlAuthToken = '01234567890abcdef0123456789abcdef0123456789abcdef0123456789abcde';
var method = 'GET';
var requestPath = '/exchange/api/v1/prod/fills';
var queryString = '?';
var headers = 'BTNL-AUTH-TIMESTAMP' + btnlAuthTimestamp + 'BTNL-CONNECTION-ID' + btnlConnectionId;
var body = '';
var prehashString = method + requestPath + queryString + headers + body;
// base-64 encoded SHA256 HMAC signature
var signature = CryptoJS.enc.Base64.stringify(CryptoJS.HmacSHA256(prehashString, btnlAuthToken));
The valid BTNL-SIGNATURE
for this request is U6NRnV8v0OfCU1Wcq3CSwIqn5yklDVV5nHsEvlegXU0=
An example prehash string to get all fills for ConnectionId
3f
between the times 2024-01-16T20:08:34.000Z
& 2024-02-28T20:08:34.000Z
is:
GET/exchange/api/v1/prod/fills?begin_time=2024-01-16T20:08:34.000Z&end_time=2024-02-28T20:08:34.000ZBTNL-AUTH-TIMESTAMP2024-02-29T18:07:06.745ZBTNL-CONNECTION-ID3f
The valid BTNL-SIGNATURE
for this request is a19KTfskTlZDWSVZcxDJv+r4cR5tzmhUikpCdl0DXEk=