Create Signed Requests

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}`
    });
}