OMS fiat wallets - Polygon Developer Docs

A fiat wallet holds a USD balance for a customer at OMS’s partner bank. It works like an OMS custodial wallet: you create it with POST /wallets, fund it, and withdraw with a quote and transaction. The difference is where the balance lives. A fiat wallet is an internal ledger balance with no network and no onchain address, and its ID uses the wlt_fiat_ prefix.

	Fiat wallet	Custodial wallet	Virtual account
Holds	A USD balance	A stablecoin balance on one chain	Nothing: it receives and routes
Identifier	`wlt_fiat_...`	`wlt_...` with an onchain address	Bank account and routing numbers
Created with	`POST /wallets` (`type: fiat`)	`POST /wallets` (`type: custodial`)	`POST /virtual-accounts`

Before you start

Fiat wallets must be enabled for your project, along with the internal book-transfer rail they settle on, and the customer must be registered with the partner bank. POST /wallets returns 403 EreborConfigMissing or 403 destinationRailNotAllowed when the project is not set up, and 400 EreborCustomerNotMapped when the customer is not registered. Contact us to enable fiat wallets.

Create a fiat wallet

curl -X POST https://api.polygon.technology/v0.13/wallets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "customerId": "cst_...",
    "type": "fiat",
    "details": { "asset": "usd" },
    "label": "USD balance"
  }'

usd is the only supported asset; any other asset returns 422 UnsupportedAsset. A customer can hold a limited number of fiat wallets, and a create past that limit returns 409 FiatWalletLimitReached. The wallet starts preallocated and becomes active once the partner bank opens the backing account. The wallet.provisioned webhook fires when the wallet is first recorded, while it is still preallocated, so it does not signal activation. Read GET /wallets/{id} to confirm the wallet is active before you use it.

Fund it

A fiat wallet is funded the same way OMS delivers to any destination: point a virtual account or a deposit address at it with a walletFiat destination.

"destination": {
  "type": "walletFiat",
  "details": { "id": "wlt_fiat_...", "asset": "usd" }
}

From a bank transfer: a virtual account with a walletFiat destination credits each inbound deposit to the wallet.
From crypto: a deposit address with a walletFiat destination converts inbound USDC or USDT and credits the USD.

OMS credits the wallet by internal book transfer at the partner bank, so the resolved destination instrument on the transaction reads network: bookTransfer. The wallet must belong to the same customer as the virtual account or deposit address.

Withdraw to a bank account

Withdraw the same way you would from a custodial wallet: create a quote with the fiat wallet as the source, then execute it.

{
  "customerId": "cst_...",
  "source": {
    "type": "walletFiat",
    "details": { "id": "wlt_fiat_...", "asset": "usd" },
    "amount": "100.00"
  },
  "destination": {
    "type": "bankUs",
    "details": { "id": "ext_...", "asset": "usd", "network": "ach" }
  }
}

Send this to POST /quotes, then call POST /transactions with the returned quoteId. The destination can be any registered bank external account: bankUs, bankIban, or bankCanada. The transaction’s sourceToDestination is fiatAccountToFiatAccount.

Sending from a fiat wallet to a crypto destination is not supported in this release. A quote with a fiat wallet source and a crypto destination returns CryptoOutNotSupported.

Read the balance

GET /wallets/{id} accepts a wlt_fiat_ ID and returns the wallet with type: fiat. A fiat balance always renders as a decimal string with two places: "0.00" for a wallet that has never been funded, and a negative value such as "-25.00" if the wallet is overdrawn. To list a customer’s transactions on the wallet, call GET /transactions?walletId=wlt_fiat_....

Custodial wallets: OMS-held stablecoin balances
Entities and relationships: how wallets, quotes, and transactions fit together
Create a wallet: API reference for POST /wallets

​Before you start

​Create a fiat wallet

​Fund it

​Withdraw to a bank account

​Read the balance

​Related

Before you start

Create a fiat wallet

Fund it

Withdraw to a bank account

Read the balance

Related