> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polygon.technology/llms.txt
> Use this file to discover all available pages before exploring further.

# OMS fiat wallets

> Hold a USD balance for a customer at OMS's partner bank, fund it from bank or crypto deposits, and withdraw it to a bank account.

A fiat wallet holds a USD balance for a customer at OMS's partner bank. It works like an OMS [custodial wallet](/wallets/custodial-wallets): 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](https://polygon.technology/get-access?utm_source=docs\&utm_medium=card\&utm_campaign=oms_access) to enable fiat wallets.

## Create a fiat wallet

```bash theme={null}
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](/payments/virtual-accounts) or a [deposit address](/payments/deposit-addresses) at it with a `walletFiat` destination.

```json theme={null}
"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.

```json theme={null}
{
  "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](/payments/external-accounts): `bankUs`, `bankIban`, or `bankCanada`. The transaction's `sourceToDestination` is `fiatAccountToFiatAccount`.

<Note>
  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`.
</Note>

## 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_...`.

## Related

* [Custodial wallets](/wallets/custodial-wallets): OMS-held stablecoin balances
* [Entities and relationships](/payments/core-concepts/entities): how wallets, quotes, and transactions fit together
* [Create a wallet](/api-reference/wallet/create-a-wallet): API reference for `POST /wallets`