Authentication

Exchange REST API Authentication #

This page explains how to sign and authenticate REST API endpoints with API keys that let you control authorization.

NOTE

See FIX API Connectivity for FIX API authentication.

Private Endpoints #

Private endpoints are available for order management and account management. Every private request must be signed using the described authentication scheme.

INFO

Private endpoints require authentication using your Coinbase Exchange API key. You can generate API keys here.

API Keys #

To sign a request, you must create an API key via the HootDex website. The API key is scoped to a specific profile. Each user can generate a max of 300 API keys.

Generating an API Key #

When creating a key, you must remember and store your:

1. Key
2. Secret
3. Passphrase.

The key and secret are randomly generated and provided by HootDex, you choose a passphrase to further secure your API access.

WARNING

HootDex stores the salted hash of your passphrase for verification purposely only and cannot be recovered if you forget it.

API Key Permissions #

You can control access by restricting the functionality of API keys. Before creating the key, you must choose what permissions you would like the key to have:

Refer to the documentation below to see what API key permissions are required for a specific route.

Signing Requests #

All REST requests must contain the following headers:

All request bodies should have content type application/json and be valid JSON.

Selecting a Timestamp #

The HD-ACCESS-TIMESTAMP header MUST be number of seconds since Unix Epoch in UTC. Decimal values are allowed.

Your timestamp must be within 30 seconds of the API service time or your request is considered expired and rejected. We recommend using the time endpoint to query for the API server time if you believe there is a time difference between your server and the API servers.

Signing a Message #

The HD-ACCESS-SIGN header is generated by creating a sha256 HMAC using the base64-decoded secret key on the prehash string timestamp + method + requestPath + body (where + represents string concatenation) and base64-encode the output.

INFO

Remember to base64-decode the alphanumeric secret string (resulting in 64 bytes) before using it as the key for HMAC. Also, base64-encode the digest output before sending in the header.

• timestamp is the same as the HD-ACCESS-TIMESTAMP header.
• method should be UPPER CASE e.g., GET or POST.
• requestPath should only include the path of the API endpoint.
• body is the request body string or omitted if there is no request body (typically for GET requests).

Signature Example #

The following example demonstrates how to generate a signature in Javascript:

// import crypto library
var crypto = require(‘crypto’);

// create the json request object
var hd_access_timestamp = Date.now() / 1000; // in ms
var hd_access_passphrase = ‘…’;
var secret = ‘HDTFew23xx5…’;
var requestPath = ‘/orders’;
var body = JSON.stringify({
price: ‘2.0’,
size: ‘2.0’,
side: ‘buy’,
product_id: ‘HETH-USD’
});
var method = ‘POST’;

// create the prehash string by concatenating required parts
var message = hd_access_timestamp + method + requestPath + body;

// decode the base64 secret
var key = Buffer.from(secret, ‘base64’);

// create a sha256 hmac with the secret
var hmac = crypto.createHmac(‘sha256’, key);

// sign the require message with the hmac and base64 encode the result
var hd_access_sign = hmac.update(message).digest(‘base64’);