Work with omnibus accounts

Goal

Set up a customer with an omnibus account and use it end-to-end: create the account, fund it, read its balance, and move funds both within your platform (off-chain) and to external wallets (on-chain). If you’re not familiar with the two custody models, read Crypto custody first.

How omnibus custody works

With omnibus accounts, customer funds are pooled in a Bastion custody vault. Bastion tracks each account’s balance on a secure double-entry ledger. This differs from segregated accounts, where each customer holds funds at their own dedicated on-chain addresses.

Characteristic	Omnibus (`OMNIBUS`)
How assets are held	Pooled in a custody vault; per-account balances tracked on Bastion’s internal ledger
Balance model	Chain-agnostic: one USDC balance regardless of chain
Off-chain transfers	Instant, fee-free transfers between omnibus accounts on the same platform
On-chain withdrawals	Supported on Solana and EVM chains, with gas sponsored by Bastion

Both account types are fully custodial under Bastion’s US regulated licensing, and your platform uses the same APIs either way.

Key entities

Entity	Description
Your platform	The product integrating Bastion’s APIs
Customer	An individual or business your platform has onboarded (KYC/KYB-verified)
Identity	The customer’s record in Bastion, used for compliance and permissions
Account	An omnibus account linked to the identity. Its balance lives on Bastion’s internal ledger.

Flow overview

Onboard the customer and wait for their identity to become ACTIVE.
Create an account with type: OMNIBUS.
Fund the account via on-ramp, crypto deposit, or off-chain transfer.
Check the chain-agnostic balance.
Move funds off-chain (within your platform) or on-chain (external withdrawals).

Prerequisites

You have access to your dashboard
You’ve created an API key
You’ve registered a webhook

Step 1 – onboard the customer

Omnibus accounts follow the same onboarding flow as any other account. Create an identity, submit KYC or KYB data, and track status until the identity is ACTIVE:

Accounts cannot be created until the identity’s status is ACTIVE.

Step 2 – create an omnibus account

Call POST /v2/accounts with type set to OMNIBUS.

The type field defaults to SEGREGATED. You must set type: "OMNIBUS" explicitly to create an omnibus account.

Use a unique request_id (UUID) as an idempotency key. Reuse the same request_id on retries to avoid duplicate accounts. Request

POST /v2/accounts
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "request_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "identity_id": "01HZX8QK9VM5T9JY8ZQXQZQXQZ",
  "type": "OMNIBUS"
}

The response returns the new account. Capture these fields:

Field	Meaning
`id`	The account ID. Store it alongside your internal customer record.
`type`	`OMNIBUS`, confirming the custody model
`status`	The account’s status, derived from its parent identity state (`ACTIVE` when ready)

If the identity has not passed compliance and jurisdiction checks, the request returns HTTP 422.

Step 3 – fund the account

An omnibus account can receive funds in three ways:

Funding method	How it works
On-ramp conversion	Convert fiat to stablecoin into the account. See On-ramp.
Crypto deposit	Receive crypto from an external wallet or exchange. See Receive crypto deposits.
Off-chain transfer	Receive an instant transfer from another omnibus account on your platform.

In all cases, Bastion credits the balance and delivers a webhook when funds arrive. For deposits, that is the deposit_v2 event. Off-chain deposits from another account on your platform arrive with source_type: ACCOUNT and source_account_id identifying the sender.

Step 4 – check the balance

GET /v2/accounts/{account_id}/balances
Authorization: Bearer YOUR_API_KEY

Response:

{
  "balances": [
    {
      "symbol": "USDC",
      "total": "975000000",
      "available": "975000000",
      "decimals": 6,
      "type": "OMNIBUS",
      "chain": "CHAIN_UNSPECIFIED"
    }
  ]
}

Omnibus balances differ from segregated balances:

Balances are chain-agnostic. The type field is OMNIBUS and chain is CHAIN_UNSPECIFIED. A customer holding USDC has one balance entry, regardless of which chains the funds arrived on. Segregated accounts instead return one entry per chain.
contract_address is omitted.

Balances are returned in atomic units as strings. Use the decimals field to convert to a human-readable amount (e.g., "975000000" with decimals: 6 = 975.00 USDC). The available field reflects the amount the customer can use for transfers or conversions. total may differ from available if funds are held for a pending operation.

Step 5 – move funds

Both transfer modes use the same endpoint, POST /v2/crypto/transfers. The destination field determines the mode.

Off-chain: send to another account on your platform

Off-chain transfers move funds instantly on Bastion’s internal ledger. There is no blockchain transaction, no gas fee, and no chain selection. Both sender and recipient must have omnibus accounts on the same platform.

{
  "request_id": "66f3b0b2-a25b-4e9d-a94b-fbcfa0720312",
  "account_id": "36hv3yZpsHt7pwgBZom5SXgURYz",
  "currency_symbol": "USDC",
  "amount": "25.00",
  "account_destination": {
    "account_id": "48jK9mLp2rSTuvW3xYzAaBbCcDd"
  }
}

Off-chain transfers settle immediately, with a status lifecycle of ACCEPTED → CONFIRMED / FAILED. For the full walkthrough, including webhook payloads and status handling, see Send crypto off-chain.

On-chain: withdraw to an external wallet

On-chain withdrawals send funds through the blockchain to any wallet address. Omnibus accounts support on-chain withdrawals on Solana and EVM chains, with gas sponsored by Bastion. Specify the destination address and chain:

{
  "request_id": "903c9e51-51af-4597-9174-0a93ca80dbac",
  "account_id": "36hv3yZpsHt7pwgBZom5SXgURYz",
  "currency_symbol": "USDC",
  "amount": "25.00",
  "address_destination": {
    "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "chain": "SOLANA_MAINNET"
  }
}

Because the omnibus balance is chain-agnostic, the customer’s full available balance can be withdrawn to any supported chain. On-chain transfers settle after block confirmation, with a status lifecycle of ACCEPTED → SUBMITTED → CONFIRMED / FAILED / CANCELED / DROPPED. For the full walkthrough, see Send crypto on-chain.

Step 6 – verify setup

Confirm the customer is fully ready:

Check identity status — GET /v2/identities/{identity_id} returns status: ACTIVE
Check the account — GET /v2/accounts/{id} returns type: OMNIBUS and status: ACTIVE
Check balances — GET /v2/accounts/{account_id}/balances shows the funded, chain-agnostic balance

Implementation notes

Recommendation	Details
Set `type` explicitly	`POST /v2/accounts` defaults to `SEGREGATED`. Always pass `type: "OMNIBUS"` when creating omnibus accounts.
Use idempotent request IDs	Provide a unique `request_id` (UUID) per account creation and per transfer. Reuse it on retries to avoid duplicates.
Display one balance per asset	Omnibus balances are chain-agnostic. Do not build per-chain balance UI for omnibus accounts.
Check `available` before sends	Confirm sufficient `available` balance before submitting a transfer. Surface insufficient-funds errors clearly in your UI.
Validate off-chain eligibility	Off-chain transfers require omnibus accounts on both sides, on the same platform. Ineligible destinations return HTTP 400.
Keep records in sync	Store `identity_id`, `account_id`, and `transfer_id` in your own system and reconcile via `submit_cryptocurrency_transfer_v2` and `deposit_v2` webhooks.

Getting Started

Concepts

Quickstarts

Compliance

Security

Bastion Dashboard

LLMs and MCP Server

Work with omnibus accounts

Goal

How omnibus custody works

Key entities

Flow overview

Prerequisites

Step 1 – onboard the customer

Step 2 – create an omnibus account

Step 3 – fund the account

Step 4 – check the balance

Step 5 – move funds

Off-chain: send to another account on your platform

On-chain: withdraw to an external wallet

Step 6 – verify setup

Implementation notes

​Goal

​How omnibus custody works

​Key entities

​Flow overview

​Prerequisites

​Step 1 – onboard the customer

​Step 2 – create an omnibus account

​Step 3 – fund the account

​Step 4 – check the balance

​Step 5 – move funds

​Off-chain: send to another account on your platform

​On-chain: withdraw to an external wallet

​Step 6 – verify setup

​Implementation notes

​Related documentation

Goal

How omnibus custody works

Key entities

Flow overview

Prerequisites

Step 1 – onboard the customer

Step 2 – create an omnibus account

Step 3 – fund the account

Step 4 – check the balance

Step 5 – move funds

Off-chain: send to another account on your platform

On-chain: withdraw to an external wallet

Step 6 – verify setup

Implementation notes

Related documentation