# accounts

Balances (ledger accounts per currency and sub-balances), account details per rail, journal with running balance, statements, currencies.

## GET /balances

operationId: `listBalances`
Summary: List balances
API key scopes: `balances:read`
Parameters: `X-Tenant-Id` (header, required), `X-Request-Id` (header), `cursor` (query), `limit` (query), `sort` (query), `filter` (query), `q` (query)
Responses: 200 `BalancePage`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 429 `Problem`, default `Problem`

Balances tab (All / Favourites / per currency). Amounts are real-time from `ledger.account_balances`. **Operator staff** (`x-tenant: any`): with `X-Tenant-Id` set to a customer they read that customer; with their operator id they read every customer of the operator (RLS operator scope), optionally narrowed with `filter[customerId]`.

**API key scope:** `balances:read`.

**Metadata filter:** `filter[metadata.<key>]=<value>` (exact match; at most 5; AND).

**Batch look-up (P12-T07):** `filter[id]=<id>,<id>,…` (at most 100) returns those rows only, e.g. to resolve names shown next to ids; combine with `limit` ≥ the number of ids.

## GET /balances/{balanceId}

operationId: `getBalance`
Summary: Get balance
API key scopes: `balances:read`
Parameters: `balanceId` (path, required), `X-Tenant-Id` (header, required), `X-Request-Id` (header), `If-None-Match` (header)
Responses: 200 `Balance`, 304, 401 `Problem`, 403 `Problem`, 404 `Problem`, 429 `Problem`, default `Problem`

**API key scope:** `balances:read`.

## GET /balances/{balanceId}/details

operationId: `getBalanceAccountDetails`
Summary: Account details (local and SWIFT)
API key scopes: `balances:read`
Parameters: `balanceId` (path, required), `X-Tenant-Id` (header, required), `X-Request-Id` (header), `rail` (query)
Responses: 200, 400 `Problem`, 401 `Problem`, 403 `Problem`, 404 `Problem`, 429 `Problem`, default `Problem`

`status: pending` until the partner has provisioned the account.

**API key scope:** `balances:read`.

## GET /balances/{balanceId}/holds

operationId: `listBalanceHolds`
Summary: Pending holds on a balance
API key scopes: `balances:read`
Parameters: `balanceId` (path, required), `X-Tenant-Id` (header, required), `X-Request-Id` (header), `cursor` (query), `limit` (query), `sort` (query), `filter` (query)
Responses: 200 `HoldPage`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 404 `Problem`, 429 `Problem`, default `Problem`

**API key scope:** `balances:read`.

**Review holds (P10R-01):** a hold placed while a payment is reviewed is listed with subject type `payment_review`, its own id as subject id and a neutral description; the amount counts against the available balance like any other hold.

## GET /balances/{balanceId}/journal

operationId: `listBalanceJournal`
Summary: Journal lines with running balance
API key scopes: `transactions:read`
Parameters: `balanceId` (path, required), `X-Tenant-Id` (header, required), `X-Request-Id` (header), `cursor` (query), `limit` (query), `sort` (query), `filter` (query)
Responses: 200 `JournalLinePage`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 404 `Problem`, 429 `Problem`, default `Problem`

**API key scope:** `transactions:read`.

## GET /balances/{balanceId}/statements

operationId: `listStatements`
Summary: Monthly statements
API key scopes: `statements:read`
Parameters: `balanceId` (path, required), `X-Tenant-Id` (header, required), `X-Request-Id` (header), `cursor` (query), `limit` (query), `sort` (query), `filter` (query)
Responses: 200 `StatementPage`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 404 `Problem`, 429 `Problem`, default `Problem`

**API key scope:** `statements:read`.

## POST /balances/{balanceId}/statements

operationId: `requestStatement`
Summary: Generate a custom-period statement (async)
API key scopes: `statements:read`
Parameters: `balanceId` (path, required), `X-Tenant-Id` (header, required), `X-Request-Id` (header)
Request body: `StatementRequest`
Responses: 202 `Job`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 404 `Problem`, 409 `Problem`, 422 `Problem`, 429 `Problem`, default `Problem`

**Step-up:** requires a verified step-up challenge for action `statement.full_export` within the last 5 minutes (session/bearer only). Otherwise `403` with problem type `step-up-required`; the step-up check runs before body validation.

**API key scope:** `statements:read`.

## GET /balances/{balanceId}/statements/{statementId}/download

operationId: `downloadStatement`
Summary: Download statement
API key scopes: `statements:read`
Parameters: `balanceId` (path, required), `statementId` (path, required), `X-Tenant-Id` (header, required), `X-Request-Id` (header), `format` (query)
Responses: 200 `DownloadLink`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 404 `Problem`, 429 `Problem`, default `Problem`

**API key scope:** `statements:read`.

## GET /currencies

operationId: `listCurrencies`
Summary: Currencies offered by the operator (with enabled flag)
API key scopes: `balances:read`
Parameters: `X-Tenant-Id` (header, required), `X-Request-Id` (header), `enabled` (query)
Responses: 200, 400 `Problem`, 401 `Problem`, 403 `Problem`, 429 `Problem`, default `Problem`

**API key scope:** `balances:read`.