Authentication

Authenticated routes require an API key in the X-Api-Key header:

X-Api-Key: <api_key>

Create a staging API key

Sign in to the Stabyl staging app to create API keys for staging. Store the generated key when it is shown and use it only with https://api-staging.stabyl.com/v1. Keep API keys in server-side systems only. Do not embed keys in browser, mobile, desktop, or user-controlled code.

Production API access

Production API access is not enabled by staging access. Your organization must complete KYB and receive an explicit invitation from Stabyl before provisioning production credentials. Follow the instructions in that invitation and use the resulting credentials only with https://api.stabyl.com/v1. Do not copy a staging key into production configuration or treat successful staging integration as production approval. New keys use immutable scopes. The default scope set excludes wallets:withdraw; select that scope explicitly during key creation and complete account authentication with an existing account passkey or withdrawal password. Changing scopes requires replacing the key. An IP or CIDR allowlist is optional.

Key Handling Rules

Rule	Reason
Store keys in a secret manager or encrypted environment store	Keys authorize account activity
Use separate keys per service	Limits blast radius and simplifies rotation
Do not log full key values	Logs are copied and retained in many systems
Keep staging and production keys separate	Prevents accidental live requests
Use a dedicated key for withdrawals	Keeps signing material and scope narrow
Store the signing secret returned at creation	The secret is displayed only once

Signed Withdrawal Requests

Withdrawal quote and submit calls require three additional headers:

X-Stabyl-Timestamp: <unix_milliseconds>
X-Stabyl-Nonce: <uuid_v4_or_v7>
X-Stabyl-Signature: <base64url_ed25519_signature>

The signature covers the HTTP method, exact path and query, timestamp, nonce, and SHA-256 hash of the exact raw body bytes. See Withdrawals for canonicalization rules and the fixed test vector. The signed request is the Partner withdrawal authorization. Quote and submit do not accept or wait for an emailed verification code or client-supplied withdrawal token.

Public Endpoints

Only these Mintlify-documented routes do not require an API key:

GET /partner/wallets/chains
GET /partner/wallets/fiat/banks
POST /simulate/fiat/deposits
POST /simulate/fiat/withdrawals
POST /simulate/crypto/deposits
POST /simulate/crypto/withdrawals
POST /simulate/kyb/status
POST /simulate/notifications/product-updates

All other documented routes require X-Api-Key.

Authentication Failures

Status	What it usually means	What to check
`401`	The key or required signature is missing, malformed, invalid, or sent to the wrong environment	Header values, canonical path, raw body bytes, clock, key value, and base URL
`403`	The key is valid but lacks the required immutable scope or fails its IP allowlist	Key scopes, account readiness, and the caller’s source IP
`409`	A signed nonce was replayed or an idempotency key was reused for another intent	Generate a new nonce for transport retries; keep the body unchanged
`429`	Requests are arriving too quickly	Backoff and reduce polling or retry loops
`503`	Signed replay protection is temporarily unavailable	Fail closed and retry later with a new nonce

If the same key works for reads but not withdrawal writes, confirm wallets:withdraw is present and that the request was signed with the secret returned for that key.

Get Started

Wallets

Exchange

Webhooks

WebSocket

Create a staging API key

Production API access

Key Handling Rules

Signed Withdrawal Requests

Public Endpoints

Authentication Failures

​Create a staging API key

​Production API access

​Key Handling Rules

​Signed Withdrawal Requests

​Public Endpoints

​Authentication Failures

Create a staging API key

Production API access

Key Handling Rules

Signed Withdrawal Requests

Public Endpoints

Authentication Failures