Authentication

All API requests are made against the Bitnob base URL https://api.bitnob.com and authenticated using HMAC signature.

Auth Modes

All API requests must be authenticated using HMAC Signature. Both your CLIENT_ID and CLIENT_SECRET are required.

HMAC Signature — Each request is signed with a timestamp and nonce, making it tamper-proof and resistant to replay attacks.

mode	headers required
HMAC Signature	X-Auth-Client, X-Auth-Signature, X-Auth-Timestamp, X-Auth-Nonce

This guide explains how to sign HTTP requests using HMAC-SHA256. Examples are shown in JavaScript (Node.js crypto module), Go, and Python.

Node.js with the built-in crypto module. Environment variables set:

CLIENT_IDstring

Your Bitnob Client ID used to authenticate API requests. This is provided by Bitnob when you create an app.

CLIENT_SECRETstring

Your Bitnob Secret Key used for signing API requests. Keep this key secure and do not expose it in frontend code.

Set Environment Variables

This authentication flow ensures each request is fresh, tamper-proof, and uniquely identifiable.

Nonce A 16-byte cryptographically-random value, hex-encoded. Guarantees each request is one-off and thwarts replay attacks.

Timestamp The current Unix timestamp in seconds (e.g. 1719236465). Ensures you can reject stale requests.

Concatenate the following fields in exactly this order, separated by colons:

CLIENT_ID:TIMESTAMP:NONCE:PAYLOAD

Payload should be the exact JSON payload you're sending—without extra whitespace or line breaks. If no body, use an empty string.

Use HMAC-SHA256 over the string to sign, keyed with your shared CLIENT_SECRET.

Encode the raw binary HMAC output in hexadecimal.

Example pseudo-code:

Pseudo-code

Include all four custom headers on every API request:

header	value	purpose
X-Auth-Client	Your CLIENT_ID	Identifies who is calling the API
X-Auth-Timestamp	Unix timestamp in seconds	Prevents replay of old requests
X-Auth-Nonce	16-byte hex-encoded nonce	Adds per-request uniqueness
X-Auth-Signature	The hex-encoded HMAC	Verifies integrity & authenticity

Tip: Always validate on the server that:

The timestamp is within an acceptable window (e.g. ±5 minutes).

The nonce hasn't been used before (store recent nonces for de-duplication).

The computed signature matches the one provided.

By following these steps exactly, you ensure your API is resilient against replay, tampering, and impersonation.

Auth