Create Signed Requests
Dive into the implementation details of Bitso's HMAC signature.
To authenticate in any of the API endpoints, all of your HTTP requests must be valid JSON objects and include the following three fields in the Authorization header payload:
key
: The API Key that you generated. See the section, Set Up Your Testing Environment.nonce
: An integer that must be unique and increase with each API call. Bitso recommends using a UNIX timestamp.signature
: A Hash-based Message Authentication Code (HMAC). For further details, refer to the next section, Build Your Signature.
Build Your Signature
To generate a signature for an HTTP request, you must create a hash-based message authentication code (HMAC) that uses the hash function SHA-256.
To create an SHA-256 HMAC, use your generated Bitso API Secret as the cryptographic key on the concatenation of:
nonce + HTTP method + request path + JSON payload
Do not include the plus signs, +, in the concatenated string. Hex encode the obtained output.
Important in Signature Creation
Ensure the following is true when creating your signature:
- The nonce value is the same as the value stored in the
nonce
field of the Authorization header.- The request path and JSON payload values are precisely the same as those used in the request.
Authorization Header
Construct the header with the fields described at the beginning of the article as follows:
Auth_Header
: Bitso <key
>:<nonce
>:<signature
>
Examples
The shell script on the left tab below exemplifies a signed HTTP GET request to the /balance/
endpoint. Ensure to replace the values of the variables API_KEY
and API_SECRET
with the ones you generated.
And the right tab exemplifies a pre-request script in JavaScript for the Postman API testing platform that builds the authorization header. Ensure to create the environment variables api-key
and api-secret
and assign them your Bitso credentials.
#!/bin/bash
# requires:
# -httpie: https://github.com/jkbrzt/httpie
URL="https://stage.bitso.com/api/v3/balance/"
#Use your Bitso credentials
API_KEY="vToM******"
API_SECRET="*****197c28f2b782ed5ae**********"
SECS=$(date +%s)
DNONCE=$(expr 1000 '*' "$SECS")
HTTPmethod=GET
JSONPayload=""
RequestPath="/api/v3/balance/"
SIGNATURE=$(echo -n $DNONCE$HTTPmethod$RequestPath$JSONPayload | openssl dgst -binary -sha256 -hmac $API_SECRET | xxd -p -c 256 )
AUTH_HEADER="Bitso $API_KEY:$DNONCE:$SIGNATURE"
http GET $URL Authorization:"$AUTH_HEADER"
const API_KEY = pm.environment.get("api-key");
const API_SECRET = pm.environment.get("api-secret");
signRequest(pm.request, API_KEY, API_SECRET);
function signRequest(request, apiKey, apiSecret) {
const nonce = Date.now();
const method = request.method;
const path = request.url.getPathWithQuery();
const body = request.body.raw || "";
const data = `${nonce}${method}${path}${body}`;
const hash = CryptoJS.HmacSHA256(data, apiSecret);
const signature = CryptoJS.enc.Hex.stringify(hash);
pm.request.headers.add({
key: 'Authorization',
value: `Bitso ${apiKey}:${nonce}:${signature}`
});
}
Updated 26 days ago