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 api-keys:view, 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.

List Your API Keys

Call GET /partner/api/keys with an X-Api-Key credential explicitly granted api-keys:view. Existing keys without this scope must be replaced if you want to use them for inventory access.

curl 'https://api-staging.stabyl.com/v1/partner/api/keys' \
  -H 'X-Api-Key: YOUR_API_KEY'

The response contains data.keys, with active keys for the authenticated account ordered newest first. Keys created through a browser session appear here too. Each entry includes its name, key_last4, scopes, audience, authentication scheme, IP allowlist, creation time, last-used time, and withdrawal authorization time when present. Full credentials and secrets are never returned. This endpoint does not list other accounts in your organization or grant permission to create keys. Creation and revocation remain session operations. To list your webhook endpoints, use GET /partner/webhooks with webhooks:view.

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

For user-targeted simulation calls, a valid X-Api-Key or session cookie lets you omit user_id. Without credentials, supply user_id. A supplied ID must match the authenticated account; invalid credentials are rejected. When both an API key and session are supplied, they must identify the same account. Signed API keys retain their request-signature requirements. See Sandbox Simulation. 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