Authentication

Overview

The HopNow API uses HMAC (Hash-based Message Authentication Code) signatures to authenticate requests. This method ensures that:

Requests come from a verified source (authentication)
Request data hasn’t been tampered with (integrity)
Requests can’t be replayed (protection against replay attacks)

All API endpoints require HMAC authentication.

How HMAC Authentication Works

Each API request must include four authentication headers:

Header	Description
`X-API-Key`	The `api_key` value returned when the key is created
`X-Signature`	HMAC-SHA256 signature of the request
`X-Timestamp`	Unix timestamp when the request was created
`X-Nonce`	Unique random token to prevent replay attacks

The API uses only HMAC headers for client API requests. Do not send an Authorization: Bearer header for these endpoints.

Creating the Signature

Use the credential pair returned when you create an API key:

api_key: send this value in the X-API-Key header
secret: use this value as the HMAC-SHA256 signing key

The HMAC signature is created by:

Constructing the payload from request components
Creating an HMAC-SHA256 hash using your API secret
Converting to hexadecimal representation

Signature Payload Format

The payload for signing consists of these components concatenated together:

{HTTP_METHOD}{PATH_AND_QUERY}{TIMESTAMP}{NONCE}{BODY}

Where:

HTTP_METHOD: Uppercase HTTP method (GET, POST, PATCH, DELETE)
PATH_AND_QUERY: The URL path exactly as sent to HopNow, starting with /, followed by ? and the query string when the request has query parameters. Do not include the scheme, host, port, or fragment.
TIMESTAMP: Unix timestamp as a string
NONCE: Unique random token (32 hex characters)
BODY: Exact request body string sent over the wire (empty string for GET requests)

Examples:

Request URL https://api.hopnow.io/v1/customers/cus_abc123/accounts signs /v1/customers/cus_abc123/accounts
Request URL https://api.hopnow.io/v1/customers/cus_abc123/accounts?page=1&size=10 signs /v1/customers/cus_abc123/accounts?page=1&size=10

Step-by-Step Example

Let’s create a signature for this request:

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

{"name":"Trading Account"}

Step 1: Generate timestamp and nonce

import time
import secrets

timestamp = int(time.time())
nonce = secrets.token_hex(16)

Step 2: Construct the payload

POST/v1/customers/cus_abc123/accounts1640995200a1b2c3d4e5f678901234567890abcdef{"name":"Trading Account"}

Step 3: Create HMAC-SHA256 signature

import hmac
import hashlib
import time
import secrets

timestamp = int(time.time())
nonce = secrets.token_hex(16)
secret = "your_secret"
payload = f"POST/v1/customers/cus_abc123/accounts{timestamp}{nonce}" + '{"name":"Trading Account"}'

signature = hmac.new(
    secret.encode('utf-8'),
    payload.encode('utf-8'),
    hashlib.sha256
).hexdigest()

print(signature)

Implementation Examples

Python

import requests
import hmac
import hashlib
import time
import secrets
import json

class HopClient:
    def __init__(self, api_key, secret, base_url="https://api.hopnow.io"):
        self.api_key = api_key
        self.secret = secret
        self.base_url = base_url
    
    def _create_signature(self, method, path_and_query, timestamp, nonce, body=""):
        """Create HMAC signature for request authentication"""
        payload = f"{method.upper()}{path_and_query}{timestamp}{nonce}{body}"
        signature = hmac.new(
            self.secret.encode('utf-8'),
            payload.encode('utf-8'),
            hashlib.sha256
        ).hexdigest()
        return signature
    
    def _make_request(self, method, path_and_query, data=None):
        """Make authenticated request to the API"""
        url = f"{self.base_url}{path_and_query}"
        timestamp = str(int(time.time()))
        nonce = secrets.token_hex(16)
        body = json.dumps(data, separators=(",", ":")) if data else ""
        
        signature = self._create_signature(method, path_and_query, timestamp, nonce, body)
        
        headers = {
            "Content-Type": "application/json",
            "X-API-Key": self.api_key,
            "X-Timestamp": timestamp,
            "X-Nonce": nonce,
            "X-Signature": signature,
        }
        
        response = requests.request(method, url, headers=headers, data=body)
        response.raise_for_status()
        return response.json()
    
    def create_account(self, customer_id, name):
        """Create a new account"""
        return self._make_request(
            "POST",
            f"/v1/customers/{customer_id}/accounts",
            {"name": name}
        )
    
    def get_accounts(self, customer_id):
        """List customer accounts"""
        return self._make_request(
            "GET", 
            f"/v1/customers/{customer_id}/accounts"
        )

# Usage
client = HopClient("your_api_key", "your_secret")
account = client.create_account("cus_abc123", "My Account")
print(account)

import requests
import hmac
import hashlib
import time
import secrets
import json

# Configuration
API_KEY = "your_api_key"
SECRET = "your_secret"
BASE_URL = "https://api.hopnow.io"

def make_authenticated_request(method, path_and_query, data=None):
    url = f"{BASE_URL}{path_and_query}"
    timestamp = str(int(time.time()))
    nonce = secrets.token_hex(16)
    body = json.dumps(data, separators=(",", ":")) if data else ""
    
    # Create signature
    payload = f"{method.upper()}{path_and_query}{timestamp}{nonce}{body}"
    signature = hmac.new(
        SECRET.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    
    # Make request
    headers = {
        "Content-Type": "application/json",
        "X-API-Key": API_KEY,
        "X-Timestamp": timestamp,
        "X-Nonce": nonce,
        "X-Signature": signature,
    }
    
    response = requests.request(method, url, headers=headers, data=body)
    return response.json()

# Example usage
result = make_authenticated_request(
    "POST",
    "/v1/customers/cus_abc123/accounts",
    {"name": "My Account"}
)
print(result)

JavaScript/Node.js

const crypto = require('crypto');
const axios = require('axios');

class HopClient {
  constructor(apiKey, secret, baseUrl = 'https://api.hopnow.io') {
    this.apiKey = apiKey;
    this.secret = secret;
    this.baseUrl = baseUrl;
  }

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

  generateNonce() {
    return crypto.randomBytes(16).toString('hex');
  }

  async makeRequest(method, pathAndQuery, data = null) {
    const url = `${this.baseUrl}${pathAndQuery}`;
    const timestamp = Math.floor(Date.now() / 1000).toString();
    const nonce = this.generateNonce();
    const body = data ? JSON.stringify(data) : '';
    
    const signature = this.createSignature(method, pathAndQuery, timestamp, nonce, body);
    
    const headers = {
      'Content-Type': 'application/json',
      'X-API-Key': this.apiKey,
      'X-Timestamp': timestamp,
      'X-Nonce': nonce,
      'X-Signature': signature,
    };

    try {
      const response = await axios({
        method,
        url,
        headers,
        data: body || undefined
      });
      return response.data;
    } catch (error) {
      throw new Error(`API request failed: ${error.response?.data?.message || error.message}`);
    }
  }

  async createAccount(customerId, name) {
    return this.makeRequest(
      'POST',
      `/v1/customers/${customerId}/accounts`,
      { name }
    );
  }

  async getAccounts(customerId) {
    return this.makeRequest('GET', `/v1/customers/${customerId}/accounts`);
  }
}

// Usage
const client = new HopClient('your_api_key', 'your_secret');

async function example() {
  try {
    const account = await client.createAccount('cus_abc123', 'My Account');
    console.log('Created account:', account);
  } catch (error) {
    console.error('Error:', error.message);
  }
}

example();

const crypto = require('crypto');
const axios = require('axios');

// Configuration
const API_KEY = 'your_api_key';
const SECRET = 'your_secret';
const BASE_URL = 'https://api.hopnow.io';

async function makeAuthenticatedRequest(method, pathAndQuery, data = null) {
  const url = `${BASE_URL}${pathAndQuery}`;
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const nonce = crypto.randomBytes(16).toString('hex');
  const body = data ? JSON.stringify(data) : '';
  
  // Create signature
  const payload = `${method.toUpperCase()}${pathAndQuery}${timestamp}${nonce}${body}`;
  const signature = crypto
    .createHmac('sha256', SECRET)
    .update(payload)
    .digest('hex');
  
  // Make request
  const response = await axios({
    method,
    url,
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY,
      'X-Timestamp': timestamp,
      'X-Nonce': nonce,
      'X-Signature': signature,
    },
    data: body || undefined
  });
  
  return response.data;
}

// Example usage
makeAuthenticatedRequest(
  'POST',
  '/v1/customers/cus_abc123/accounts',
  { name: 'My Account' }
).then(result => {
  console.log(result);
}).catch(error => {
  console.error('Error:', error.response?.data || error.message);
});

cURL

#!/bin/bash

# Configuration
API_KEY="your_api_key"
SECRET="your_secret"
BASE_URL="https://api.hopnow.io"

# Request details
METHOD="POST"
ENDPOINT="/v1/customers/cus_abc123/accounts"
URL="${BASE_URL}${ENDPOINT}"
TIMESTAMP=$(date +%s)
NONCE=$(openssl rand -hex 16)
BODY='{"name":"My Account"}'

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

# Make request
curl -X "$METHOD" "$URL" \
  -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"

Authentication Headers Reference

X-API-Key

The api_key value returned when you create an API key. This identifies the key used for the request.

X-API-Key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

X-Signature

The HMAC-SHA256 signature of your request, encoded as a lowercase hexadecimal string.

X-Signature: 8f7e1b2c3d4e5f6789abcdef012345678901234567890abcdef1234567890ab

X-Timestamp

Unix timestamp indicating when the request was created. Requests older than 5 minutes are rejected.

X-Timestamp: 1640995200

X-Nonce

Unique random token to prevent replay attacks. Must be 32 hexadecimal characters (16 bytes).

X-Nonce: a1b2c3d4e5f678901234567890abcdef

Security Best Practices

Never expose your API secret: Keep your API secret secure and never include it in client-side code, logs, or version control.

1. Secure Storage

Store API secrets in environment variables or secure key management systems
Never hardcode secrets in your application code
Use different API keys for different environments (development, staging, production)

2. Request Validation

Always generate a new nonce for each request to prevent replay attacks
Ensure nonces are cryptographically random (use secrets.token_hex() in Python or crypto.randomBytes() in Node.js)
Validate timestamps to prevent replay attacks beyond the nonce window
Implement request timeouts to avoid hanging requests
Log authentication failures for security monitoring

3. Error Handling

Don’t expose authentication details in error messages
Implement proper retry logic with exponential backoff
Monitor for unusual authentication patterns

Common Issues and Troubleshooting

Invalid Signature Error

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_signature",
    "message": "The signature is invalid"
  }
}

Common causes:

Incorrect payload construction (ensure format: {METHOD}{PATH_AND_QUERY}{TIMESTAMP}{NONCE}{BODY})
Signing the full URL instead of only the path and query string
Wrong HTTP method case (must be uppercase)
Missing or incorrect timestamp/nonce
Query string ordering or encoding differences between the signed payload and the actual request
Incorrect secret key

Timestamp Too Old Error

{
  "error": {
    "type": "authentication_error",
    "code": "timestamp_too_old",
    "message": "Request timestamp is too old"
  }
}

Solution: Ensure your system clock is synchronized and create fresh timestamps for each request.

Nonce Replay Error

{
  "error": {
    "type": "authentication_error",
    "code": "nonce_replay",
    "message": "Nonce already used"
  }
}

Solution: Generate a new unique nonce for each request. Nonces cannot be reused within the 5-minute window.

Missing Headers Error

{
  "error": {
    "type": "authentication_error",
    "code": "missing_headers", 
    "message": "Required authentication headers are missing"
  }
}

Solution: Ensure all four headers (X-API-Key, X-Signature, X-Timestamp, X-Nonce) are included in every request.

Testing Your Implementation

Use a real GET endpoint to verify your authentication implementation. For example, list one account for a customer you own:

GET https://api.hopnow.io/v1/customers/{customer_id}/accounts?size=1

The signed path for that request is:

/v1/customers/{customer_id}/accounts?size=1

Need help with authentication? Review the examples above or contact support.

Getting Started

Guides

Webhooks

API Reference

Endpoints

Overview

How HMAC Authentication Works

Creating the Signature

Signature Payload Format

Step-by-Step Example

Implementation Examples

Python

JavaScript/Node.js

cURL

Authentication Headers Reference

X-API-Key

X-Signature

X-Timestamp

X-Nonce

Security Best Practices

1. Secure Storage

2. Request Validation

3. Error Handling

Common Issues and Troubleshooting

Invalid Signature Error

Timestamp Too Old Error

Nonce Replay Error

Missing Headers Error

Testing Your Implementation

​Overview

​How HMAC Authentication Works

​Creating the Signature

​Signature Payload Format

​Step-by-Step Example

​Implementation Examples

​Python

​JavaScript/Node.js

​cURL

​Authentication Headers Reference

​X-API-Key

​X-Signature

​X-Timestamp

​X-Nonce

​Security Best Practices

​1. Secure Storage

​2. Request Validation

​3. Error Handling

​Common Issues and Troubleshooting

​Invalid Signature Error

​Timestamp Too Old Error

​Nonce Replay Error

​Missing Headers Error

​Testing Your Implementation

Overview

How HMAC Authentication Works

Creating the Signature

Signature Payload Format

Step-by-Step Example

Implementation Examples

Python

JavaScript/Node.js

cURL

Authentication Headers Reference

X-API-Key

X-Signature

X-Timestamp

X-Nonce

Security Best Practices

1. Secure Storage

2. Request Validation

3. Error Handling

Common Issues and Troubleshooting

Invalid Signature Error

Timestamp Too Old Error

Nonce Replay Error

Missing Headers Error

Testing Your Implementation