Wallets

Wallets are custodial stablecoin accounts. OMS manages the private keys, with no user signing, no wallet SDKs, and no blockchain interactions required from your application. All operations are server-to-server API calls. Each wallet holds a single asset on one chain (USDC on Polygon by default). A wallet is the source or destination for every transaction. To hold more than one asset, create a wallet per asset and chain under the same customer.

This page covers the custodial wallet resource of the Payments API. If your product needs users to control their own keys on-chain (consumer apps, agentic flows), use OMS non-custodial wallets. The two models can be combined in a single product.

Object

{
  "id": "wlt_...",
  "object": "wallet",
  "customerId": "cst_...",
  "type": "internal",
  "status": "active",
  "address": "0x7B3a9F2c4D1eA8bF6390cE5d2B7fA104C8e3D9b1",
  "asset": "usdc",
  "chain": "polygon",
  "blockchainAsset": {
    "protocol": "evm",
    "chainId": "137",
    "tokenId": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359"
  },
  "createdAt": "2026-01-15T10:31:00Z",
  "updatedAt": "2026-01-15T10:31:00Z"
}

The address field is the wallet’s on-chain address. It is read-only and assigned at creation. type is internal for OMS-managed wallets or external for wallets held outside OMS. chain is the canonical chain name (for example, polygon), and blockchainAsset carries the resolved on-chain identity: protocol, chainId, and tokenId.

Wallet status	Meaning
`active`	Usable for sends and receipts.
`suspended`	Temporarily blocked.
`closed`	Terminated.

At launch, wallets are custodial only: a single asset on one chain. Provisioning is scoped per asset and chain, so hold multiple assets by creating one wallet each under the same customer.

Create a wallet

POST /customers/{id}/wallets provisions a wallet for a customer for the requested asset and chain, and returns the created wallet.

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

Pass an Idempotency-Key header to safely retry without provisioning duplicates.

POST /customers/{id}/wallets and GET /customers/{id}/wallets are deprecated. Responses carry Deprecation: true and a Sunset header. Migrate to POST /wallets for creation and GET /wallets?customerId=... for listing. The flat list carries only the common wallet fields; asset, chain, and address require a follow-up GET /wallets/{id} per row. The flat list also does not sync live with the custody provider on every request.

Associate an embedded wallet

POST /customers/{customerId}/wallets/associate links an existing embedded (WaaS) wallet to a customer so subsequent operations reference it like any other wallet. The wallet is identified by a WaaS ID token in the request body: the token’s subject is the wallet ID, so the wallet ID is never passed directly, and the token’s audience must be the authenticated project. The response returns the associated wallet.

Balance

Read a wallet’s current balance with GET /wallets/{id}/balance. The response includes the display balance and its estimated value; pass estimatedBalanceCurrencyCode to value the balance in a currency other than USD (the default).

{
  "data": {
    "id": "wlt_...",
    "customerId": "cst_...",
    "address": "0x7B3a...D9b1",
    "asset": "usdc",
    "chain": "polygon",
    "currencyName": "USD Coin",
    "balance": "1234.56",
    "estimatedBalanceValue": "1234.56",
    "blockchainAsset": {
      "protocol": "evm",
      "chainId": "137",
      "tokenId": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359"
    },
    "updatedAt": "2026-01-15T10:31:00Z"
  }
}

For the customer’s total balance across every wallet and asset, use GET /customers/{id}/balance. See Customers.

Fiat wallet balance

A fiat wallet’s balance renders as a fixed-point USD decimal string with exactly two decimal places: "0.00" for a never-funded wallet, "500.00" when funded, "-25.00" when overdrawn. The key is present on every 200, never omitted, never null. Crypto wallets keep per-asset decimal scaling, so a USDC balance still renders trimmed (for example, "1234.56"). When the wallet provider returns a successful balance response but omits an entry for a given wallet, estimatedBalanceValue defaults to "0.00" so a zero-balance fiat wallet keeps a stable response shape.

Funding a wallet

A wallet can receive funds in three ways:

Method	How it works
Direct crypto transfer	Send crypto to the wallet’s `address`.
Virtual account	Fiat deposited to the customer’s assigned bank account number auto-converts to crypto.
Deposit address	Crypto sent to a monitored address auto-routes to the configured destination.

A direct transfer to the address credits the wallet balance. Virtual accounts and deposit addresses are the flows where OMS auto-creates a transaction in response to incoming funds.

Transaction history

GET /wallets/{id}/transactions returns a wallet’s transaction history, most recent first, with cursor-based pagination and optional transactionType, since, and until filters. The id path parameter accepts a wallet ID (wlt_ prefix).

GET /wallets/{id}/transactions is deprecated. Responses carry Deprecation: true and a Sunset header. Migrate to GET /transactions?walletId={id}, which returns business transactions (source, destination, pricing, status). Note that the deprecated endpoint returns raw ledger entries (credit, debit, hold, release with balanceAfter) and includes reconciliation-only entries that have no counterpart on the transactions endpoint; if you rely on those raw entries, plan the migration accordingly.

Key operations

Operation	Endpoint
Create a wallet	`POST /customers/{id}/wallets` (body: `asset`, `chain`)
List a customer’s wallets	`GET /customers/{id}/wallets`
Get a wallet balance	`GET /wallets/{id}/balance`
List wallet transactions	`GET /wallets/{id}/transactions`

Programmatic wallet creation via POST /wallets with an explicit custodyType (custodial or embedded) is coming in an upcoming release. Today, provision wallets under a customer with POST /customers/{id}/wallets.

Virtual accounts: assign a bank account number that auto-funds a destination
Deposit addresses: set up a monitored crypto address that routes to a destination
Transactions: move funds out of a wallet via crypto, bank transfer, or cash

Overview

Introduction

Fundamentals

Object

Create a wallet

Associate an embedded wallet

Balance

Fiat wallet balance

Funding a wallet

Transaction history

Key operations

​Object

​Create a wallet

​Associate an embedded wallet

​Balance

​Fiat wallet balance

​Funding a wallet

​Transaction history

​Key operations

​Related

Object

Create a wallet

Associate an embedded wallet

Balance

Fiat wallet balance

Funding a wallet

Transaction history

Key operations

Related