Getting Started

Quickstart

Seven requests take a new customer from nothing to a paid-out on-ramp order. Each step links to the page that explains the details; the bodies here are the shortest working form.

Send X-Api-Key with every request — see Authentication for where the key comes from and for the client samples in other languages.

1. Create the customer

curl https://api.stablegate.com/v1/customers/ \
  --request POST \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "individual",
  "email": "[email protected]",
  "first_name": "Max",
  "last_name": "Mustermann",
  "country_code": "DE"
}'

The response carries the customer uuid. Keep it: every later call needs it. Details — Customers.

2. Verify the customer

Instant verification needs nothing from the customer beyond their identity details:

curl https://api.stablegate.com/v1/customers/CUSTOMER_UUID/verification/instant/ \
  --request POST \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "first_name": "Max",
  "last_name": "Mustermann",
  "date_of_birth": "1990-05-17"
}'

Stablegate screens the name against sanctions and politically exposed persons and approves the application when the screening is clear — usually within minutes. Poll Check the Verification State until application.status is approved; kyc_level_key then holds light.

curl https://api.stablegate.com/v1/customers/CUSTOMER_UUID/verification/ \
  --header 'X-Api-Key: YOUR_API_KEY'

Standard verification works the same way but the customer uploads documents: Create a Verification Link.

3. Register where the money goes

For an on-ramp the customer receives crypto, so register their wallet:

curl https://api.stablegate.com/v1/customers/CUSTOMER_UUID/wallets/ \
  --request POST \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "rail": "ethereum",
  "address": "0xDC1dCb46fC96C46c4F294866AFCA81874041bB2",
  "name": "Max — main"
}'

Ethereum and Polygon wallets also need an ownership signature — External Accounts. For an off-ramp register a bank account instead.

4. Check what the order will cost

curl https://api.stablegate.com/v1/customers/CUSTOMER_UUID/check-fees/ \
  --request POST \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "source": {
    "rail": "sepa",
    "asset": "EUR",
    "amount": 1000
  },
  "destination": {
    "rail": "ethereum",
    "asset": "USDC"
  }
}'

The answer holds the commission, the amount the customer receives, the rate and how long the rate holds. Limits are a separate call — POST /v1/customers/CUSTOMER_UUID/check-limits/ returns an empty array when the order fits.

5. Create the order

curl https://api.stablegate.com/v1/customers/CUSTOMER_UUID/orders/ \
  --request POST \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: onramp-2026-11-10-001' \
  --data '{
  "source": {
    "rail": "sepa",
    "asset": "EUR",
    "amount": 1000
  },
  "destination": {
    "rail": "ethereum",
    "asset": "USDC",
    "client_account_uuid": "WALLET_UUID"
  }
}'

The response is the order: reference is the payment reference the customer must put on the transfer, source.deposit_bank_info holds the account to pay into, state stays new until the money arrives.

6. Follow the deposit and the payout

Either poll the order or wait for the webhook.

curl https://api.stablegate.com/v1/customers/CUSTOMER_UUID/orders/ORDER_UUID/ \
  --header 'X-Api-Key: YOUR_API_KEY'

source.deposit_status moves to detected when the transfer lands, and state goes new → processing → done. Webhooks are described in Webhooks: one event per status change, and one per deposit status change.

What to expect and when

Step	How long it takes
Instant verification	Minutes; longer when the screening returns a match and compliance reviews it
SEPA deposit	Usually the same or next banking day, `sepa_instant` in seconds; `deposit_status` shows the arrival
Payout to a wallet	Minutes after the order reaches `processing`
Payout to a bank account	Same or next banking day

Idempotency-Key is optional but cheap: a retried request with the same key returns the first result instead of creating a second order. See Idempotency.

Ready to integrate?

Tell us about your use case and we will enable Partner API access for your account.

Talk to the team

Errors

The body of every failed request, the status codes, the error codes you can branch on, and what to do about each.

Customers

A customer represents an end-user of your platform within the Stablegate system. Every operation — orders, external accounts, fee checks, limit checks — is scoped to a customer. Before you can process any transactions, you need to register your customers with Stablegate.