Skip to main content
Stablecoin Account API Publisher Disclaimer This page covers the vocabulary and request conventions that apply to every Stablecoin Account endpoint. Read it once before building — the rest of the guide assumes these concepts.

​
Assets, networks, and balances

Four terms come up throughout the API: Each balance splits into three buckets:
  • available_balance — funds you can withdraw, convert, or transfer now.
  • frozen_balance — funds locked by in-flight orders or risk review.
  • margin_balance — funds reserved as margin.
Query balances with List Assets, and always check List Supported Assets and Networks before offering an asset–network pair to your users: it tells you whether deposits and withdrawals are currently enabled, minimum amounts, precision, and estimated arrival times.

​
Wallet addresses

A wallet address is not the same thing as a balance: the balance is what you hold, the wallet address is where senders send crypto to fund it. UQPAY generates and manages one address per asset–network pair — the first request creates it, and every later request returns the same address, so it is safe to fetch repeatedly. An address only accepts its own asset on its own network; funds sent as a different token, or over a different network, cannot be credited automatically. Retrieve an address with Deposit Wallet Address (see Receive deposits for the full flow), or look it up in the Merchant Portal — see Wallet address - find your wallet address using merchant portal.

​
Order types and lifecycles

Every money movement creates an order with a long order_id (UUID) and a human-friendly short_order_id (for example WD260124-N1PAAIXX). Orders appear in the unified asset transaction history with one of these types:

​
Order statuses

Deposits and withdrawals use the subset Pending → Success / Failed. Treat Success and the terminal failed webhook events as the only final states; Pending orders can remain in progress for some time depending on network congestion.

​
Request conventions

​
Base URLs

All Stablecoin Account endpoints live under /v1/ramp/ and use the same paths in both environments.

​
Authentication

Request an access token from the Access Token endpoint using your x-client-id and x-api-key credentials, then send it on every call:

​
Acting on behalf of a sub-account

Pass the optional x-on-behalf-of header with a sub-account’s account_id to execute a request for that sub-account. Omit it to act as the master account. See Connected Accounts for how sub-accounts work.

​
Idempotency

Write endpoints that create orders — Create Transfer, Create Conversion, Create Withdraw, Create Address Book, Update Address Book, and Submit Deposit Sender Travel Rule — accept an x-idempotency-key header (UUID). Retrying a request with the same key returns the original result instead of creating a duplicate order. Generate a fresh UUID per logical operation and reuse it on network retries:

​
Response envelope

Every response wraps its payload in the same envelope. code mirrors the HTTP status; data carries the result:
List endpoints paginate inside data with total_pages and total_items, controlled by the page_num and page_size query parameters. Amount fields are decimal strings (for example "100.50") — parse them with a decimal type, not a float. See Error codes for non-2xx responses.

​
Webhooks

Order status changes are pushed to your configured webhook endpoint as events named ramp.<resource>.<status> (for example ramp.deposit.success). Each event carries the order in data and the order ID in source_id. See the Webhooks tab for payloads per event.