Authentication

Every request is signed with HMAC-SHA256. Your credentials are a pair: an API key, sent on every request, and an API secret, which signs the request and is never transmitted. Authorization: Bearer is not accepted.

Credentials

Credential	Format	Sent
API key	64 lowercase hex characters	On every request, in `X-API-Key`
API secret	86 URL-safe characters	Never. It keys the signature.

The ak_… id on created_by and updated_by identifies the API key record, not the key value.

Access requirements

Your organization’s KYC must be approved before any endpoint will serve data. Until it is, calls return 403 with code KYC_NOT_APPROVED and details.kyc_status carrying the current state.

Scopes

Each API key carries a set of scopes, each at read or write. Write implies read. A call outside your key’s scopes returns 403 ACCESS_DENIED. Use these five scope names when creating a key or updating its scopes:

Scope	Grants access to
`accounts`	Accounts, account identity, associated persons, balances, deposit instructions and wallets
`payments`	Payouts, payins, transfers, beneficiaries and payout destinations
`fx`	Quotes and trades
`virtual_accounts`	Virtual accounts, virtual account groups, their agreements and documents
`webhooks`	Webhook endpoint management

Endpoint pages name the scope each one needs. Each scope covers every resource in its row, so a payout integration needs payments at write. Keys may also carry an IP allowlist, in which case a request from any other address returns 403. Scopes are set when the key is issued and cannot be changed through the API.

Required headers

string

required

The API key value.

string

required

Unix epoch seconds, within 300 seconds of server time.

string

required

A value unique to this request; a UUID is the usual choice. A nonce cannot be reused for 300 seconds.

string

required

Lowercase hex HMAC-SHA256 of the signature string, keyed with your API secret.

Signature string

Concatenate five parts with no separators:

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

Part	Value
`METHOD`	Uppercase HTTP method
`PATH_AND_QUERY`	The path as sent, starting with `/`, plus `?` and the raw query string when there is one. No scheme or host: for `https://api.hopnow.io/v1/customers/cus_9f2a…/accounts?size=1`, sign `/v1/customers/cus_9f2a…/accounts?size=1`
`TIMESTAMP`	The value sent in `X-Timestamp`
`NONCE`	The value sent in `X-Nonce`
`BODY`	The request body exactly as transmitted; empty string when there is none

Sign the bytes you send: serialise the body once and use that same string for the signature and the request, and keep the query parameters in the order you send them. Idempotency-Key and X-Request-ID are not part of the signature string.

Building a signed request

import hashlib
import hmac
import json
import time
import uuid

import httpx

API_KEY = "<your api key>"
API_SECRET = "<your api secret>"
BASE_URL = "https://api.sbx.hopnow.io"

def signed_request(method, path_and_query, body_obj=None, extra_headers=None):
    body = json.dumps(body_obj, separators=(",", ":")) if body_obj is not None else ""
    timestamp = str(int(time.time()))
    nonce = str(uuid.uuid4())

    payload = f"{method.upper()}{path_and_query}{timestamp}{nonce}{body}"
    signature = hmac.new(
        API_SECRET.encode(), payload.encode(), hashlib.sha256
    ).hexdigest()

    headers = {
        "X-API-Key": API_KEY,
        "X-Timestamp": timestamp,
        "X-Nonce": nonce,
        "X-Signature": signature,
        "Content-Type": "application/json",
        **(extra_headers or {}),
    }

    return httpx.request(
        method, BASE_URL + path_and_query, content=body or None, headers=headers
    )

import { createHmac, randomUUID } from 'node:crypto';

const API_KEY = '<your api key>';
const API_SECRET = '<your api secret>';
const BASE_URL = 'https://api.sbx.hopnow.io';

export async function signedRequest(method, pathAndQuery, bodyObj, extraHeaders = {}) {
  const body = bodyObj === undefined ? '' : JSON.stringify(bodyObj);
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const nonce = randomUUID();

  const payload = `${method.toUpperCase()}${pathAndQuery}${timestamp}${nonce}${body}`;
  const signature = createHmac('sha256', API_SECRET).update(payload).digest('hex');

  return fetch(BASE_URL + pathAndQuery, {
    method,
    body: body || undefined,
    headers: {
      'X-API-Key': API_KEY,
      'X-Timestamp': timestamp,
      'X-Nonce': nonce,
      'X-Signature': signature,
      'Content-Type': 'application/json',
      ...extraHeaders,
    },
  });
}

#!/usr/bin/env bash
BASE_URL="https://api.sbx.hopnow.io"
API_KEY="<your api key>"
API_SECRET="<your api secret>"

METHOD="GET"
PATH_AND_QUERY="/v1/customers/cus_9f2a7c1e6a2b4f3c9b8d2e5a/accounts?size=1"
TIMESTAMP="$(date +%s)"
NONCE="$(uuidgen | tr '[:upper:]' '[:lower:]')"
BODY=""

SIGNATURE="$(printf '%s' "${METHOD}${PATH_AND_QUERY}${TIMESTAMP}${NONCE}${BODY}" \
  | openssl dgst -sha256 -hmac "$API_SECRET" \
  | awk '{print $NF}')"

curl -sS "${BASE_URL}${PATH_AND_QUERY}" \
  -H "X-API-Key: ${API_KEY}" \
  -H "X-Timestamp: ${TIMESTAMP}" \
  -H "X-Nonce: ${NONCE}" \
  -H "X-Signature: ${SIGNATURE}"

Test vectors

Check your signing implementation against these fixed inputs. Both use the secret test_secret_key_123. These are offline checks: the timestamps are fixed and are not valid for a live request.

POST with a body

{
  "method": "POST",
  "path_and_query": "/v1/test",
  "timestamp": "1640995200",
  "nonce": "a1b2c3d4e5f678901234567890abcdef",
  "body": "{\"test\":true}",
  "expected_signature": "91d30335d4bfdc5e0801f31de86e34e5ecc557aca551650f42141dd06eeb9953"
}

GET with a query string

{
  "method": "GET",
  "path_and_query": "/v1/customers/cus_123/accounts?page=1&size=10",
  "timestamp": "1640995200",
  "nonce": "00112233445566778899aabbccddeeff",
  "body": "",
  "expected_signature": "15decbbdf4fa8f2a26998e95a4c95f75bfa19cab74c8f2c2f08ff6ef191800b4"
}

When authentication fails

Every failure returns the standard error envelope.

Status	`code`	Cause
`401`	`UNAUTHORIZED`	A header is missing, `X-Timestamp` is not an integer or is more than 300 seconds from server time, the nonce was used in the last 300 seconds, the key is unknown or expired, or the signature does not match.
`403`	`ACCESS_DENIED`	The request came from an IP outside the key’s allowlist, or the key’s scopes do not cover this endpoint.
`403`	`KYC_NOT_APPROVED`	Your organization’s KYC is not approved. `details.kyc_status` carries the current state.
`503`	`SERVICE_UNAVAILABLE`	Authentication could not be completed. Retry.

A nonce is consumed before the signature is checked, so a request that failed on its signature cannot be retried with the same nonce. Generate a fresh nonce and timestamp for every attempt.

Getting started

API basics

Endpoints

Webhooks

Credentials

Access requirements

Scopes

Required headers

Signature string

Building a signed request

Test vectors

When authentication fails

​Credentials

​Access requirements

​Scopes

​Required headers

​Signature string

​Building a signed request

​Test vectors

​When authentication fails

Credentials

Access requirements

Scopes

Required headers

Signature string

Building a signed request

Test vectors

When authentication fails