API concepts

How the gateway authenticates you, scopes your data, and normalizes the platform behind one REST contract.

A few ideas explain almost everything about how the gateway behaves. Read this once and the rest of the docs will make sense.

Applications and associations

An association is a Zeam business tenant. An application is a registered integration bound to exactly one association. Your application credentials identify you; the association defines the data you can see.

Your association is fixed to your application. You receive its id as associationId when you issue a token, but you never send it — the gateway resolves it server-side from your bearer token on every request, so one application only ever acts within its own association.

Request authentication

Every request carries x-zeam-auth; protected requests also carry a bearer token:

• x-zeam-auth: <application secret>, your application secret (API key), issued at registration. Required on every request, including token issuance.
• Authorization: Bearer <access token>, a short-lived token from POST /v1/auth/token. Required on protected requests.

The gateway verifies the token server-side on every protected request and resolves your association from it. See Authentication.

One contract over the whole platform

Wherever you look, the gateway presents the same uniform contract:

• Resource-oriented routes under /v1, camelCase fields.
• Cursor pagination on collections.
• RFC 7807 problem responses on every error.
• An X-Request-Id on every response for support correlation.

Request lifecycle

Wallets and balances

Each wallet in your association has a Stellar public key. Balances (on-chain trustlines) are embedded directly in the wallet resource and returned by GET /v1/wallets, GET /v1/wallets/{walletId}, and POST /v1/wallets. Balance enrichment is best-effort: a transient Horizon failure leaves balances empty rather than failing the whole request.

Creating a wallet for your own association only takes a walletName and an assetCode (see GET /v1/assets for valid codes) — network, wallet type, and custody are fixed platform-side. A wallet held on behalf of a third party additionally requires ownAccount: false and a metadata object with that party’s FICA details.

A sandbox token does not provide test isolation from production: records you create and funds you move are real either way. See Sandbox limitations.

The payment model

You move money by submitting a payment directly:

• POST /v1/payments/p2p/own and POST /v1/payments/p2p/own/multi: a same-asset transfer between your own wallets (single or multi-leg).
• POST /v1/payments/p2p/beneficiary: a same-asset payment to a beneficiary’s crypto destination.
• POST /v1/payments/swap/own and POST /v1/payments/swap/beneficiary: the cross-asset equivalents.
• POST /v1/payments/offramp: a cash-out to a real-world destination, executed against a quote.

Payments are asynchronous: submission returns 202 Accepted with a transactionRecordId. Track the outcome by polling the transactions routes or by receiving webhook updates. The end-to-end path is walked in Your first transaction.

Environments

There are two environments: a sandbox for building and testing, and production for live traffic. You start in the sandbox and are promoted to production after validation and operational readiness. See Sandbox.