# Generate a Position Report (balance snapshot)

Endpoint: POST /v1/exports/position
Version: v1
Security: bearer

## Security:

  - `bearer` (unknown)
    http bearer JWT

## Request fields (application/json):

  - `domainId` (string, required)
    Domain UUID to export position data for

  - `asOfTimestamp` (string, required)
    Point-in-time timestamp for balance snapshot (ISO-8601)

  - `includeChildDomains` (boolean)
    Include data from child domains

  - `vaultIds` (array)
    Filter by vault UUIDs

  - `tickerIds` (array)
    Filter by ticker UUIDs

  - `accountIds` (array)
    Filter by account UUIDs

  - `includeZeroBalances` (boolean)
    Include accounts with zero balances

  - `format` (string, required)
    Output format
    Enum: "CSV", "JSON"

## Response 201:

  - `201` (unknown)
    Report generated.

## Response 201 fields (application/json):

  - `metadata` (object, required)
    File-level metadata and reconciliation control totals.

  - `metadata.exportId` (string, required)
    Unique identifier of this export. Also returned in the X-Export-Id header.
    Example: cef02796-daca-425f-91ed-f670eb8ec99f

  - `metadata.requestAuthor` (string, required)
    Identity that requested the export.
    Example: harmonize:hmz@metaco.com

  - `metadata.generatedAt` (string, required)
    Generation timestamp (ISO-8601).
    Example: 2026-08-27T09:15:00Z

  - `metadata.filters` (object, required)
    Echo of the request filter parameters.
    Example: {"domainId":"5cd224fe-193e-8bce-c94c-c6c05245e2d1","asOfTimestamp":"2026-08-21T16:32:03.9740000+00:00","includeZeroBalances":true}

  - `metadata.asOfTimestamp` (string)
    Echoed from the request — Position Report only (ISO-8601).
    Example: 2026-08-27T00:00:00Z

  - `metadata.dateRangeStart` (string)
    Echoed from the request — Movement Report only (ISO-8601).
    Example: 2026-07-25T00:00:00Z

  - `metadata.dateRangeEnd` (string)
    Echoed from the request — Movement Report only (ISO-8601).
    Example: 2026-08-27T00:00:00Z

  - `metadata.recordCount` (number, required)
    Number of data rows. Position: one row per (account, ticker). Movement: one row per transfer.
    Example: 22

  - `metadata.controlTotals` (object, required)
    Reconciliation control totals across all rows.

  - `metadata.controlTotals.balanceTotalAmount` (string)
    Sum of all totalBalance values (Position Report only). BigNumber-formatted string.
    Example: 429.04029589

  - `metadata.controlTotals.balanceReservedAmount` (string)
    Sum of all reservedBalance values (Position Report only). BigNumber-formatted string.
    Example: 2.0033804

  - `metadata.controlTotals.balanceQuarantinedAmount` (string)
    Sum of all quarantineBalance values (Position Report only). BigNumber-formatted string.
    Example: 122.2

  - `metadata.controlTotals.valueSum` (string)
    Sum of all enrichedTransactionValue values (Movement Report only). BigNumber-formatted string.
    Example: 154.54

  - `data` (array, required)
    One row per (account, ticker). With omnibus support enabled, contains on-chain custody accounts only — virtual (tenant) balances are excluded and control totals represent on-chain holdings.

  - `data.domainId` (string, required)
    Domain UUID owning the account.

  - `data.domainName` (string, required)
    Domain display name.
    Example: My root domain

  - `data.vaultType` (string, required)
    Vault backing type passed through from the core system, such as 'MPC' or 'HSM'. Empty for accounts without a vault (external).
    Example: HSM

  - `data.vaultId` (string, required)
    Vault UUID. Empty for accounts without a vault (external).

  - `data.vaultName` (string, required)
    Vault display name. Empty for accounts without a vault (external).

  - `data.accountId` (string, required)
    Account UUID.

  - `data.accountName` (string, required)
    Account display name.
    Example: omnibus

  - `data.accountType` (string, required)
    One of 'vault', 'gas station', 'external', 'omnibus', 'deposit wallet'. 'external' identifies an account held at a subcustodian Provider — its vault columns are empty. 'omnibus' (a domain's omnibus wallet) and 'deposit wallet' (an omnibus tenant's deposit wallet) are emitted only when omnibus support is enabled for the environment.
    Example: omnibus

  - `data.ledgerName` (string, required)
    Blockchain network name as configured by the operator.
    Example: XRPL Testnet August 2024

  - `data.addressOnLedger` (string, required)
    On-chain address of the account on this ledger.

  - `data.tickerId` (string, required)
    Asset UUID.

  - `data.tickerKind` (string, required)
    Asset kind.
    Example: Native

  - `data.tickerName` (string, required)
    Asset display name.
    Example: XRP Testnet August 2024

  - `data.tickerSymbol` (string, required)
    Asset symbol.
    Example: tXRP

  - `data.reservedBalance` (string, required)
    Reserved balance. BigNumber-formatted string in display units.
    Example: 0.000000

  - `data.quarantineBalance` (string, required)
    Quarantined balance. BigNumber-formatted string in display units.
    Example: 0.000000

  - `data.totalBalance` (string, required)
    Total balance. BigNumber-formatted string in display units.
    Example: 51.994800

  - `data.ledgerBalanceTimestamp` (string, required)
    DB write time of the latest contributing accounting entry (ISO-8601) — not on-chain block time.
    Example: 2026-08-21T14:27:15.03518Z

## Response 201 headers (application/json):

  - `Content-Disposition` (string)
    Attachment filename.
    Example: attachment; filename="position_report_5cd224fe-193e-8bce-c94c-c6c05245e2d1_2026-08-21.csv"

  - `X-Export-Id` (string)
    Export UUID (same value as metadata.exportId).

## Response 400:

  - `400` (unknown)
    Invalid value for: domainId, asOfTimestamp (must be ISO-8601, not in the future), format, vaultIds, tickerIds, accountIds, includeChildDomains, includeZeroBalances. Or 'Invalid query parameters for balance lookup' (single string message) when the accounting service rejects the query.

## Response 400 fields (application/json):

  - `statusCode` (number, required)
    HTTP status code.

  - `message` (any, required)
    Client-safe error message. Validation errors (400) return an array of messages.

  - `error` (string)
    HTTP error name.

## Response 401:

  - `401` (unknown)
    One of: missing bearer token; invalid or expired JWT.

## Response 401 fields (application/json):

  - `statusCode` (number, required)
    HTTP status code.

  - `message` (any, required)
    Client-safe error message. Validation errors (400) return an array of messages.

  - `error` (string)
    HTTP error name.

## Response 403:

  - `403` (unknown)
    User has no profile in the target domain with read access to 'accounts'. With includeChildDomains, each child domain is verified individually.

## Response 403 fields (application/json):

  - `statusCode` (number, required)
    HTTP status code.

  - `message` (any, required)
    Client-safe error message. Validation errors (400) return an array of messages.

  - `error` (string)
    HTTP error name.

## Response 413:

  - `413` (unknown)
    One of: 'Export spans {n} domains, exceeding the maximum of 100. Remove includeChildDomains or narrow the scope.'; 'Export exceeds maximum of 100000 balance records. Add ticker or account filters to narrow the result set.'

## Response 413 fields (application/json):

  - `statusCode` (number, required)
    HTTP status code.

  - `message` (any, required)
    Client-safe error message. Validation errors (400) return an array of messages.

  - `error` (string)
    HTTP error name.

## Response 429:

  - `429` (unknown)
    One of: Export already in progress (same parameters within 60s); Maximum concurrent exports reached (2 per user).

## Response 429 fields (application/json):

  - `statusCode` (number, required)
    HTTP status code.

  - `message` (any, required)
    Client-safe error message. Validation errors (400) return an array of messages.

  - `error` (string)
    HTTP error name.

## Response 502:

  - `502` (unknown)
    One of: 'Upstream accounting service is unavailable. Please retry.'; 'Gas station service is unavailable'; 'Omnibus service is unavailable' / 'Omnibus service returned inconsistent data' (when omnibus support is enabled). The export fails rather than returning rows with incorrect classification — retry once the upstream is reachable.

## Response 502 fields (application/json):

  - `statusCode` (number, required)
    HTTP status code.

  - `message` (any, required)
    Client-safe error message. Validation errors (400) return an array of messages.

  - `error` (string)
    HTTP error name.

