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 is trades:view, trades:create, trades:execute, wallets:view, wallets:transfer, and settlements:view. It excludes webhooks:view, webhooks:manage, and wallets:withdraw, so select those explicitly during key creation when you need them. Selecting wallets:withdraw also requires completing account authentication with an existing account passkey or withdrawal password. Changing scopes requires replacing the key. An IP or CIDR allowlist is optional. A key can never do more than its stored scopes allow. It can do less if your account’s own permissions are later reduced, because effective access is the intersection of the two.

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 scope, is not a partner API key, fails its IP allowlist, or the account has not met a production requirement such as KYB	Key scopes, account readiness, and the caller’s source IP. Scope failures return code `FORBIDDEN` on ordinary routes and `MISSING_SCOPE` on signed withdrawal routes
`409`	A signed nonce was replayed, or a withdrawal 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, the rate-limit store, or webhook management 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