Signing requests

As a security measure, requests on the /api/v1/private endpoints need to be signed, both when using HTTP and when using Websocket. To sign a request, you'll need an access key and access secret. Those can be obtained from the API tab on your account settings. Never share these keys with anyone, as they provide full access to your account.

First, you'll need to compute the signature string. The signature string is a series of UTF-8 encoded key-value pairs, with the key and values separated by an equals sign (=), and the pairs separated by ampersands (&). The pairs should be alphabetically sorted. The signature string consists of the following keys:

  • _, the nonce, the current timestamp in ms.
  • _ackey, your access key
  • _acsec, your secret key
  • _action, the full path of the API call, e.g. /api/v1/private/buy
  • All of the arguments to your call, in alphabetical order.

A few of the value types require special attention:

  • Array values are concatenated. e.g. ["test", "value"] would be replaced by testvalue in the signature string
  • Boolean values are true or false, all lower case
  • Float values need to have the exact same notation as in the actual encoded parameter (same number of digits, same rounding). In some programming languages this can be hard to achieve. In those cases, it is best to first convert the float to a string, and use that as a parameter.

For example: a request to buy some future could yield the following signature string. Note how the arguments are sorted alphabetically. In this example, line feeds added for readability. Line feeds are not used in the actual signature string.

_=1452237485895&
_ackey=2YZn85siaUf5A&
_acsec=BTMSIAJ8IYQTAV4MLN88UAHLIUNYZ3HN&
_action=/api/v1/private/buy&
instrument=BTC-15JAN16&
price=500&
quantity=1

Once you have generated the signature string, it is time to generate the signature hash. The signature hash is the base64 encoded SHA256 hash of the signature string. Once you've obtained the signature string, you can use it to form the signature. The signature consists of three parts, separated by . (period): your access key, the nonce, and the signature hash. It is important that both the access key and the nonce are the same as the ones used in the signature string. For example, the example above would generate the following signature: 2YZn85siaUf5A.1452237485895.LQctRklxPiJDHJj9ZYp78Epilx7N78crGghzr1pvNlI=.

When using RPC over HTTP, the signature is added as a X-Deribit-Sig header. When using Websocket, the signature is transmitted in the sig field.

JavaScript code example:

let access_key = '2YZn85siaUf5A';
let secret_key = 'BTMSIAJ8IYQTAV4MLN88UAHLIUNYZ3HN';

function get_signature(action, arguments) {
    let nonce = (new Date()).getTime().toString();

    let signatureString = 
        '_=' + nonce 
        + '&_ackey=' + access_key
        + '&_acsec=' + secret_key
        + '&_action=' + action;

    Object.keys(arguments).sort().forEach((key) => {
        signatureString += "&";
        signatureString += key;
        signatureString += "=";

        let value = arguments[key];
        if (Array.isArray(value)) {
            value = value.join('');
        }

        signatureString += value.toString();
    });

    let signatureStringEncoded = new TextEncoder("utf-8").encode(signatureString);
    let binaryHash = crypto.subtle.digest("SHA-256", signatureStringEncoded);
    return (
        access_key + "." + 
        nonce.toString() + "." +  
        btoa(binaryHash)
    )
}

Python code example:

import hashlib, time, base64

access_key = '2YZn85siaUf5A';
secret_key = 'BTMSIAJ8IYQTAV4MLN88UAHLIUNYZ3HN';

def get_signature(action, arguments):
    nonce = str(int(time.time() * 1000))

    signature_string = '_=%s&_ackey=%s&_acsec=%s&_action=%s' % (
        nonce, access_key, secret_key, action
    )

    for key, value in sorted(arguments.items()):
        if isinstance(value, list):
            value = "".join(str(v) for v in value)
        else:
            value = str(v)

        signature_string += "&%s=%s" % (key, value)

    sha256 = hashlib.sha256()
    sha256.update(signature_string.encode("utf-8"))
    signature_hash = base64.b64encode(sha256.digest()).decode()

    return "%s.%s.%s" % (access_key, nonce, signature_hash)
}

results matching ""

    No results matching ""