Set up an Omnibus account

An Omnibus account pools your users’ funds into one custodial wallet that your company controls. Each user keeps a named custodial wallet of their own, which acts as their sub-ledger: it has its own deposit address, so every deposit is attributed to a named user. You then sweep funds from those wallets into the Omnibus account, either by triggering each transfer or automatically as deposits land.

Concept	In OMS
Omnibus account	A custodial wallet owned by a business customer that represents your company
Named user sub-ledger	A custodial wallet owned by the user’s own customer record
Sweep	A transfer from a user’s wallet to the Omnibus account
Internal P2P	A transfer from one user’s wallet to another’s

Step 1: Create the business customer

Create one customer with type: business to represent your company. A business requires companyLegalName and email, and follows your project’s KYB policy.

POST /v0.13/customers
Authorization: Bearer {accessToken}
Idempotency-Key: cst-omnibus-001
Content-Type: application/json

{
  "type": "business",
  "companyLegalName": "Your Company Inc.",
  "email": "treasury@yourcompany.example",
  "externalId": "omnibus",
  "signedAgreement": true
}

Store the returned cst_ ID, and wait for the customer’s cryptoCustody endorsement to become active before you create wallets. If your project requires KYB, complete it first; see Onboard a business.

Step 2: Create the Omnibus wallets

Create a custodial wallet for the business customer for each asset and network you accept. Each wallet holds one asset on one network and has its own onchain address.

POST /v0.13/wallets
Authorization: Bearer {accessToken}
Idempotency-Key: 4b3a2c1d-0e9f-4a8b-9c7d-6e5f4a3b2c1d
Content-Type: application/json

{
  "customerId": "cst_omnibus...",
  "type": "custodial",
  "details": { "network": "polygon", "asset": "usdc" },
  "label": "Omnibus USDC"
}

Store each wallet’s wlt_ ID and address; you need the address in Step 4. If the response is 202, poll the operation in the Location header until it completes, then read the wallet. address is left out until the wallet has one.

Create one Omnibus wallet per asset, for example one for USDC and one for USDT. Each sweep then lands in a wallet of the same asset, and no swap is needed.

Step 3: Create a wallet for each user

Onboard each user as their own customer, then create their custodial wallets the same way as Step 2. See Customer onboarding for the full flow. Give each user their wallet’s address to deposit to. Every deposit is recorded against that user’s wallet before it is swept.

Step 4: Register the Omnibus account for each user

The Omnibus wallets belong to a different customer, so a user’s wallet cannot send to them by wlt_ ID. Register each Omnibus wallet as an external account under the user instead. Repeat this step once for each user.

Create a counterparty under the user’s customer record that represents your company:

POST /v0.13/counterparties

{
  "customerId": "cst_alice...",
  "entityType": "business",
  "businessName": "Your Company Inc."
}

POST /v0.13/external-accounts

{
  "owner": { "kind": "counterparty", "counterpartyId": "ctp_..." },
  "type": "walletExternal",
  "walletExternal": {
    "blockchainAddress": "0xOmnibusWalletAddress...",
    "networkFamily": "evm",
    "custodian": "OTHER",
    "otherCustodian": "OMS"
  },
  "label": "Omnibus account"
}

Store the returned ext_ ID and wait for the account to become active. An EVM address registered once is valid across every EVM chain.

Step 5: Sweep deposits into the Omnibus account

Choose how sweeps run. OMS does not sweep on a schedule: you either trigger each sweep or route deposits through a deposit address that forwards them.

Trigger sweeps yourself

Create a quote with the user’s wallet as the source and the Omnibus external account as the destination:

POST /v0.13/quotes
Authorization: Bearer {accessToken}
Idempotency-Key: qt-sweep-alice-001
Content-Type: application/json

{
  "customerId": "cst_alice...",
  "source": {
    "type": "walletCrypto",
    "details": { "id": "wlt_alice...", "asset": "usdc", "network": "polygon" },
    "amount": "250.00"
  },
  "destination": {
    "type": "walletExternal",
    "details": { "id": "ext_...", "asset": "usdc", "network": "polygon" }
  }
}

Confirm it with POST /transactions:

{ "quoteId": "qt_..." }

To automate this, listen for transaction.statusChanged and create a sweep when a deposit to a user’s wallet reaches completed.

Sweep automatically with deposit addresses

Create a deposit address for each user whose destination is the Omnibus external account, and give users the deposit address instead of their wallet address. Every deposit is then forwarded to the Omnibus account as it lands, with no quote step.

POST /v0.13/deposit-addresses

{
  "customerId": "cst_alice...",
  "expectedSourceAsset": "usdc",
  "expectedSourceNetwork": "polygon",
  "destination": {
    "type": "walletExternal",
    "details": { "id": "ext_...", "asset": "usdc", "network": "polygon" }
  }
}

A deposit address accepts one asset on one network. If you hold USDC and USDT Omnibus wallets, create one deposit address per asset for each user, each pointing at the Omnibus wallet of the matching asset. See Forward deposits to a wallet.

Send funds between users

A transfer from one user’s wallet to another’s follows the same pattern as a sweep. Register the recipient’s wallet address as a walletExternal external account under the sender, owned by a counterparty that represents the recipient, then quote from the sender’s wallet to that ext_ ID. Transfers between wallets owned by the same customer, such as moving funds between two Omnibus wallets, skip registration: reference the destination directly as walletCrypto with its wlt_ ID.

Reconcile balances

Track movements with transaction events. Subscribe to transaction.statusChanged and match events where data.resource.source.id or data.resource.destination.id is the wallet you are reconciling, or list them with GET /transactions?walletId=wlt_.... OMS does not emit separate balance events.
Treat reported balances as spendable. balances[] on GET /wallets/{walletId} never includes pending funds.
Wait for completed. A transaction changes a wallet’s balance only when it reaches completed.

Customer onboarding: create customers and custodial wallets
External accounts: register external wallets and counterparty-owned accounts
Deposit addresses guide: forward inbound deposits automatically
Receiving webhooks: verify and apply transaction.statusChanged deliveries

Overview

Introduction

Fundamentals

Step 1: Create the business customer

Step 2: Create the Omnibus wallets

Step 3: Create a wallet for each user

Step 4: Register the Omnibus account for each user

Step 5: Sweep deposits into the Omnibus account

Trigger sweeps yourself

Sweep automatically with deposit addresses

Send funds between users

Reconcile balances

​Step 1: Create the business customer

​Step 2: Create the Omnibus wallets

​Step 3: Create a wallet for each user

​Step 4: Register the Omnibus account for each user

​Step 5: Sweep deposits into the Omnibus account

​Trigger sweeps yourself

​Sweep automatically with deposit addresses

​Send funds between users

​Reconcile balances

​Related

Step 1: Create the business customer

Step 2: Create the Omnibus wallets

Step 3: Create a wallet for each user

Step 4: Register the Omnibus account for each user

Step 5: Sweep deposits into the Omnibus account

Trigger sweeps yourself

Sweep automatically with deposit addresses

Send funds between users

Reconcile balances

Related