Skip to main content
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 statusMeaning
activeUsable for sends and receipts.
suspendedTemporarily blocked.
closedTerminated.
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.

​
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.

​
Funding a wallet

A wallet can receive funds in three ways:
MethodHow it works
Direct crypto transferSend crypto to the wallet’s address.
Virtual accountFiat deposited to the customer’s assigned bank account number auto-converts to crypto.
Deposit addressCrypto 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 /accounts/{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).

​
Key operations

OperationEndpoint
Create a walletPOST /customers/{id}/wallets (body: asset, chain)
List a customer’s walletsGET /customers/{id}/wallets
Get a wallet balanceGET /wallets/{id}/balance
List wallet transactionsGET /accounts/{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