Skip to content

Authentication ​

All currently published BITXpay Merchant APIs (Payments and Subscriptions) use a single authentication method:

  1. Signature Authentication (Ed25519 / EdDSA) - For merchant-facing APIs (Payment Links, etc.)

Planned: HMAC-SHA256

A second scheme, HMAC-SHA256, is planned for a future set of standard (non-merchant) APIs. It has no live endpoints today and is not part of the current contract. It will be documented here once it ships.


Signature Authentication (Merchant APIs) ​

Merchant-facing APIs authenticate requests with an asymmetric signature over a canonical message. The current primitive is Ed25519 (EdDSA); RSA-PSS with SHA-256 is also accepted for legacy keys issued before Ed25519 was adopted.

Ed25519 vs legacy RSA-PSS

New merchant keys are Ed25519. Ed25519 is deterministic (no per-signature random nonce), produces a fixed 64-byte signature, and hashes the message internally with SHA-512 — you do not pre-hash the message. If your account was provisioned with an older RSA key, sign with RSA-PSS + SHA-256 instead; the request headers and message format are identical.

Required Headers ​

HeaderDescription
X-API-KeyYour merchant API key, e.g. btxm_9b451fa04a2e
X-API-SignatureSignature of the canonical message, base64-encoded (raw 64-byte Ed25519 signature, or RSA-PSS signature for legacy keys)
X-API-TimestampRFC 3339 / ISO 8601 timestamp in UTC (e.g., 2026-01-31T17:53:56Z). Fractional seconds are accepted.
Content-Typeapplication/json (requests with a body)
Alternative: Authorization: Bearer

The API key may also be sent as Authorization: Bearer btxm_… instead of X-API-Key. X-API-Key takes precedence when both are present. The signature and timestamp headers are still required.

Obtaining Your Keys ​

  1. Log in to your BITXpay Dashboard
  2. Navigate to Developers → API Keys
  3. Generate your Merchant API Key and Private Key
  4. Store both securely - the private key is shown only once

Your credentials will include:

CredentialFormatExample
API Key (public identifier)btxm_ + 12 hex charactersbtxm_9b451fa04a2e
Private Key (keep secret)Ed25519: + base64 of the PKCS#8 DER keyEd25519:MC4CAQAwBQYDK2VwBCIEI…
Public Key (for your records)Ed25519: + base64 of the SubjectPublicKeyInfo DER keyEd25519:MCowBQYDK2VwAyEA…

Legacy accounts have an RSA key pair in PEM format instead (-----BEGIN PRIVATE KEY-----).

The private key is not PEM

The issued private key is the Ed25519:<base64> string above, not a PEM file. Decode the base64 part and load it as a PKCS#8 DER key (see the examples below), or wrap it in -----BEGIN PRIVATE KEY----- / -----END PRIVATE KEY----- lines (base64 lines of 64 characters) if your library only accepts PEM. Both encode the same key.

Keys are bound to an environment

The API key looks the same in sandbox and production (btxm_…). A key created in the sandbox dashboard only authenticates against https://sandboxapi.bitxpay.com/api/v1; a key created in the production dashboard only against https://api.bitxpay.com/api/v1. Using a key against the other environment fails with INVALID_API_KEY.

Generating the Signature ​

The signature is created by signing the canonical message with your private key:

Message Format:

METHOD + PATH + TIMESTAMP + BODY
PartValue
METHODUpper-case HTTP method, e.g. POST
PATHThe full request path including the /api/v1 prefix, without host or query string, e.g. /api/v1/payment_links
TIMESTAMPThe exact string sent in X-API-Timestamp
BODYThe exact raw request body string sent on the wire (empty string for requests without a body)

There are no separators between the parts.

Example Message:

POST/api/v1/payment_links2026-01-31T17:53:56Z{"amount":100.50,"currency":"USDT","payment_name":"Invoice #12345"}

Sign the full path

The server verifies the signature against the path it received, which includes /api/v1. Signing /payment_links while calling https://sandboxapi.bitxpay.com/api/v1/payment_links fails with SIGNATURE_VERIFICATION_FAILED. Query strings (?page=1) are not part of the signed path. A trailing slash is part of the path: sign /api/v1/payment_links/ if that is the URL you call.

Body must match byte-for-byte

Sign the exact string you send. Serialise the JSON once, sign that string, and send that same string. Do not let your HTTP client re-serialise the object (for example use data=body rather than json=body in Python requests).

Signature Parameters (Ed25519 — default):

  • Algorithm: Ed25519 (EdDSA)
  • Hashing: performed internally by Ed25519 (SHA-512) — do not pre-hash the message
  • Signature size: 64 bytes (fixed)
  • Output Format: raw signature bytes, base64-encoded for transmission

Legacy RSA-PSS keys:

  • Algorithm: RSA-PSS
  • Hash Function: SHA-256 (also used for the MGF1 mask)
  • Salt length: equal to the digest length (32 bytes)
  • Key Size: 2048 bits (minimum)
  • Output Format: raw signature bytes, base64-encoded for transmission

Important Security Notes:

  • Ed25519 signing is deterministic — there is no per-signature random nonce to manage, which removes the nonce-reuse key-leak risk of DSA/ECDSA.
  • Keep your private key secret and never ship it in client-side code.
  • Include a fresh X-API-Timestamp on every request (see Timestamp Validation).

Node.js Example ​

These examples load the dashboard-issued key and sign the exact request bytes.

javascript
import crypto from 'crypto';

// Load the private key exactly as the dashboard issued it:
//   "Ed25519:<base64 PKCS#8 DER>"  (current keys)
//   "-----BEGIN PRIVATE KEY-----"  (legacy RSA keys, PEM)
function loadPrivateKey(raw) {
  raw = raw.trim();
  if (raw.startsWith('Ed25519:')) {
    return crypto.createPrivateKey({
      key: Buffer.from(raw.slice('Ed25519:'.length), 'base64'),
      format: 'der',
      type: 'pkcs8',
    });
  }
  return crypto.createPrivateKey(raw);
}

// message = METHOD + PATH + TIMESTAMP + BODY  (no separators)
// PATH is the full request path, including the /api/v1 prefix.
function sign(privateKey, method, path, timestamp, body = '') {
  const message = `${method}${path}${timestamp}${body}`;
  if (privateKey.asymmetricKeyType === 'ed25519') {
    // Ed25519 hashes internally: algorithm must be null, do not pre-hash.
    return crypto.sign(null, Buffer.from(message, 'utf8'), privateKey).toString('base64');
  }
  // Legacy RSA keys: RSA-PSS with SHA-256, salt length = digest length.
  return crypto
    .sign('sha256', Buffer.from(message, 'utf8'), {
      key: privateKey,
      padding: crypto.constants.RSA_PKCS1_PSS_PADDING,
      saltLength: crypto.constants.RSA_PSS_SALTLEN_DIGEST,
    })
    .toString('base64');
}

// Usage
const apiKey = process.env.MERCHANT_API_KEY;               // btxm_xxxxxxxxxxxx
const privateKey = loadPrivateKey(process.env.MERCHANT_PRIVATE_KEY); // Ed25519:MC4CAQAw...

const host = 'https://sandboxapi.bitxpay.com';
const path = '/api/v1/payment_links';                       // sign the FULL path
const method = 'POST';
const timestamp = new Date().toISOString();                 // RFC 3339, UTC
const body = JSON.stringify({
  payment_name: 'Invoice #12345',
  amount: 100.5,
  currency: 'USDT',
  customer_email: 'john@example.com',
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
});

const signature = sign(privateKey, method, path, timestamp, body);

const response = await fetch(host + path, {
  method,
  headers: {
    'X-API-Key': apiKey,
    'X-API-Signature': signature,
    'X-API-Timestamp': timestamp,
    'Content-Type': 'application/json',
  },
  body, // send the exact string that was signed
});
console.log(response.status, await response.json());

Python Example ​

python
import base64
import json
import os
from datetime import datetime, timezone

import requests
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import ed25519, padding


def load_private_key(raw: str):
    """Load the key exactly as the dashboard issued it.

    "Ed25519:<base64 PKCS#8 DER>"   current keys
    "-----BEGIN PRIVATE KEY-----"   legacy RSA keys (PEM)
    """
    raw = raw.strip()
    if raw.startswith("Ed25519:"):
        der = base64.b64decode(raw[len("Ed25519:"):])
        return serialization.load_der_private_key(der, password=None)
    return serialization.load_pem_private_key(raw.encode(), password=None)


def sign(private_key, method: str, path: str, timestamp: str, body: str = "") -> str:
    # message = METHOD + PATH + TIMESTAMP + BODY (no separators)
    # PATH is the full request path, including the /api/v1 prefix.
    message = f"{method}{path}{timestamp}{body}".encode("utf-8")
    if isinstance(private_key, ed25519.Ed25519PrivateKey):
        signature = private_key.sign(message)  # Ed25519 hashes internally; do not pre-hash
    else:  # legacy RSA keys: RSA-PSS + SHA-256
        signature = private_key.sign(
            message,
            padding.PSS(mgf=padding.MGF1(hashes.SHA256()), salt_length=padding.PSS.DIGEST_LENGTH),
            hashes.SHA256(),
        )
    return base64.b64encode(signature).decode("ascii")


# Usage
api_key = os.environ["MERCHANT_API_KEY"]                       # btxm_xxxxxxxxxxxx
private_key = load_private_key(os.environ["MERCHANT_PRIVATE_KEY"])  # Ed25519:MC4CAQAw...

host = "https://sandboxapi.bitxpay.com"
path = "/api/v1/payment_links"                                  # sign the FULL path
method = "POST"
timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")  # RFC 3339, UTC
body = json.dumps({
    "payment_name": "Invoice #12345",
    "amount": 100.5,
    "currency": "USDT",
    "customer_email": "john@example.com",
    "success_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel",
})

signature = sign(private_key, method, path, timestamp, body)

response = requests.post(
    host + path,
    headers={
        "X-API-Key": api_key,
        "X-API-Signature": signature,
        "X-API-Timestamp": timestamp,
        "Content-Type": "application/json",
    },
    data=body,  # send the exact string that was signed (not json=...)
)
print(response.status_code, response.json())

Testing with Postman ​

For easy testing with Postman, see our Postman Setup Guide which includes a pre-request script that automatically generates signatures.

Timestamp Validation ​

X-API-Timestamp must parse as RFC 3339 and be within 5 minutes of the server clock, in either direction. Requests outside that window are rejected:

json
{
  "error": "unauthorized",
  "message": "request timestamp expired. Maximum allowed time difference is 5 minutes",
  "code": "TIMESTAMP_EXPIRED",
  "time_diff_seconds": 360.4
}

Ensure your system clock is synchronized with NTP servers.

Authentication Errors ​

All authentication failures return a JSON body with error, message and a string code:

HTTPcodeWhen
401API_KEY_REQUIREDNeither X-API-Key nor Authorization is present
401INVALID_API_KEY_FORMATKey does not start with btxm_
401INVALID_API_KEY_LENGTHKey shorter than 17 characters
401INVALID_API_KEY_HASHLegacy key without a public key fails hash validation
401INVALID_API_KEYKey unknown in this environment, or deactivated
401API_KEY_EXPIREDKey past its expiry date
401SIGNATURE_REQUIREDX-API-Signature missing
401TIMESTAMP_REQUIREDX-API-Timestamp missing
401INVALID_TIMESTAMP_FORMATTimestamp is not RFC 3339
401TIMESTAMP_EXPIREDTimestamp more than 5 minutes from server time
401SIGNATURE_VERIFICATION_FAILEDSignature does not verify against the key's public key
403MERCHANT_ACCOUNT_INACTIVEThe merchant account is not active
403DOMAIN_NOT_AUTHORIZEDKey is restricted to a domain and the request Origin/Referer does not match
403INSUFFICIENT_SCOPESKey lacks a scope required by the endpoint

A failed signature check also echoes what the server signed over, which is the quickest way to spot a path or body mismatch:

json
{
  "error": "unauthorized",
  "message": "signature verification failed: Ed25519 signature verification failed",
  "code": "SIGNATURE_VERIFICATION_FAILED",
  "debug": {
    "method": "POST",
    "path": "/api/v1/payment_links",
    "body_length": 71,
    "message_hash": ""
  }
}

Security Best Practices ​

WARNING

Keep your private key secure and never expose it in client-side code.

  1. Store keys securely - Use environment variables or a secrets manager
  2. Use HTTPS - All API requests must use HTTPS
  3. Rotate keys periodically - Generate new API keys regularly
  4. Limit key permissions - Use keys with minimal required scopes, and set a domain restriction where applicable
  5. Monitor API usage - Check your dashboard for unusual activity