# Generate an Omnibus Position Report (a domain's omnibus pool and its breakdown)

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

## Security:

  - `bearer` (unknown)
    http bearer JWT

## Request fields (application/json):

  - `domainId` (string, required)
    Domain UUID whose omnibus structure to export

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

  - `tenantIds` (array)
    Filter by virtual account (tenant) UUIDs. Filters virtual-account rows and their deposit wallets; the omnibus wallet row is always kept.

  - `tickerIds` (array)
    Filter by ticker 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 per-accountType control totals.

  - `metadata.exportId` (string, required)
    Unique identifier of this export. Also returned in the X-Export-Id header.
    Example: ecca7eb1-a2f3-4351-bf46-e4f9e8f55272

  - `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-31T08:28:26.767Z

  - `metadata.filters` (object, required)
    Echo of the request filter parameters.
    Example: {"domainId":"c73e9e5e-e803-4dc0-93c5-be71c3396ae9","asOfTimestamp":"2026-08-31T08:27:21.2980000+00:00","includeZeroBalances":true}

  - `metadata.asOfTimestamp` (string, required)
    Echoed from the request (ISO-8601).

  - `metadata.recordCount` (number, required)
    Number of data rows — one per (account, ticker).
    Example: 4

  - `metadata.controlTotals` (object, required)
    Reconciliation control totals, strictly per accountType — never summed across types (the omnibus wallet's balance IS the pool backing the virtual rows; a grand total would double-count by construction). Sums span all tickers, so they are integrity checksums rather than balances; per-ticker reconciliation is done from the rows.

  - `metadata.controlTotals.omnibus` (object, required)
    Totals over the 'omnibus' (pool wallet) rows.

  - `metadata.controlTotals.omnibus.recordCount` (number, required)
    Number of rows of this accountType.
    Example: 2

  - `metadata.controlTotals.omnibus.availableBalance` (string, required)
    Signed BigNumber sum across all tickers.
    Example: 18.9998

  - `metadata.controlTotals.omnibus.reservedBalance` (string, required)
    Signed BigNumber sum across all tickers.
    Example: 0

  - `metadata.controlTotals.omnibus.quarantineBalance` (string, required)
    Signed BigNumber sum across all tickers.
    Example: 0

  - `metadata.controlTotals.omnibus.feeBalance` (string, required)
    Signed BigNumber sum across all tickers.
    Example: 1.0002

  - `metadata.controlTotals.omnibus.confiscationBalance` (string, required)
    Signed BigNumber sum across all tickers.
    Example: 0

  - `metadata.controlTotals.omnibus.totalBalance` (string, required)
    Signed BigNumber sum across all tickers.
    Example: 18.9998

  - `metadata.controlTotals.depositWallet` (object, required)
    Totals over the 'deposit wallet' rows.

  - `metadata.controlTotals.virtualAccount` (object, required)
    Totals over the 'virtual account' (tenant) rows.

  - `data` (array, required)
    One row per (account, ticker) across the three row kinds. Rows are Accounting-driven: never-funded tenants produce no rows; funded-then-drained tenants appear with total 0 under includeZeroBalances. Per-ticker reconciliation: Σ virtual-account availableBalance equals the omnibus wallet row's totalBalance (net of in-flight sweeps).

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

  - `data.domainName` (string, required)
    Domain display name.
    Example: TEST_SG_SUB_DOMAIN

  - `data.accountType` (string, required)
    Row kind: 'omnibus' (the pool wallet), 'deposit wallet' (a tenant's on-chain deposit wallet), or 'virtual account' (a tenant's off-chain claim on the pool).
    Example: virtual account

  - `data.accountId` (string, required)
    Unified row identity together with accountType: the custody accountId on 'omnibus' and 'deposit wallet' rows, the tenantId on 'virtual account' rows — identical to the Accounting Service account identity. Joining to custody data requires filtering accountType IN ('omnibus','deposit wallet'); virtual-row ids resolve only in the Accounting/Omnibus services.

  - `data.accountName` (string, required)
    Custody account alias on on-chain rows; tenant alias on virtual rows.
    Example: SG_OMNIBUS-host

  - `data.mappedVirtualAccountId` (string, required)
    Owning tenantId — populated on 'deposit wallet' rows only (the deposit-wallet → virtual-account ownership edge). Empty on omnibus and virtual rows.

  - `data.isHost` (boolean, required)
    True on the host tenant row — the catch-all tenant absorbing untagged direct deposits and pool-side costs; its balance may be negative (fee debt) and is never filtered.

  - `data.parentOmnibusAccountId` (string, required)
    Omnibus wallet custody accountId; empty on the 'omnibus' row itself.

  - `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.ledgerName` (string, required)
    Blockchain network name as configured by the operator.
    Example: XRPL Testnet August 2024

  - `data.availableBalance` (string, required)
    Available balance — the headline number for virtual rows. Signed BigNumber string in display units, passed through from Accounting unmodified.
    Example: -1.000200

  - `data.reservedBalance` (string, required)
    Reserved balance (in-flight outbound on custody rows). Passed through from Accounting; 0 in practice on virtual rows (Accounting carries no tenant holds).
    Example: 0.000000

  - `data.quarantineBalance` (string, required)
    Quarantined balance (compliance holds on custody rows). Passed through from Accounting; 0 in practice on virtual rows.
    Example: 0.000000

  - `data.feeBalance` (string, required)
    Cumulative fees bucket (informational — not a component of totalBalance). Itemizes the host tenant's absorbed network fees and reserves.
    Example: 1.000200

  - `data.confiscationBalance` (string, required)
    Cumulative confiscation bucket (informational — not a component of totalBalance).
    Example: 0.000000

  - `data.totalBalance` (string, required)
    Total balance = available + reserved + quarantine. Signed; the host tenant may be negative.
    Example: -1.000200

  - `data.ledgerBalanceTimestamp` (string, required)
    DB write time of the latest contributing accounting entry (ISO-8601) — not on-chain block time.
    Example: 2026-08-25T10:57:46.932669Z

## Response 201 headers (application/json):

  - `Content-Disposition` (string)
    Attachment filename.
    Example: attachment; filename="omnibus_position_report_c73e9e5e-e803-4dc0-93c5-be71c3396ae9_2026-08-31.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, tenantIds, tickerIds, 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'.

## 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 404:

  - `404` (unknown)
    Omnibus support is not enabled for this environment.

## Response 404 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)
    Export exceeds the maximum of 100000 balance records. Add ticker or tenant 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 422:

  - `422` (unknown)
    The domain has no omnibus structure. An empty file is indistinguishable from all-zero balances and is never returned.

## Response 422 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: 'Omnibus service is unavailable'; 'Omnibus service returned inconsistent data'; 'Omnibus structure changed during export. Please retry.' (a tenant was created while the hierarchy was being read — retry sees the settled state); 'Upstream accounting service is unavailable. Please retry.'. The export fails rather than returning rows with incorrect classification.

## 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.

