Authentication
All currently published BITXpay Merchant APIs (Payments and Subscriptions) use a single authentication method:
- 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
| Header | Description |
|---|---|
X-API-Key | Your merchant API key, e.g. btxm_9b451fa04a2e |
X-API-Signature | Signature of the canonical message, base64-encoded (raw 64-byte Ed25519 signature, or RSA-PSS signature for legacy keys) |
X-API-Timestamp | RFC 3339 / ISO 8601 timestamp in UTC (e.g., 2026-01-31T17:53:56Z). Fractional seconds are accepted. |
Content-Type | application/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
- Log in to your BITXpay Dashboard
- Navigate to Developers → API Keys
- Generate your Merchant API Key and Private Key
- Store both securely - the private key is shown only once
Your credentials will include:
| Credential | Format | Example |
|---|---|---|
| API Key (public identifier) | btxm_ + 12 hex characters | btxm_9b451fa04a2e |
| Private Key (keep secret) | Ed25519: + base64 of the PKCS#8 DER key | Ed25519:MC4CAQAwBQYDK2VwBCIEI… |
| Public Key (for your records) | Ed25519: + base64 of the SubjectPublicKeyInfo DER key | Ed25519: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| Part | Value |
|---|---|
METHOD | Upper-case HTTP method, e.g. POST |
PATH | The full request path including the /api/v1 prefix, without host or query string, e.g. /api/v1/payment_links |
TIMESTAMP | The exact string sent in X-API-Timestamp |
BODY | The 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-Timestampon every request (see Timestamp Validation).
Node.js Example
These examples load the dashboard-issued key and sign the exact request bytes.
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
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:
{
"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:
| HTTP | code | When |
|---|---|---|
| 401 | API_KEY_REQUIRED | Neither X-API-Key nor Authorization is present |
| 401 | INVALID_API_KEY_FORMAT | Key does not start with btxm_ |
| 401 | INVALID_API_KEY_LENGTH | Key shorter than 17 characters |
| 401 | INVALID_API_KEY_HASH | Legacy key without a public key fails hash validation |
| 401 | INVALID_API_KEY | Key unknown in this environment, or deactivated |
| 401 | API_KEY_EXPIRED | Key past its expiry date |
| 401 | SIGNATURE_REQUIRED | X-API-Signature missing |
| 401 | TIMESTAMP_REQUIRED | X-API-Timestamp missing |
| 401 | INVALID_TIMESTAMP_FORMAT | Timestamp is not RFC 3339 |
| 401 | TIMESTAMP_EXPIRED | Timestamp more than 5 minutes from server time |
| 401 | SIGNATURE_VERIFICATION_FAILED | Signature does not verify against the key's public key |
| 403 | MERCHANT_ACCOUNT_INACTIVE | The merchant account is not active |
| 403 | DOMAIN_NOT_AUTHORIZED | Key is restricted to a domain and the request Origin/Referer does not match |
| 403 | INSUFFICIENT_SCOPES | Key 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:
{
"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.
- Store keys securely - Use environment variables or a secrets manager
- Use HTTPS - All API requests must use HTTPS
- Rotate keys periodically - Generate new API keys regularly
- Limit key permissions - Use keys with minimal required scopes, and set a domain restriction where applicable
- Monitor API usage - Check your dashboard for unusual activity