> ## 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. # Create a wallet > Creates a wallet for a customer. Polymorphic on `type`: `fiat` and `custodial` are implemented — `embedded` is accepted by the request discriminator but rejected with 501 `walletTypeNotSupported`. Pass an `Idempotency-Key` header to safely retry without provisioning duplicates; a replay returns the same response, including the same operation `Location`. A `fiat` create requires the project to be configured for fiat wallets at "Erebor Bank, N.A." (403 `ereborConfigMissing`), the fiat-wallet book-transfer rail enabled for the project (403 `destinationRailNotAllowed`), and the customer registered with that bank (400 `ereborCustomerNotMapped`); the wallet starts `preallocated` and becomes `active` once the bank opens the backing account. The `wallet.provisioned` webhook fires when the wallet is first recorded and carries `preallocated`, so it does not signal activation — re-read `GET /wallets/{id}` for that. A `custodial` create requires the project and the customer to be enrolled with the custody provider (422 `projectMissingCoinmeId`, 422 `providerUserAccountNotFound`) and an asset/network pair that provider supports (422 `unsupportedAsset`); it returns `201` with the wallet when the wallet already exists or the provider confirms it synchronously, and `202` with a `Location` header pointing at the wallet-provisioning operation — poll `GET /wallets/operations/{operationId}` — when confirmation arrives asynchronously. A durable provider rejection is 422 `walletProvisioningRejected`. ## OpenAPI ````yaml /api-reference/openapi.yaml post /wallets openapi: 3.0.3 info: title: Polygon OMS Public API version: v26.09.09-0001 description: >- Unified API for moving money between crypto and fiat. Three ways to move money: Transactions (instant, wallet or card funded, including Cash-In for in-person cash deposits), Deposit Addresses (reusable crypto deposit configurations), and Virtual Accounts (dedicated bank accounts that auto-convert fiat to crypto). Standard transactions follow a two-step flow: create a Quote (pricing), then create a Transaction (execution). Cash-in codes generate a one-time deposit code for in-person cash deposits at retail locations. contact: name: Polygon OMS url: https://oms.polygon.technology servers: - url: https://sandbox-api.polygon.technology/v0.13 description: Sandbox - url: https://api.polygon.technology/v0.13 description: Production security: - BearerAuth: [] tags: - name: Auth description: Authentication via FrontEgg - name: Customers description: Customer management and KYC - name: Customer - name: Wallet - name: Quote - name: Transaction - name: CashIns - name: CashLocation - name: Sandbox - name: VirtualAccount - name: Counterparty - name: ExternalAccount - name: Reference - name: DepositAddress paths: /wallets: post: tags: - Wallet summary: Create a wallet description: >- Creates a wallet for a customer. Polymorphic on `type`: `fiat` and `custodial` are implemented — `embedded` is accepted by the request discriminator but rejected with 501 `walletTypeNotSupported`. Pass an `Idempotency-Key` header to safely retry without provisioning duplicates; a replay returns the same response, including the same operation `Location`. A `fiat` create requires the project to be configured for fiat wallets at "Erebor Bank, N.A." (403 `ereborConfigMissing`), the fiat-wallet book-transfer rail enabled for the project (403 `destinationRailNotAllowed`), and the customer registered with that bank (400 `ereborCustomerNotMapped`); the wallet starts `preallocated` and becomes `active` once the bank opens the backing account. The `wallet.provisioned` webhook fires when the wallet is first recorded and carries `preallocated`, so it does not signal activation — re-read `GET /wallets/{id}` for that. A `custodial` create requires the project and the customer to be enrolled with the custody provider (422 `projectMissingCoinmeId`, 422 `providerUserAccountNotFound`) and an asset/network pair that provider supports (422 `unsupportedAsset`); it returns `201` with the wallet when the wallet already exists or the provider confirms it synchronously, and `202` with a `Location` header pointing at the wallet-provisioning operation — poll `GET /wallets/operations/{operationId}` — when confirmation arrives asynchronously. A durable provider rejection is 422 `walletProvisioningRejected`. operationId: createWallet parameters: - $ref: '#/components/parameters/IdempotencyKeyHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WalletRequest' responses: '201': description: >- The request has succeeded and a new resource has been created as a result. content: application/json: schema: $ref: '#/components/schemas/WalletResource' '202': description: >- The request has been accepted for processing, but processing has not yet completed. headers: Location: required: true description: URL of the wallet-provisioning operation to poll for completion. schema: type: string content: application/json: schema: $ref: '#/components/schemas/WalletOperation' '400': description: The server could not understand the request due to invalid syntax. content: application/json: schema: anyOf: - $ref: '#/components/schemas/EreborCustomerNotMappedErrorResponse' - $ref: '#/components/schemas/InvalidWalletTypeErrorResponse' '403': description: Access is forbidden. content: application/json: schema: anyOf: - $ref: >- #/components/schemas/DestinationRailNotAllowedErrorResponse - $ref: '#/components/schemas/EreborConfigMissingErrorResponse' '409': description: The request conflicts with the current state of the server. content: application/json: schema: anyOf: - $ref: '#/components/schemas/ConflictErrorResponse' - $ref: '#/components/schemas/FiatWalletLimitReachedErrorResponse' '422': description: Client error content: application/json: schema: anyOf: - $ref: '#/components/schemas/EreborValidationFailedErrorResponse' - $ref: '#/components/schemas/IdempotencyKeyReuseErrorResponse' - $ref: '#/components/schemas/ProjectMissingCoinmeIDErrorResponse' - $ref: >- #/components/schemas/ProviderUserAccountNotFoundErrorResponse - $ref: '#/components/schemas/UnsupportedAssetErrorResponse' - $ref: >- #/components/schemas/WalletProvisioningRejectedErrorResponse '500': description: Server error content: application/json: schema: $ref: '#/components/schemas/InternalErrorResponse' '501': description: Server error content: application/json: schema: $ref: '#/components/schemas/WalletTypeNotSupportedErrorResponse' '503': description: Service unavailable. content: application/json: schema: $ref: '#/components/schemas/ServiceUnavailableErrorResponse' components: parameters: IdempotencyKeyHeader: name: Idempotency-Key in: header required: true description: >- Required on POST and PUT requests. Use a unique value per logical mutation attempt, for example a UUID. schema: type: string schemas: WalletRequest: type: object oneOf: - $ref: '#/components/schemas/WalletRequestCustodial' - $ref: '#/components/schemas/WalletRequestEmbedded' - $ref: '#/components/schemas/WalletRequestFiat' discriminator: propertyName: type mapping: custodial: $ref: '#/components/schemas/WalletRequestCustodial' embedded: $ref: '#/components/schemas/WalletRequestEmbedded' fiat: $ref: '#/components/schemas/WalletRequestFiat' description: >- Create a wallet for a customer. Pick a `type`; the variant-specific fields live in `details`. Only `fiat` is implemented today; `custodial` and `embedded` are accepted by the discriminator but rejected with 501. WalletResource: type: object oneOf: - $ref: '#/components/schemas/WalletResourceCustodial' - $ref: '#/components/schemas/WalletResourceFiat' discriminator: propertyName: type mapping: custodial: $ref: '#/components/schemas/WalletResourceCustodial' fiat: $ref: '#/components/schemas/WalletResourceFiat' description: >- A wallet OMS manages for a customer. `type` discriminates the variant and the variant-specific fields live in `details`: `custodial` holds one crypto asset on one network at the custody provider ("Coinme Inc." today); `fiat` holds a single fiat currency balance (only `usd` today) on an internal ledger at "Erebor Bank, N.A." — no network and no on-chain address. There is no `embedded` variant in the response: a request for one is rejected with 501 `walletTypeNotSupported`. Read `type` for logic rather than parsing the id. WalletOperation: type: object required: - operationId - object - customerId - status - pairs - createdAt properties: operationId: allOf: - $ref: '#/components/schemas/typeId' description: Operation ID (`op_` TypeID). object: type: string enum: - wallet.operation description: Resource type discriminator. Always "wallet.operation". customerId: allOf: - $ref: '#/components/schemas/typeId' description: >- The OMS customer the operation provisions wallets for (`cst_` prefix). status: $ref: '#/components/schemas/WalletOperationStatus' pairs: type: array items: $ref: '#/components/schemas/WalletOperationPairStatus' walletId: allOf: - $ref: '#/components/schemas/typeId' description: >- The provisioned wallet's id (`wlt_` prefix), present once the requested pair has completed and the wallet record is visible. createdAt: type: string format: date-time description: >- The status resource a `202 Accepted` wallet create points at (its `Location` header). Project-scoped: an operation is only visible to the project that created it. Poll until `status` leaves `pending`; when the requested wallet is confirmed, `walletId` carries its id. EreborCustomerNotMappedErrorResponse: type: object required: - error - code - msg properties: error: type: string enum: - EreborCustomerNotMapped code: type: number enum: - 10026 msg: type: string enum: - customer not yet mapped to Erebor cause: type: string InvalidWalletTypeErrorResponse: type: object required: - error - code - msg properties: error: type: string enum: - InvalidWalletType code: type: number enum: - 10149 msg: type: string enum: - missing or unrecognized wallet type cause: type: string DestinationRailNotAllowedErrorResponse: type: object required: - error - code - msg properties: error: type: string enum: - DestinationRailNotAllowed code: type: number enum: - 10184 msg: type: string enum: - destination rail %q is not enabled for this project cause: type: string EreborConfigMissingErrorResponse: type: object required: - error - code - msg properties: error: type: string enum: - EreborConfigMissing code: type: number enum: - 10025 msg: type: string enum: - erebor integration is not configured for this partner cause: type: string ConflictErrorResponse: type: object required: - error - code - msg properties: error: type: string enum: - Conflict code: type: number enum: - 4000 msg: type: string enum: - resource conflict cause: type: string FiatWalletLimitReachedErrorResponse: type: object required: - error - code - msg properties: error: type: string enum: - FiatWalletLimitReached code: type: number enum: - 10329 msg: type: string enum: - >- the customer already holds the maximum number of fiat wallets permitted cause: type: string EreborValidationFailedErrorResponse: type: object required: - error - code - msg properties: error: type: string enum: - EreborValidationFailed code: type: number enum: - 10027 msg: type: string enum: - erebor terminally rejected the provisioning payload cause: type: string IdempotencyKeyReuseErrorResponse: type: object required: - error - code - msg properties: error: type: string enum: - IdempotencyKeyReuse code: type: number enum: - 10277 msg: type: string enum: - Idempotency key already used with a different request cause: type: string ProjectMissingCoinmeIDErrorResponse: type: object required: - error - code - msg properties: error: type: string enum: - ProjectMissingCoinmeID code: type: number enum: - 10073 msg: type: string enum: - project is not enrolled with a custodial wallet provider cause: type: string ProviderUserAccountNotFoundErrorResponse: type: object required: - error - code - msg properties: error: type: string enum: - ProviderUserAccountNotFound code: type: number enum: - 10029 msg: type: string enum: - provider account not provisioned for this customer cause: type: string UnsupportedAssetErrorResponse: type: object required: - error - code - msg properties: error: type: string enum: - UnsupportedAsset code: type: number enum: - 10151 msg: type: string enum: - custodial wallets are not supported for %s on %s cause: type: string WalletProvisioningRejectedErrorResponse: type: object required: - error - code - msg properties: error: type: string enum: - WalletProvisioningRejected code: type: number enum: - 10152 msg: type: string enum: - the custodial wallet provider rejected this wallet create cause: type: string InternalErrorResponse: type: object required: - error - code - msg properties: error: type: string enum: - Internal code: type: number enum: - 10124 msg: type: string enum: - internal error cause: type: string WalletTypeNotSupportedErrorResponse: type: object required: - error - code - msg properties: error: type: string enum: - WalletTypeNotSupported code: type: number enum: - 10150 msg: type: string enum: - wallet type %q is not supported yet cause: type: string ServiceUnavailableErrorResponse: type: object required: - error - code - msg properties: error: type: string enum: - ServiceUnavailable code: type: number enum: - 5003 msg: type: string enum: - service unavailable cause: type: string WalletRequestCustodial: type: object required: - customerId - type - details properties: customerId: allOf: - $ref: '#/components/schemas/typeId' description: Owning customer (`cst_` prefix). type: type: string enum: - custodial description: Type discriminator. details: $ref: '#/components/schemas/WalletRequestCustodialDetails' label: type: string nullable: true metadata: type: object additionalProperties: type: string description: Create a custodial crypto wallet. Not yet implemented — returns 501. WalletRequestEmbedded: type: object required: - customerId - type - details properties: customerId: allOf: - $ref: '#/components/schemas/typeId' description: Owning customer (`cst_` prefix). type: type: string enum: - embedded description: Type discriminator. details: $ref: '#/components/schemas/WalletRequestEmbeddedDetails' label: type: string nullable: true metadata: type: object additionalProperties: type: string description: Create an embedded crypto wallet. Not yet implemented — returns 501. WalletRequestFiat: type: object required: - customerId - type - details properties: customerId: allOf: - $ref: '#/components/schemas/typeId' description: Owning customer (`cst_` prefix). type: type: string enum: - fiat description: Type discriminator. details: $ref: '#/components/schemas/WalletRequestFiatDetails' label: type: string nullable: true metadata: type: object additionalProperties: type: string description: >- Create a fiat balance wallet, held for the customer at Erebor Bank, N.A. It holds a single fiat currency — only `usd` today; any other asset is rejected with 422 `unsupportedAsset`. example: customerId: cst_vfa0nxw6zvyws9g237jrxn4y7k type: fiat details: asset: usd WalletResourceCustodial: type: object required: - id - object - customerId - status - provider - multiAsset - displayName - type - details properties: id: allOf: - $ref: '#/components/schemas/typeId' description: Wallet ID (TypeID; `wlt_fiat_` for fiat wallets). object: type: string enum: - wallet description: Resource type discriminator. Always "wallet". customerId: allOf: - $ref: '#/components/schemas/typeId' description: The OMS customer that owns this record (`cst_` prefix). customer: allOf: - $ref: '#/components/schemas/CustomerSummary' description: >- Display-safe summary of the owning customer (`customer.id` equals `customerId`). Returned on list and detail responses. status: allOf: - $ref: '#/components/schemas/WalletResourceStatus' description: Current wire status. provider: type: string description: >- The legal entity holding this wallet's assets, derived from wallet type and asset: `custodial` → "Coinme Inc."; `fiat` (usd) → "Erebor Bank, N.A.". New providers may be added, so treat the string as free-form rather than a fixed set. multiAsset: type: boolean description: >- true when the wallet supports every network in its family and all assets on them; false when restricted to a single asset (fiat, custodial). displayName: type: string description: >- Server-generated wallet name. Custodial wallets use their on-chain address; fiat wallets use `USD balance ()`. Distinct from the optional partner-supplied label. label: type: string nullable: true balances: type: array items: $ref: '#/components/schemas/WalletResourceBalance' metadata: type: object additionalProperties: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time type: type: string enum: - custodial description: Type discriminator. details: $ref: '#/components/schemas/WalletDetailCustodial' description: >- The `custodial` variant — one crypto asset on one network, held on the customer's behalf by the custody provider, currently "Coinme Inc.". `details.address` is the on-chain deposit address and is omitted until the provider reports one. WalletResourceFiat: type: object required: - id - object - customerId - status - provider - multiAsset - displayName - type - details properties: id: allOf: - $ref: '#/components/schemas/typeId' description: Wallet ID (TypeID; `wlt_fiat_` for fiat wallets). object: type: string enum: - wallet description: Resource type discriminator. Always "wallet". customerId: allOf: - $ref: '#/components/schemas/typeId' description: The OMS customer that owns this record (`cst_` prefix). customer: allOf: - $ref: '#/components/schemas/CustomerSummary' description: >- Display-safe summary of the owning customer (`customer.id` equals `customerId`). Returned on list and detail responses. status: allOf: - $ref: '#/components/schemas/WalletResourceStatus' description: Current wire status. provider: type: string description: >- The legal entity holding this wallet's assets, derived from wallet type and asset: `custodial` → "Coinme Inc."; `fiat` (usd) → "Erebor Bank, N.A.". New providers may be added, so treat the string as free-form rather than a fixed set. multiAsset: type: boolean description: >- true when the wallet supports every network in its family and all assets on them; false when restricted to a single asset (fiat, custodial). displayName: type: string description: >- Server-generated wallet name. Custodial wallets use their on-chain address; fiat wallets use `USD balance ()`. Distinct from the optional partner-supplied label. label: type: string nullable: true balances: type: array items: $ref: '#/components/schemas/WalletResourceBalance' metadata: type: object additionalProperties: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time type: type: string enum: - fiat description: Type discriminator. details: $ref: '#/components/schemas/WalletDetailFiat' description: >- The `fiat` variant — a single fiat currency balance (only `usd` today) held at a partner bank, currently "Erebor Bank, N.A.". An internal ledger balance: no network and no on-chain address. typeId: type: string pattern: >- ^[a-z]+_([0-9a-hjkmnp-tv-z]{26}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$ description: >- Public TypeID, e.g. `txn_01h455vb4pex5vsknk084sn02q`; legacy UUID suffixes are accepted until non-v7 rows are retired. x-go-type: string WalletOperationStatus: type: string enum: - pending - complete - partial - terminal description: >- Aggregate status of a wallet-provisioning operation. `pending`: at least one pair is still converging and automation is active. `partial`: some pairs completed, at least one needs an operator. `terminal`: the provider durably rejected at least one pair. `complete`: every pair confirmed. WalletOperationPairStatus: type: object required: - asset - network - state properties: asset: type: string description: Crypto asset (canonical symbol, e.g. "usdc"). network: type: string description: Blockchain network (canonical name, e.g. "polygon"). state: $ref: '#/components/schemas/WalletOperationPairState' description: >- One asset/network pair being converged by a wallet-provisioning operation. WalletRequestCustodialDetails: type: object required: - network - asset properties: network: allOf: - $ref: '#/components/schemas/CryptoNetwork' description: Blockchain network the wallet operates on. asset: type: string description: Crypto asset the custodial wallet holds. description: Custodial crypto wallet create request details. WalletRequestEmbeddedDetails: type: object required: - networkFamily properties: networkFamily: allOf: - $ref: '#/components/schemas/NetworkFamily' description: Network family the embedded wallet operates on (`evm` or `solana`). description: Embedded crypto wallet create request details. WalletRequestFiatDetails: type: object required: - asset properties: asset: type: string enum: - usd description: Fiat currency the wallet holds. Only `usd` today. description: Fiat wallet create request details — the fiat currency to hold. CustomerSummary: type: object required: - id - name properties: id: allOf: - $ref: '#/components/schemas/typeId' description: The OMS customer id (`cst_` prefix). name: type: string description: Customer display name. description: >- Display-safe summary of a customer — ID plus display name only. Enables one-request list rendering: a page of rows needs no per-row detail queries. Always the record's owning customer, not whichever side a party sits on. WalletResourceStatus: type: string enum: - preallocated - active - suspended description: >- `preallocated`: reserved/provisioned but not yet activated. `active`: usable. `suspended`: temporarily disabled (e.g. a compliance or risk hold). There is no terminal value — a closed wallet also reports `suspended`. WalletResourceBalance: type: object required: - asset - network - balance - estimatedValueUsd properties: asset: type: string network: type: string nullable: true description: Null for fiat balances — held on an internal ledger, not a network. balance: $ref: '#/components/schemas/signedFixedDecimalString' estimatedValueUsd: $ref: '#/components/schemas/signedFixedDecimalString' description: >- One (asset, network) balance entry on a wallet. The OMS contract calls this `WalletBalance`; renamed here because the legacy balance-response envelope owns that name. WalletDetailCustodial: type: object required: - network - asset properties: network: type: string description: >- Blockchain network the wallet operates on (canonical name, e.g. "polygon"). asset: type: string description: Crypto asset the wallet holds (canonical symbol, e.g. "usdc"). address: type: string description: >- On-chain deposit address. Omitted when the provider has not reported one yet. description: >- Custodial crypto wallet details — one asset on one network, held by the custody provider on the customer's behalf. WalletDetailFiat: type: object required: - asset properties: asset: type: string enum: - usd description: Fiat currency of the balance. Only `usd` today. description: >- Fiat wallet details — a single fiat currency balance held at a partner bank (internal ledger, no network or on-chain address). WalletOperationPairState: type: string enum: - pending - complete - terminal description: >- Per-pair convergence state on a wallet-provisioning operation. `terminal` means the provider durably rejected the pair. CryptoNetwork: type: string enum: - ethereum - polygon - base - solana - tron description: >- Blockchain network identifier: `ethereum`, `polygon`, `base`, `solana`, `tron`. Pass the lowercase name — numeric EVM chain IDs (`1`, `137`, `8453`) are not accepted, and responses always return the name. This is the wire vocabulary, not an availability list. `tron` is receive-side only: a registered external wallet cannot be created on it, so it is never a valid `walletExternal` network. Availability is per provider rather than per project, so a network your project holds through one provider can still be refused for a customer on another — call `GET /networks?vendor=` scoped to the provider you are asking about, since omitting `vendor` returns the union across every provider the project holds and over-reports. NetworkFamily: type: string enum: - evm - solana description: >- Crypto network family for a registered external wallet. A walletExternal is registered per family (an EVM address is valid across every EVM chain), and the registration covers every served network in that family. signedFixedDecimalString: type: string description: >- Wire-safe decimal string for signed financial values that must ship with a fixed scale (trailing zeros preserved). It combines the two guarantees the OMS `Customer.totalBalance` fields need at once: the leading minus is part of the contract — a fiat balance may be negative after an ACH clawback, so consumers render the sign as-is and never clamp to zero — and the scale is preserved on the wire (e.g. `"25.00"`, `"-25.00"`, `"0.00"`), unlike `signedDecimalString`/`decimal.Decimal`, whose `.String()` trims trailing zeros (`"25.00"` → `"25"`). Same underlying `numeric.FixedDecimalString` Go type as `fixedDecimalString`; the builder is responsible for setting the scale (via `StringFixed`). x-go-type-import: path: github.com/0xPolygon/bpn-lib/numeric x-go-type: numeric.FixedDecimalString securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: Token from POST /auth/token ````