Setup and governance

Set up Omnibus in an existing Ripple Custody domain. The domain provides the vault assignment, user roles, account policies, compliance controls, and transaction governance that apply to the omnibus wallet and deposit wallets.

Before creating an omnibus structure, confirm that you have:

• An existing domain for the omnibus structure.
• A vault assigned to the domain.
• Tickers and ledgers configured for the assets you intend to support.
• System-signed intents activated for the deployment.
• A system-signed policy that gives the Omnibus service access to required automated operations.
• Gas Station configured for just-in-time fee funding if non-native token sweeps require sponsored gas.
• Monitoring and balance-operations ownership defined.

For domain and policy concepts, see Domains and Policies. For the system-signed intent activation sequence, see System-signed intent configuration.

Omnibus supports one omnibus structure per domain. Create all related custody accounts in that domain:

• The omnibus wallet.
• Virtual accounts, including the host virtual account.
• Deposit wallets created for virtual accounts.

Using a dedicated domain for each omnibus structure keeps policy scope, audit, monitoring, and support boundaries clearer.

Omnibus uses system-signed intents for automated operations that do not require a user to sign each request. The Omnibus service still authenticates as a service caller, and policy conditions should identify that service caller with context.submitter.subject or context.submitter.custodyRoles.

Before Omnibus submits system-signed automation intents:

1. Gateway must be configured for system-signed intents.
2. The active Gateway system signing public key must be registered in Notary with purpose: "SystemSignatures".
3. NOTARY_SYSTEM_SIGNED_INTENTS_ENABLED must be set to enabled: true.
4. A matching policy with intentOrigin: "SystemSigned" must allow the Omnibus service to submit the required intent types.

System-signed intent configuration is enabled by default at deployment level in current release packages, but system-signed traffic remains disabled until the Notary key registration, system property, and policy are in place.

For the full deployment and activation sequence, see System-signed intent configuration.

The Omnibus service needs a manually created policy that matches its system-signed automation intents:

Use intentOrigin: "SystemSigned" and specify only the required intent types:

{
  "intentTypes": [
    "v0_CreateAccount",
    "v0_CreateTransactionOrder",
    "v0_AddAccountLedgers"
  ],
  "intentOrigin": "SystemSigned",
  "condition": {
    "expression": "context.submitter.custodyRoles.includes('omnibus-service')",
    "type": "Expression"
  }
}

Use the service role or subject value that your deployment issues to the Omnibus service. The role name (omnibus-service above) must match a value in the service caller's custody_roles token claim. If the policy includes an approval workflow, user-signed approvers must satisfy it; the service submitter does not count as a user approval.

Creating an omnibus structure has two phases:

1. Create the omnibus wallet: The user initiates the Omnibus creation flow with alias, vaultId, and keyStrategy, plus optional ledger, description, custom-property, ignored-account, and Gas Station settings. Omnibus validates the domain, prepares a custody account creation intent, and returns the omnibus record with an unsigned Custody intent payload. The client signs that payload and submits it to POST /v1/intents.
2. Set up automation: Omnibus creates the host virtual account, initializes Accounting Service state, configures the omnibus wallet to skip quarantine for intra-domain sweeps, and checks Gas Station sponsorship. Omnibus does not validate the system-signed automation policy: you create that policy upstream, and no step of the creation flow checks it. Verify it through your normal governance process before treating the omnibus structure as operational.

Omnibus can use Gas Station for non-native token sweeps and withdrawals on supported Solana, XRPL, and EVM networks. Gas Station provides native gas to the deposit wallet or omnibus wallet that needs to broadcast the token transaction.

For native asset withdrawals, the host virtual account is responsible for the native network transaction fee in Omnibus accounting. Fee compensation or reimbursement records for Gas Station-funded non-native withdrawal gas depend on the final Omnibus accounting behavior for your release.

Plan the sponsorship model before creating the omnibus structure:

• Domain-wide sponsorship is simpler when all omnibus-related accounts need sponsorship.
• Account-level sponsorship limits sponsorship to selected accounts.
• Use just-in-time sponsorship. Fund the sponsor account, but do not pre-fund each Omnibus deposit wallet.
• Add the Gas Station account ID to the Omnibus ignored-account list at creation so native-token funding transactions are not processed as customer deposits.

When Omnibus configures the omnibus wallet for intra-domain sweeps, it uses the account compliance configuration API to set skipQuarantineFrom to Domain. This lets sweeps from deposit wallets arrive at the omnibus wallet without a second quarantine cycle. External deposits to deposit wallets still follow the normal confirmation and quarantine-release flow.

For configuration steps, see Manage a gas station with the API.

Omnibus supports lock states at two levels:

Use virtual account locks for operational holds, incident response, or customer lifecycle events. Locks are not a replacement for custody policies on on-chain withdrawals.

When an operator adds a ledger to the omnibus wallet, Omnibus propagates that ledger to existing deposit wallets. This lets new deposits use the same ledger coverage as the omnibus wallet.

Ledger propagation is one-way:

• Add ledgers to the omnibus wallet.
• Let Omnibus add missing ledgers to deposit wallets.
• Avoid adding ledgers directly to deposit wallets.

If a deposit wallet has a ledger that the omnibus wallet does not support, sweeps on that ledger can fail until an operator resolves the mismatch.