Omnibus Position Report

The Position Report covers the on-chain custody layer only. An omnibus structure adds a second, off-chain layer: virtual accounts that track each tenant's share of the pooled funds. The Omnibus Position Report serves that layer. It reports the omnibus pool and its per-tenant breakdown in one file, with the mapping columns you need to tie a deposit wallet to its virtual account and every row to its parent omnibus wallet.

The omnibus wallet and deposit wallets appear in both reports on purpose. Those shared on-chain rows are the bridge that lets an auditor tie the two files together.

To generate an Omnibus Position Report, you need the following:

POST /v1/exports/position/omnibus

The service generates a balance snapshot for the omnibus structure in the target domain as of asOfTimestamp. The report covers one domain. It has no includeChildDomains option, because each omnibus structure belongs to exactly one domain.

Send the request body as application/json.

curl -X POST "https://{host}/v1/exports/position/omnibus" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "domainId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "asOfTimestamp": "2026-09-15T23:59:59Z",
    "tenantIds": ["1559bf54-5343-476e-b720-29edfee0edd7"],
    "includeZeroBalances": false,
    "format": "CSV"
  }'

The service returns the report as a single file with a Content-Disposition attachment header and an X-Export-Id header for tracing. For the response structure of each format, see Output formats.

Each row represents one account-and-asset balance, as in the Position Report. The report contains three kinds of row, distinguished by accountType:

Row identity is always accountType plus accountId. The accountId value is the same identity the Accounting Service uses for the balance: a custody account ID on on-chain rows and a tenant ID on virtual account rows. When you join accountId to custody account data, filter on accountType in (omnibus, deposit wallet) first. Virtual account IDs resolve only through the Omnibus API /tenants resources.

Each mapping column has one role, and every relationship appears once. The deposit-wallet-to-virtual-account link lives on the deposit wallet row, because that's the direction reconciliation reads it: funds arrive on a wallet, and the question is who owns them.

The service builds rows from the Accounting Service's balance records and uses the omnibus structure only to classify and enrich them. This has several consequences:

• A virtual account that has never been funded produces no row, under any setting. Creating a tenant writes no balance record, so there is no position to report. For the full roster of virtual accounts, including never-funded ones, use the Omnibus API.
• A virtual account that was funded and later drained to zero has a row, with zero balances and a populated ledgerBalanceTimestamp, when includeZeroBalances is true.
• A deposit wallet row can appear before its virtual account has a row, for example when a deposit sits in quarantine awaiting its first sweep. The mapping is still visible through the wallet row's mappedVirtualAccountId.
• The host virtual account is always included, and its balance can be negative. The host absorbs fee compensation, so it can run a fee debt. The service never filters it out, because the reconciliation below depends on it.
• The report includes all virtual accounts regardless of status. A locked virtual account with a balance still appears.
• Row order isn't part of the contract. Sort on accountType and accountId downstream if you need a stable order.

For each asset, the sum of availableBalance across the virtual account rows equals the omnibus wallet's totalBalance. The negative host balance is part of that sum. For example, a pool with two virtual accounts at 20.000000 and -1.000200 reconciles to an omnibus wallet total of 18.999800.

Compute this check from the rows of one file, per ticker. Don't use the control totals for it: a control total can span several assets with different decimal scales, so it's an integrity checksum, not a per-asset figure. See Control totals.

Column order is a fixed contract.

The metadata header carries control totals per account type, never a grand total across types. The omnibus wallet's balance is the pool that backs the virtual account rows, so a cross-type sum would double-count by construction.

Each account type carries a record count and the signed sum of each of the six balance columns:

"controlTotals": {
  "omnibus": {
    "recordCount": 3,
    "availableBalance": "41.9868",
    "reservedBalance": "0",
    "quarantineBalance": "0",
    "feeBalance": "0.015",
    "confiscationBalance": "0",
    "totalBalance": "41.9868"
  },
  "depositWallet": { "recordCount": 1, "...": "..." },
  "virtualAccount": { "recordCount": 4, "...": "..." }
}

To verify a file, group the rows by accountType, re-sum each balance column, and compare the results and the record counts against the header. For how control totals work across every report, see Control totals.

If the service returns an error, the response body is a client-safe JSON object and never exposes internal details. Common cases for the Omnibus Position Report include:

• 400: A required field is missing, a UUID or timestamp is malformed, asOfTimestamp is in the future, or a filter array exceeds 1,000 entries.
• 401: The JWT is missing or invalid.
• 403: You lack read access to accounts in the target domain.
• 404: Omnibus support isn't enabled for this environment. See Omnibus support.
• 413: The result would exceed 100,000 rows. Narrow the scope with tenantIds or tickerIds, then request again.
• 422: The domain has no omnibus structure. The service returns this error rather than an empty file, because an empty file would be indistinguishable from a structure whose balances are all zero.
• 429: A duplicate request within 60 seconds while a previous export is still processing, or you already have 2 exports processing.
• 502: The Accounting Service or the Omnibus service is unavailable. The service fails the request rather than emit misclassified rows.

If the omnibus structure changes while the service reads it, for example because someone creates a virtual account mid-export, the export fails with a retryable error instead of returning rows that match no single point in time. Request the report again.

For the full list, see Error responses.