Exchange HTTP API Authentication • Bitnomial Documentation

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.

Signing Requests

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

Signing A Request

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.

Timestamp Formatting

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.

Example Prehash String

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.

Example Signature

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=

Example Signature With Time Parameters

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=