HMAC Signature Guide

Overview

This guide explains the exact HMAC-SHA256 signing contract used by the HopNow Client API.

For the complete authentication overview, see Authentication.

Signing Contract

Every client API request must include these headers:

X-API-Key: your_api_key
X-Timestamp: unix_timestamp
X-Nonce: unique_32_character_hex_nonce
X-Signature: calculated_hmac_signature

The signature is calculated over this payload:

{METHOD}{PATH_AND_QUERY}{TIMESTAMP}{NONCE}{BODY}

Component	Description	Example
`METHOD`	HTTP method in uppercase	`POST`
`PATH_AND_QUERY`	The URL path exactly as sent to HopNow, starting with `/`, followed by `?` and the query string when present. Do not include the scheme, host, port, or fragment.	`/v1/customers/cus_123/accounts?page=1`
`TIMESTAMP`	Unix timestamp as a string	`1640995200`
`NONCE`	Unique random 32-character hex string	`a1b2c3d4e5f678901234567890abcdef`
`BODY`	Exact request body string sent over the wire. Use an empty string for requests without a body.	`{"name":"Trading Account"}`

Use the API key’s secret as the HMAC key. The api_key value goes in the X-API-Key header. Examples:

Request URL	Sign this `PATH_AND_QUERY` value
`https://api.hopnow.io/v1/test`	`/v1/test`
`https://api.hopnow.io/v1/customers/cus_123/accounts?page=1&size=10`	`/v1/customers/cus_123/accounts?page=1&size=10`

Example Payload

For this request:

POST https://api.hopnow.io/v1/customers/cus_123/accounts
Content-Type: application/json

{"name":"Trading Account"}

With:

timestamp = 1640995200
nonce = abcdef0123456789abcdef0123456789

The payload to sign is:

POST/v1/customers/cus_123/accounts1640995200abcdef0123456789abcdef0123456789{"name":"Trading Account"}

Implementation Examples

import hashlib
import hmac
import json
import secrets
import time

import requests


def compact_json(data):
    return json.dumps(data, separators=(",", ":"))


def create_signature(method, path_and_query, timestamp, nonce, body, secret):
    payload = f"{method.upper()}{path_and_query}{timestamp}{nonce}{body}"
    return hmac.new(
        secret.encode("utf-8"),
        payload.encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()


api_key = "your_api_key"
secret = "your_secret"
base_url = "https://api.hopnow.io"
path_and_query = "/v1/customers/cus_123/accounts"
body = compact_json({"name": "Trading Account"})
timestamp = str(int(time.time()))
nonce = secrets.token_hex(16)
signature = create_signature("POST", path_and_query, timestamp, nonce, body, secret)

response = requests.post(
    f"{base_url}{path_and_query}",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": api_key,
        "X-Timestamp": timestamp,
        "X-Nonce": nonce,
        "X-Signature": signature,
    },
    data=body,
)
response.raise_for_status()

const crypto = require('crypto');

function createSignature(method, pathAndQuery, timestamp, nonce, body, secret) {
  const payload = `${method.toUpperCase()}${pathAndQuery}${timestamp}${nonce}${body}`;
  return crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
}

const apiKey = 'your_api_key';
const secret = 'your_secret';
const baseUrl = 'https://api.hopnow.io';
const pathAndQuery = '/v1/customers/cus_123/accounts';
const body = JSON.stringify({ name: 'Trading Account' });
const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce = crypto.randomBytes(16).toString('hex');
const signature = createSignature('POST', pathAndQuery, timestamp, nonce, body, secret);

fetch(`${baseUrl}${pathAndQuery}`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': apiKey,
    'X-Timestamp': timestamp,
    'X-Nonce': nonce,
    'X-Signature': signature,
  },
  body,
});

API_KEY="your_api_key"
SECRET="your_secret"
BASE_URL="https://api.hopnow.io"
METHOD="POST"
PATH_AND_QUERY="/v1/customers/cus_123/accounts"
TIMESTAMP=$(date +%s)
NONCE=$(openssl rand -hex 16)
BODY='{"name":"Trading Account"}'

PAYLOAD="${METHOD}${PATH_AND_QUERY}${TIMESTAMP}${NONCE}${BODY}"
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" -hex | cut -d' ' -f2)

curl -X "$METHOD" "${BASE_URL}${PATH_AND_QUERY}" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIGNATURE" \
  -d "$BODY"

Test Vectors

Use these fixed inputs to validate your local implementation before making API calls.

Test Case 1: POST Request

Input	Value
Method	`POST`
Path and query	`/v1/test`
Timestamp	`1640995200`
Nonce	`a1b2c3d4e5f678901234567890abcdef`
Body	`{"test":true}`
Secret	`test_secret_key_123`

Expected payload:

POST/v1/test1640995200a1b2c3d4e5f678901234567890abcdef{"test":true}

Expected signature:

91d30335d4bfdc5e0801f31de86e34e5ecc557aca551650f42141dd06eeb9953

Test Case 2: GET Request With Query String

Input	Value
Method	`GET`
Path and query	`/v1/customers/cus_123/accounts?page=1&size=10`
Timestamp	`1640995200`
Nonce	`00112233445566778899aabbccddeeff`
Body	empty string
Secret	`test_secret_key_123`

Expected payload:

GET/v1/customers/cus_123/accounts?page=1&size=10164099520000112233445566778899aabbccddeeff

Expected signature:

15decbbdf4fa8f2a26998e95a4c95f75bfa19cab74c8f2c2f08ff6ef191800b4

Common Mistakes

Signing the full URL. Sign /v1/..., not https://api.hopnow.io/v1/....
Omitting X-Nonce or leaving the nonce out of the payload.
Signing a pretty-printed JSON body but sending compact JSON, or vice versa.
Signing query parameters in a different order than the actual request URL.
Reusing a nonce within the 5-minute replay window.
Sending a Bearer token instead of the four HMAC headers.

Troubleshooting Checklist

Log the exact payload before signing.
Confirm the signed path starts with / and includes the query string exactly as sent.
Confirm the timestamp header matches the timestamp in the payload.
Confirm the nonce header matches the nonce in the payload.
Confirm the body string is byte-for-byte the same string sent in the request.
Confirm the HMAC key is the API key secret, not the api_key header value.

Getting Started

Guides

Webhooks

API Reference

Endpoints

HMAC Signature Guide

Overview

Signing Contract

Example Payload

Implementation Examples

Test Vectors

Test Case 1: POST Request

Test Case 2: GET Request With Query String

Common Mistakes

Troubleshooting Checklist

​Overview

​Signing Contract

​Example Payload

​Implementation Examples

​Test Vectors

​Test Case 1: POST Request

​Test Case 2: GET Request With Query String

​Common Mistakes

​Troubleshooting Checklist

Overview

Signing Contract

Example Payload

Implementation Examples

Test Vectors

Test Case 1: POST Request

Test Case 2: GET Request With Query String

Common Mistakes

Troubleshooting Checklist