API concepts

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, and you send that id as the x-association-id header on every protected request. The gateway scopes all data to it, so one application only ever acts within its own association.

​

Request authentication

Every protected request carries three headers:

• Authorization: Bearer <access token>, a short-lived token from POST /v1/auth/token.
• x-zeam-auth: <application secret>, your application secret (API key), issued at registration.
• x-association-id: <association id>, the association to scope the request to.

The gateway verifies the token server-side on every request and scopes the request to your association. A protected request without x-association-id returns 412. See Authentication.

​

One contract over many services

The platform behind the gateway uses different transports and auth models. The gateway hides that. The clearest example is connector discovery: internally it is a GraphQL query, but the gateway surfaces it as a plain REST collection at GET /v1/connectors. You never write GraphQL. The result is a 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. Before creating a wallet, use GET /v1/wallet-types and GET /v1/networks to discover valid typeId and networkId values.

​

The payment model

You move money by submitting a payment directly:

• POST /v1/payments/p2p: a same-asset transfer.
• POST /v1/payments/swap: a cross-asset transfer.
• 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.