Customer API quickstart

Every step below is one HTTPS request carrying a bearer token. There is no SDK to install and no browser redirect to handle.

The examples use curl, jq, and uuidgen. Any language works the same way: form-encode the token request, then send Authorization: Bearer <token> on everything else.

Balances are available to every operator. A foreign-exchange quote is a write that moves no funds: it records provider-derived terms. Marketplace listings, offers, and trades are available only when the operator enables the marketplace capability. Treasury vault endpoints (/vaults) likewise answer 404 unless the operator enables the treasury yield capability.

Payments, bank deposits (onramp), bank payouts (offramp), and vault deposits and withdrawals are open to a client that holds money.write, which an organisation owner grants under step-up authentication together with per-transaction limits in Settings → API clients. Payments also need a destination approved there by the owner. Onramp uses an operator-supplied source_id. Vault deposits and withdrawals need neither an approved destination nor a source_id. Offramp needs an owner-approved bank-account destination and takes a USDC amount for a sandbox USD/EUR payout within the existing sell windows. The Money movement section shows each money request.

As an organisation owner, open Settings → API clients and create a client with the read and write scopes; confirm with your authenticator app when asked. Loam displays the client secret once, at creation — copy it into a secret manager before leaving the page, because it cannot be shown again. Rotating the client issues a new secret; the previous one keeps working for up to 24 hours, and stops sooner if you rotate again, so integrations can switch over. Only an organisation owner can create or rotate a client, after confirming with an authenticator app. Owners and admins can revoke one; only an owner can revoke a client that holds money.write. If a secret leaked, revoke the client to invalidate both secrets immediately, then create a new client.

The API answers on the same host you sign in to, under /api/v1. Requests to any other host return 401 with invalid_client, even when the credentials themselves are valid.

Exchange the client credentials for a short-lived bearer token. The request body is form-encoded rather than JSON, and HTTP Basic authentication is deliberately not accepted.

A valid exchange returns 200 with the token, its remaining life in seconds, and the scopes currently on the client:

An unknown, wrong, or revoked secret returns 401 with {"error": "invalid_client"}, and a client whose organisation has no API access returns 403 with {"error": "unauthorized_client"}. Token failures use the OAuth 2 shape — error and error_description — not the envelope the resource routes use.

Scopes are read from the client on every request, so narrowing them takes effect at once rather than when the token expires. Mint a new token when the old one runs out instead of storing it. In a shell, capture one now and reuse it for the rest of this guide:

Send the token as a bearer credential. This endpoint returns 200 with the standard ok and data envelope:

This projection is stablecoin-only — every row is a held stablecoin balance, never a fiat one. Balances are integers in the currency's smallest unit: 42500000000 with USDC means USDC 42,500.000000. Never parse them as decimals.

An empty data array is a success, not an error — it means the organisation has no settled balances yet.

No Convert pair is currently offered. A new quote request that reaches pair validation returns 400 invalid_input for an unoffered pair. Authentication, authorization, rate-limit, idempotency and transient-error responses still apply. See GET /api/v1/openapi.json for the live offered set.

Send a retry with the same Idempotency-Key and the same body, and Loam replays the original outcome instead of minting a second quote — so a timeout or a dropped connection costs nothing. Reuse the key with a different body and the request is rejected with 409. A new key always means a new operation.

Every money write — payments, onramp, offramp, and vault deposits and withdrawals — is checked again before Loam replays its outcome, so a retry may be refused with 403 forbidden. Do not retry with a new key: read the original write back instead, through the Location you received for it. If you have no Location, onramp, offramp and vault requests are found by the ?idempotency_key= collection read; for a payment, list /payments and match on your own amount, currency and destination. A retry can also answer 503 transient_error, or 409 with Retry-After while the first attempt is still held: wait, then retry with the same key.

Reads need no key. They change nothing and are safe to retry as they are.

Token minting and resource requests are limited separately, per client. A 429 carries Retry-After in seconds: wait that long, then retry the same request.

Resource errors carry {"ok": false, "error": "<code>"} with a machine-readable code. Handle broad cases on the status and specific recovery paths on the code. The API reference lists every code, the scope each endpoint needs, and the full response schema.

Listing payments is a read and is open in preview. A quote (POST /api/v1/fx/quotes) is a write that moves no funds: it locks provider-derived terms under the write scope. You reuse those currencies and integer amounts on a money.write request — there is no execute-quote route on this API.

GET /api/v1/payments returns the organisation's payments as a cursor page. An empty data array is a success — it means nothing has been recorded yet. Poll GET /api/v1/payments/<payment-id> for one payment.

money.write is not on the client by default. A human organisation owner grants it under fresh step-up authentication (AAL2 / MFA at grant time), sets a per-transaction limit, and approves each destination in advance. Narrowing or revoking the grant takes effect on the next request. Machine execution does not prompt for a second factor; the SQL money-authorization fence is the authority. The owner does this in Settings → API clients: grant money movement and set its limits, then set the organisation limit, then approve each counterparty. The destination ID shown once at approval is the destination_id payments use. Offramp uses the bank-account UUID approved by the owner as its destination_id; bank approval uses the RPC described below. Money limits and fiat amounts must use a currency with two decimal places or a stablecoin; RWF and UGX money moves are not supported yet.

Two failure modes are worth designing for now. A 403 with forbidden means the destination is visible but authorization was refused — missing scope, withdrawn enablement, a failed step-up grant, or an approved counterparty whose connection is no longer active. A 400 with invalid_input means the destination is unknown or invisible to the client. A revoked destination returns 403 with destination_revoked. None of these are transient, so none should be retried blindly.

When the grant is in place, a payment to an approved destination is:

amount is a positive integer in minor units, the same convention as the quote. destination_id must be an approved destination for this client. Poll GET /api/v1/payments/<payment-id> for later state.

Funds in use an operator-supplied funding account (source_id) rather than a payee. currency must equal the currency of the source_id account; otherwise the response is 403 forbidden.

List your operator's vaults with GET /api/v1/vaults and set VAULT_ID to the id of the vault you choose; only an active vault accepts deposits. Vault deposits and withdrawals take an amount in minor units of that vault's currency.

Both return 202 with { ok: true, data: { id, state } } and a Location under the same vault path. Poll that location for later state.

POST /api/v1/offramp takes destination_id, amount in USDC minor units, and currency: USDC. An organisation owner must approve the bank-account destination through the existing api_client_destination_approve Supabase RPC, using their authenticated owner session with fresh AAL2. Settings → API clients currently approves counterparties only. The approval is a human control-plane action, not a request made with the API client's bearer token. Set the project URL, publishable key, and the bank-account UUID first:

Sign in as an organisation owner without a password, then verify their enrolled TOTP factor immediately before approving. Sign-in requires a Turnstile CAPTCHA token. On the provisioned sandbox using the Turnstile test key pair, enter XXXX.DUMMY.TOKEN.XXXX at the CAPTCHA prompt. For a project using live Turnstile keys, obtain a fresh token from its sign-in page's Turnstile widget. Request a sign-in code, then enter the code from the email at the prompt below. The TOTP verification response replaces the AAL1 access token with the fresh AAL2 session used below:

Look up the API client's internal UUID through the redacted owner-readable view; do not use the public client_id in the RPC. Then approve the bank account before the fresh AAL2 session expires:

Use that bank-account UUID as destination_id on the machine request. The bank account also needs approved manual verification and payable bank details. Sandbox payouts support configured USD/EUR destinations only: 5–1,000,000 USDC for USD and 5–2,000,000 USDC for EUR. The payout currency is the account's currency, and the rate is locked at operator approval. A new intent that cannot be priced is refused before any reservation or debit. Existing intents remain replayable, including when the manual rail is disabled. Accepted requests return 202 with Location; follow it to retrieve the requested row. A same-key replay returns the same id with no second treasury debit.

• API reference — every endpoint, scope, schema, and error code.
• Settings → API clients — create, rotate, and revoke credentials.