Set up an omnibus account as a partner wallet

An omnibus account is a business customer that represents your company, plus the custodial wallets that customer owns. It gives your company its own funds in OMS, held apart from your end users’ balances. Each wallet has its own onchain address, so you can keep funds separated by asset, network, or purpose while they all belong to one entity. Use an omnibus account to:

Hold company funds. Keep treasury, fee revenue, and operating float in wallets your company owns.
Separate funds by purpose. Give settlement, payouts, and fees their own wallets and addresses, and move funds between them as needed.
Receive funds from your customers. Move funds from your end users’ wallets into a wallet your company controls, for example to consolidate deposits before settlement.

Transfers between custodial wallets in your project settle as internal ledger movements. Nothing moves onchain, and there is no network fee.

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. Request the cryptoCustody endorsement so the customer can hold custodial wallets.

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,
  "endorsements": ["cryptoCustody"]
}

Store the returned cst_ ID, and wait for the cryptoCustody endorsement to become active before you create wallets. See Customer onboarding for endorsements and verification.

Step 2: Create the wallets

Create a custodial wallet for each asset, network, and purpose you need. Each wallet holds one asset on one chain and has its own onchain address.

POST /v0.13/customers/cst_omnibus.../wallets
Authorization: Bearer {accessToken}
Idempotency-Key: wlt-omnibus-usdc-polygon
Content-Type: application/json

{
  "asset": "usdc",
  "chain": "polygon"
}

Store each wallet’s wlt_ ID and address. To fund a wallet from outside OMS, send USDC or USDT to its address.

Create one wallet per asset, for example one for USDC and one for USDT. Transfers into each wallet then stay in the same asset, and no swap is needed.

Move funds between your own wallets

Funds leave a custodial wallet through a quote and a transaction. When the source and destination wallets belong to the same customer, reference the destination directly by its wlt_ ID.

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

{
  "customerId": "cst_omnibus...",
  "source": {
    "type": "walletCrypto",
    "details": { "id": "wlt_settlement...", "asset": "usdc", "network": "polygon" },
    "amount": "10000.00"
  },
  "destination": {
    "type": "walletCrypto",
    "details": { "id": "wlt_payouts...", "asset": "usdc", "network": "polygon" }
  }
}

Confirm the quote with POST /transactions:

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

The transfer is complete when the transaction reaches completed.

Move funds from a customer’s wallet to the omnibus account

A wallet owned by a different customer cannot be referenced by its wlt_ ID. Register the omnibus wallet as an external account under the sending customer instead, then quote to it. OMS still settles the transfer as an internal ledger movement because both wallets are custodial wallets in your project. Repeat the registration once for each customer that sends to the omnibus account.

Create a counterparty under the sending customer 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.

Quote and confirm the transfer

Use the customer’s wallet as the source and the omnibus external account as the destination, then confirm with POST /transactions:

POST /v0.13/quotes

{
  "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" }
  }
}

You trigger these transfers; OMS does not run them on a schedule. To automate them, listen for transaction.statusChanged and create a transfer when a deposit to the customer’s wallet reaches completed. To forward every deposit without a quote, point a deposit address at the omnibus external account.

Reconcile balances

Track movements with transaction events. Subscribe to transaction.statusChanged and match events where the source or destination is the wlt_ ID of the wallet you are reconciling. OMS does not emit separate balance events.
Treat reported balances as spendable. Balances returned by GET /wallets/{walletId}/balance and the customer wallet endpoints never include 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

Set up an omnibus account as a partner wallet

Step 1: Create the business customer

Step 2: Create the wallets

Move funds between your own wallets

Move funds from a customer’s wallet to the omnibus account

Reconcile balances

​Step 1: Create the business customer

​Step 2: Create the wallets

​Move funds between your own wallets

​Move funds from a customer’s wallet to the omnibus account

​Reconcile balances

​Related

Step 1: Create the business customer

Step 2: Create the wallets

Move funds between your own wallets

Move funds from a customer’s wallet to the omnibus account

Reconcile balances

Related