OMS Custodial Wallets - Polygon Developer Docs

Custodial wallets are managed wallets where OMS holds and secures private keys on behalf of your customers. Your application makes server-to-server API calls with no user signing and no blockchain interaction. This model suits regulated financial products, enterprise deployments, and products where users should not be responsible for their own keys. There are two kinds. A crypto wallet (walletCrypto) holds one stablecoin on one network; to hold more than one asset or network, create one wallet each under the same customer. A fiat wallet (walletFiat) holds a USD balance at a partner bank. Both belong to a customer and act as sources and destinations in quotes and transactions.

When to use custodial wallets

Use case	Recommended
Regulated financial products (e.g., fintech, neobanks)	Yes
Enterprise deployments requiring managed key recovery	Yes
Users who should not self-custody	Yes
Consumer apps where users want full key ownership	Use non-custodial wallets instead

The two models can be combined in a single product: see Link a non-custodial wallet. To create your first wallet step by step, follow the custodial wallets quickstart.

Object

{
  "id": "wlt_...",
  "type": "walletCrypto",
  "customer": { "id": "cst_..." },
  "status": "active",
  "asset": "usdc",
  "network": "polygon",
  "address": "0x7b3a9f2c4d1ea8bf6390ce5d2b7fa104c8e3d9b1",
  "provider": "...",
  "routing": { "claimStatus": "unclaimed" },
  "balances": [
    { "asset": "usdc", "network": "polygon", "balance": "1234.560000", "estimatedValueUsd": "1234.56" }
  ],
  "createdAt": "2026-01-15T10:31:00.000Z",
  "updatedAt": "2026-01-15T10:31:00.000Z"
}

type is walletCrypto for a crypto wallet or walletFiat for a fiat wallet. A crypto wallet carries its network and its onchain address, which is omitted until the custody provider reports one. A fiat wallet has no network or address, and its balances entries carry no network. provider is the legal entity holding the wallet’s assets; treat it as a free-form string. routing reports whether a deposit address or virtual account has claimed the wallet; see Claimed wallets. balances lists the wallet’s balance per asset with a USD estimate. Each balance is a decimal string at the asset’s precision. A fiat wallet balance can be negative, for example after an ACH clawback, so render the sign as received.

Wallet status	Meaning
`pending`	Created, not yet open.
`active`	Usable for sends and receipts.
`frozen`	The money in it is held for a compliance review.
`suspended`	Disabled by operations.
`closed`	Permanently closed; never active again.

Create a wallet

POST /wallets creates a wallet for a customer. Set type to custodial for a crypto wallet or fiat for a fiat wallet; the response reports the matching walletCrypto or walletFiat type.

{
  "customerId": "cst_...",
  "type": "custodial",
  "details": { "asset": "usdc", "network": "polygon" },
  "label": "Main USDC wallet"
}

{
  "customerId": "cst_...",
  "type": "fiat",
  "details": { "asset": "usd" }
}

A custodial create returns 201 with the wallet when it exists or is confirmed right away. When confirmation arrives later, it returns 202 with a Location header; poll GET /wallets/operations/{operationId} until its status is complete, then read the wallet by the operation’s walletId. A fiat wallet starts pending and moves to active once the bank opens the account.

Error	When
`403 KYCRequired`	The customer is not cleared for custodial wallets. A custodial wallet needs an `active` `cryptoCustody` endorsement on projects that require verification.
`422 UnsupportedAsset`	The asset and network pair is not supported, or a fiat wallet asked for an asset other than `usd`.
`422 WalletProvisioningRejected`	The provider refused the wallet.
`403 DestinationRailNotAllowed`	Fiat wallets are not enabled for your project.
`501 WalletTypeNotSupported`	`type: noncustodial`. Non-custodial wallets are created with the OMS Wallet SDK, not this endpoint.

POST /wallets requires an Idempotency-Key header; a replay returns the same response, including the same operation Location.

Read, list, and update

GET /wallets/{id} returns one wallet, including its current balances.
GET /wallets lists wallets in the project, most recent first. Filter by customerId and by type (custodial, fiat, or noncustodial), or search with search. Page with limit and cursor. Claimed wallets are hidden unless you pass includeHidden=claimed.
GET /wallets?orderBy=balance ranks wallets by the USD estimate of their available balance, highest first; pass order=asc to reverse it. Wallets without a USD estimate sort last. The order uses live balances, so a balance that changes while you page can skip or repeat a wallet.
PATCH /wallets/{id} updates label only. An empty string clears it.

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

Link a non-custodial wallet

POST /customers/{customerId}/wallets/associate links an existing OMS Wallet non-custodial wallet to a customer. The request body carries an idToken issued for the wallet: the token’s subject identifies the wallet, so you never pass a wallet ID directly, and its audience must be your project.

Funding a wallet

Method	How it works
Direct crypto transfer	Send stablecoins to the wallet’s `address`. The deposit appears as a transaction with `precursor.type: walletDeposit`.
Virtual account	Fiat deposited to the customer’s bank account number converts to crypto and is delivered to the wallet.
Deposit address	Crypto sent to a deposit address is delivered to its configured destination.
Cash-in	Cash deposited at a retail location converts to crypto and is delivered to the wallet.

Transaction history

List a wallet’s transactions with GET /transactions?walletId={id}. It returns every transaction where the wallet is the source or destination, crypto or fiat alike. See Transactions.

Claimed wallets

A wallet that a live deposit address or virtual account receives into is claimed by that resource. Every wallet carries a read-only routing object that reports this state:

"routing": {
  "claimStatus": "claimed",
  "claimedBy": { "type": "virtualAccount", "id": "va_..." },
  "claimedAt": "2026-02-10T14:12:00.000Z"
}

Field	Meaning
`claimStatus`	`unclaimed`, `claimed`, or `released`.
`claimedBy`	The deposit address or virtual account currently (or last) claiming the wallet. Absent when `unclaimed`.
`claimedAt`	When the current or last claim started. Absent when `unclaimed`.
`releasedAt`	When the last claim was released. Present only when `released`.

A claimed wallet stays readable by ID, keeps its balance, and can still be updated. It cannot fund a withdrawal while the claim stands: POST /quotes and POST /transactions return 422 WalletClaimed (code 10357). GET /wallets omits claimed wallets unless you pass includeHidden=claimed. The customer’s aggregate balance still includes it. Deleting or closing the claiming virtual account or deposit address releases the wallet: claimStatus moves to released, the wallet reappears in the default listing, and it can fund withdrawals again. A deposit address’s or virtual account’s destination wallet is a payout target, not a claim. It stays listed and can fund a withdrawal. A custodial wallet that is a live virtual account’s walletCrypto destination still cannot be the destination of a second virtual account (409 VirtualAccountWalletInUse).

Webhook events

Event	Fires when
`customerWallet.created`	The wallet was created (`status: pending`, no address yet).
`customerWallet.statusChanged`	The wallet’s status changed, for example to `active` with its address.
`customerWallet.updated`	`label`, `metadata`, or the first address changed.

Routing claims and releases do not send an event.

Key operations

Operation	Endpoint
Create a wallet	`POST /wallets`
Poll a pending wallet creation	`GET /wallets/operations/{operationId}`
Get a wallet and its balances	`GET /wallets/{id}`
List wallets	`GET /wallets`
Update a wallet label	`PATCH /wallets/{id}`
List a wallet’s transactions	`GET /transactions?walletId={id}`

Virtual accounts: assign a bank account number that 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

Get access

Request custodial wallet access

Request access to OMS custodial wallet infrastructure.

​When to use custodial wallets

​Object

​Create a wallet

​Read, list, and update

​Link a non-custodial wallet

​Funding a wallet

​Transaction history

​Claimed wallets

​Webhook events

​Key operations

​Related

​Get access