Authentication

All partner endpoints require an API key, passed as a Bearer token in the Authorization header. Keyless public endpoints take no credential.

Header format

curl "https://app.gma.fi/api/agents" \
  -H "Authorization: Bearer YOUR_API_KEY"

Keys are issued in the form gma_api_.... The scheme must be exactly Bearer and the token must start with gma_api_; anything else is rejected with 401.

To request a key, see Request an API key.

Scopes

Each key carries one scope. write implies read, so a write key can call every partner endpoint.

Scope	Access
read	Read-only endpoints: agents, positions, history (GET), NAV, stats, allocations, vault history, pnl-history, portfolio-history, rebalances, withdraw status.
write	Everything a read key can do, plus deposit, withdraw (initiate/claim), and POST /api/history activity ingestion.

Error responses

Status	Meaning
401	Missing Authorization header, non-Bearer scheme, malformed key, or an invalid/revoked/expired key.
403	Insufficient scope (e.g. a read key on a write endpoint), a vault outside the key's allowlist, or a wallet outside the key's binding.
429	Rate limit exceeded (or the key has no valid RPM configured).
503	Temporarily unavailable due to maintenance (see below).

Maintenance

During deposit-blocking maintenance, the mutating money-movement endpoints — POST /api/vault/{vault_id}/deposit and the POST /api/vault/{vault_id}/withdraw initiate/claim actions — return 503; read endpoints keep serving. During full maintenance, all endpoints return 503, including the keyless public endpoints such as GET /api/oracle. Treat 503 as transient and retry with backoff.

Per-consumer vault allowlist

A key belongs to a consumer, and a consumer may be restricted to specific vaults. When a key is scoped to an allowlist, any request for a vault outside it returns 403 with "Vault not in consumer scope". An unrestricted consumer (no allowlist) may access every registered vault, and GET /api/agents and GET /api/positions transparently return only the vaults in scope.

Wallet binding

A key may additionally be bound to a single wallet. A wallet-bound key may only read or build transactions for its bound wallet; any other wallet parameter returns 403 with "Wallet does not match API key wallet binding". Multi-wallet partner keys have no binding and may act on any wallet.

Keep keys server-side

Treat production API keys as server-side secrets. Never embed a read or write key in a browser bundle. Browser-wallet applications should call a dedicated endpoint on their own backend; that backend attaches the _gamma Bearer key and pins the allowed wallet, vault, and operation before forwarding the request. The transaction-signing examples in Transactions follow this pattern.

Next: Vault endpoints