Authentication & Environments

Use sandbox for all development and testing. Production credentials are issued separately by Banxa after your integration has been approved.

Your partner reference ({partnerRef}) is a unique identifier assigned to your account. It is included in every API request path:

https://api.banxa-sandbox.com/{partnerRef}/v2/...

The production API is rate-limited to 500 requests per minute across all endpoints combined, per IP address. The sandbox API is rate-limited to 120 requests per minute per merchant account: sandbox is a shared testing environment, and the lower limit keeps it responsive for all merchants. Requests exceeding either limit will receive an HTTP 429 Too Many Requests response.

Best practices:

• Use webhooks for order status updates instead of polling the orders endpoint.
• Call the quotes endpoint only when a customer actively requests a quote — do not poll for price feeds.
• Implement exponential backoff when retrying after a 429 response.
• If you consistently hit rate limits in normal operation, review your call patterns — it typically indicates unnecessary polling.

Switch between sandbox and production via the environment toggle at the top of the Partner Dashboard. Configuration changes (webhooks, supported assets, UI settings) are made independently per environment.

All v2 endpoints use API key authentication. Include your API key in the request header:

x-api-key: YOUR_API_KEY

Your sandbox and production API keys are different. Retrieve them from the Partner Dashboard under your account settings.

The identity token sharing endpoint (POST /v2/identities/token/share) requires HMAC-signed requests instead of the standard API key header.

HMAC is also used in the opposite direction for webhooks: Banxa signs every outbound webhook notification it sends to you, and you verify that signature to confirm it genuinely came from Banxa. The signing algorithm is the same, but the path in the canonical string is different — see Webhooks for the verification flow.

HMAC credentials must be stored server-side. Never embed your API secret in frontend or mobile code.

Authorization: Bearer API_KEY:SIGNATURE:NONCE

Construct a newline-separated canonical string, then sign it with HMAC-SHA256 using your API secret.

GET request:

METHOD\nPATH_WITH_QUERY_STRING\nNONCE

POST request:

METHOD\nPATH\nNONCE\nCOMPACT_JSON_BODY

Rules:

• Use the request path only — never the full URL with domain
• Include the query string in the path for GET requests
• JSON body must be compact — no whitespace between elements
• Generate a new nonce for every request

Example, using a 16-digit microsecond nonce. Sign the path exactly as you call it — POST /{partnerRef}/v2/identities/token/share is routed to the enterprise API through the Banxa gateway, but the canonical string uses the v2 path you requested:

POST\n/mypartner/v2/identities/token/share\n1785804345837761\n{"externalCustomerId":"example_01"}

import hmac
import time
import json

key = '[YOUR_API_KEY]'
secret = '[YOUR_API_SECRET]'

def generate_hmac(method, path, payload=None):
    nonce = str(int(time.time() * 1_000_000))
    parts = [method, path, nonce]
    if payload:
        parts.append(json.dumps(payload, separators=(',', ':')))
    data = '\n'.join(parts)
    signature = hmac.new(secret.encode('utf-8'), data.encode('utf-8'), 'sha256').hexdigest()
    return f'{key}:{signature}:{nonce}', nonce

• Generate a new nonce for every request — reuse will be rejected
• Use microsecond precision for the nonce — millisecond timestamps collide under concurrent load
• Keep your system clock in sync (NTP) to avoid nonce expiry errors
• Serialize request bodies with no whitespace before signing
• Sign the request path only — never the full URL including domain
• Store your API secret in a secure secret store, never in source code or client-side storage
• Rotate your secret immediately if you suspect it has been exposed