Skip to content

Internal transfers move value between virtual accounts inside the same omnibus structure. These transfers are off-chain ledger operations. They do not create blockchain transactions, do not require vault signing, and do not pay transaction fees.

Key behavior

Intra-omnibus transfers are fast because they update virtual account balances in the Accounting Service instead of moving funds on-chain.

Transfer flow

Internal transfers are asynchronous. Omnibus accepts the request, durably persists the operation, and returns 202 Accepted with status: "PENDING" immediately. A workflow then validates the transfer, reserves the amount, and records the entry in the Accounting Service. Poll the operation for the terminal status.

Accounting ServiceOmnibus ServiceAccounting ServiceOmnibus ServiceClientRequest internal transfer (Idempotency-Key)Persist operation202 Accepted, status PENDINGValidate source, destination, ledger, and lock stateReserve amountRecord cross-account entrySource debited, destination creditedPoll transfer by operationIdTerminal status (COMPLETED or FAILED)Client
Accounting ServiceOmnibus ServiceAccounting ServiceOmnibus ServiceClientRequest internal transfer (Idempotency-Key)Persist operation202 Accepted, status PENDINGValidate source, destination, ledger, and lock stateReserve amountRecord cross-account entrySource debited, destination creditedPoll transfer by operationIdTerminal status (COMPLETED or FAILED)Client

Validation

Omnibus validates that:

  • The source and destination virtual accounts belong to the same omnibus structure.
  • The source virtual account is not locked.
  • The omnibus structure is not locked.
  • The omnibus structure supports the asset and ledger.
  • The source virtual account has enough available balance after subtracting local reservations.
  • The transfer does not require cross-chain movement.

No notarization

Internal transfers do not move blockchain assets and cannot directly lose on-chain funds. For that reason, clients do not submit them as custody intents, and custody policies do not notarize them.

This differs from a withdrawal or same-instance transfer that leaves the omnibus wallet. Custody policies still govern those on-chain operations.

Governance considerations

Omnibus does not add a separate permission system for tenants or virtual accounts. Customer integrations decide which users can operate which tenants and virtual accounts.

If your organization needs approval workflows for intra-omnibus transfers, implement that governance outside the custody notary. Complete the approval workflow before the API call records the internal transfer.

Procedures

To create and track internal transfers, see Create and track internal transfers in the API procedures, or Transfer between virtual accounts in the console procedures.

Operational notes

  • Internal transfers do not require on-chain fees, so the host virtual account and Gas Station are excluded from this flow.
  • Omnibus does not perform compliance screening because no blockchain transaction occurs.
  • Use operation history and virtual account statements for audit and customer reporting.
  • Use Withdrawals when funds need to leave the omnibus wallet.

Withdrawals

Balances