Quickstart für die Customer API

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. Marketplace listings, offers, and trades are available when the operator enables the marketplace capability. Writes cover marketplace offers and foreign-exchange quotes — requests that record intent and move no funds.

Money movement stays closed during preview. Payments, bank transfers, and vault deposits or withdrawals need the money.write scope, which an organisation owner grants by hand alongside per-transaction limits and an approved destination. Build the balance read now; the last section explains what money endpoints will ask for.

Open Settings → API clients and create a client with the read and write scopes. Loam displays the client secret once, at creation — copy it into a secret manager before leaving the page, because rotating the client is the only way to see a secret again.

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:

Balances are integers in the currency's smallest unit: 4250000 with USD means USD 42,500.00. Never parse them as decimals.

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

Listings, offers, and trades are available only when the operator has enabled the marketplace capability. These endpoints return 404 unless it is enabled. Marketplace also requires the payments and invoicing capabilities, so ask the operator to enable those prerequisites before you call the marketplace flow below.

Offers are made against a listing, so read the listings first and take an id from the response. The call returns every listing your organisation owns plus every published listing on the platform, and only a published listing accepts offers.

Note the currency on the listing. An offer has to use the same one.

Take the listing id and currency from the previous response, generate a UUID for the Idempotency-Key header, and post the price you are willing to pay — again as an integer in the smallest unit, so 2500000 with USD offers USD 25,000.00.

A created offer returns 202 with its id and state, plus a Location header pointing at the offer. 202 means accepted for processing: read the offer at that location to see where it settled.

A 409 here has two likely causes: the listing belongs to your own organisation, or the offered currency does not match the listing. Pick a different published listing, or correct the currency, rather than retrying the same body.

Send a retry with the same Idempotency-Key and the same body, and Loam replays the original outcome instead of creating a second offer — 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.

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.

Payment, funding, and vault endpoints are held to a stricter standard than the reads and offers above, and they stay closed during preview. When they open, a request needs the money.write scope granted by a human organisation owner under fresh multi-factor authentication, a per-transaction limit, and a destination approved in advance.

Two failure modes are worth designing for now. A 403 means the destination is visible but authorization was refused. A 400 means the destination is unknown or invisible to the client. Neither is transient, so neither should be retried blindly.

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