> ## 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 Deposit Address

> Create a Deposit Address. Deposit addresses must be enabled for your project and the customer must be provisioned for them.



## OpenAPI

````yaml /api-reference/openapi.yaml post /deposit-addresses
openapi: 3.0.3
info:
  title: Polygon OMS Public API
  version: v26.05.28-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.10
    description: Sandbox
  - url: https://api.polygon.technology/v0.10
    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: Webhook
  - name: CashIns
  - name: CashLocation
  - name: Sandbox
  - name: VirtualAccount
  - name: Counterparty
  - name: ExternalAccount
  - name: DepositAddress
  - name: Simulation
paths:
  /deposit-addresses:
    post:
      tags:
        - DepositAddress
      summary: Create a Deposit Address
      description: >-
        Create a Deposit Address. Deposit addresses must be enabled for your
        project and the customer must be provisioned for them.
      operationId: createDepositAddress
      parameters:
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DepositAddressCreateRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DepositAddress'
          description: >-
            The request has succeeded and a new resource has been created as a
            result.
components:
  parameters:
    IdempotencyKeyHeader:
      description: >-
        Required on POST and PUT requests. Use a unique value per logical
        mutation attempt, for example a UUID.
      in: header
      name: Idempotency-Key
      required: true
      schema:
        type: string
  schemas:
    DepositAddressCreateRequest:
      properties:
        customerId:
          description: Owning customer (cus_… or legacy public id).
          type: string
        destination:
          allOf:
            - $ref: '#/components/schemas/DepositAddressFiatDestinationRequest'
          description: >-
            Side-shaped destination: a registered bankUs, bankIban, or
            bankCanada External Account. The server validates details
            (asset/network/accountHolder) against the resolved external account.
        expectedSourceAsset:
          description: >-
            Asset of the inbound crypto the deposit address expects. "usdc" |
            "usdt" (lowercase).
          type: string
        expectedSourceNetwork:
          description: >-
            Network of the inbound crypto the deposit address expects. Drawn
            from the served-network set; excludes polygon, ink, and sui.
          type: string
        label:
          description: Partner display label.
          type: string
        metadata:
          type: object
          additionalProperties:
            type: string
        sponsorGas:
          default: true
          description: |-
            When `true`, OMS absorbs the on-chain gas cost for the destination
            delivery. Only `true` is currently supported.
          type: boolean
      required:
        - customerId
        - expectedSourceAsset
        - expectedSourceNetwork
        - destination
      type: object
    DepositAddress:
      properties:
        createdAt:
          type: string
          format: date-time
        customerId:
          description: >-
            Public customer id (cst_...). Named customerId to match VA's naming
            convention.
          type: string
        depositInstructions:
          allOf:
            - $ref: '#/components/schemas/DepositAddressDepositInstructions'
          description: >-
            Null in the 201 until provisioning populates the OMS-owned inlet
            address. Top-level mirror of the virtual account's bankDetails.
        destination:
          allOf:
            - $ref: '#/components/schemas/TransactionDestination'
          description: >-
            Unified destination shape (payoutOrigin lives inside
            TransactionDestination).
        expectedSourceAsset:
          description: Asset of the inbound crypto the DA expects.
          type: string
        expectedSourceNetwork:
          description: Network of the inbound crypto the DA expects.
          type: string
        failureReason:
          $ref: '#/components/schemas/DepositAddressFailureReason'
        id:
          type: string
        label:
          type: string
        metadata:
          type: object
          additionalProperties:
            type: string
        object:
          enum:
            - depositAddress
          type: string
        status:
          $ref: '#/components/schemas/DepositAddressStatus'
        statusReason:
          type: string
        transactionType:
          allOf:
            - $ref: '#/components/schemas/TransferType'
          description: >-
            Always TransferType.cryptoToFiat for DA. Reuses the existing
            TransferType enum (instead of a string literal) to avoid
            collision-driven renames on the generated oapi enums - see
            feedback_reuse_enums_over_collision memory.
        updatedAt:
          type: string
          format: date-time
      type: object
    DepositAddressFiatDestinationRequest:
      description: >-
        Deposit Address fiat destination: a registered bank-type External
        Account, on the shared discriminated side shape. The server validates
        the side `details` (asset/network/accountHolder) against the resolved
        external account.
      discriminator:
        mapping:
          bankCanada:
            $ref: '#/components/schemas/BankCanadaSideRequest'
          bankIban:
            $ref: '#/components/schemas/BankIbanSideRequest'
          bankUs:
            $ref: '#/components/schemas/BankUsSideRequest'
        propertyName: type
      oneOf:
        - $ref: '#/components/schemas/BankUsSideRequest'
        - $ref: '#/components/schemas/BankIbanSideRequest'
        - $ref: '#/components/schemas/BankCanadaSideRequest'
      type: object
    DepositAddressDepositInstructions:
      properties:
        address:
          description: OMS-owned on-chain inlet address for this deposit address.
          type: string
        asset:
          description: Same value as expectedSourceAsset.
          type: string
        expiresAt:
          description: >-
            Placeholder for a future provider-imposed inlet expiry. Null today;
            surfaced now so adding it later is not a breaking change.
          format: date-time
          type: string
        network:
          description: Same value as expectedSourceNetwork.
          type: string
      required:
        - asset
        - network
        - address
      type: object
    TransactionDestination:
      description: >-
        The destination side of a transaction or quote: a typed instrument plus
        `payoutOrigin`. Amounts live only in `pricing`.
      discriminator:
        mapping:
          bankCanada:
            $ref: '#/components/schemas/BankCanadaDestination'
          bankIban:
            $ref: '#/components/schemas/BankIbanDestination'
          bankUs:
            $ref: '#/components/schemas/BankUsDestination'
          card:
            $ref: '#/components/schemas/CardDestination'
          cash:
            $ref: '#/components/schemas/CashDestination'
          walletExternal:
            $ref: '#/components/schemas/WalletExternalDestination'
          walletOms:
            $ref: '#/components/schemas/WalletOmsDestination'
        propertyName: type
      oneOf:
        - $ref: '#/components/schemas/WalletOmsDestination'
        - $ref: '#/components/schemas/WalletExternalDestination'
        - $ref: '#/components/schemas/BankUsDestination'
        - $ref: '#/components/schemas/BankIbanDestination'
        - $ref: '#/components/schemas/BankCanadaDestination'
        - $ref: '#/components/schemas/CardDestination'
        - $ref: '#/components/schemas/CashDestination'
      type: object
    DepositAddressFailureReason:
      description: >-
        v2: closed enum carried on DA when status = "failed". camelCase per
        partner channel naming convention.
      enum:
        - provisioningTimeout
        - systemError
        - ereborRejected
        - intlBankAccountCreateRejected
        - noMatchingNetwork
        - blockchainAddressInUse
        - bankAccountInUse
      type: string
    DepositAddressStatus:
      enum:
        - pending
        - active
        - frozen
        - closed
        - failed
        - inactiveActionRequired
      type: string
    TransferType:
      description: >-
        Direction of value across rails: cryptoToCrypto, fiatToCrypto, or
        cryptoToFiat. Retained for resources not yet on the
        `SourceToDestination` shape (deposit address, onramp/cash-in, customer
        filters).
      enum:
        - cryptoToCrypto
        - fiatToCrypto
        - cryptoToFiat
      type: string
    BankCanadaSideRequest:
      description: >-
        Deliver to a Canadian bank account. USD routes over SWIFT; CAD over
        local rails.
      properties:
        amount:
          $ref: '#/components/schemas/decimalString'
        details:
          $ref: '#/components/schemas/BankCanadaSideDetails'
        type:
          enum:
            - bankCanada
          type: string
      required:
        - type
        - details
      type: object
    BankIbanSideRequest:
      description: Deliver to an IBAN account over SWIFT (USD).
      properties:
        amount:
          $ref: '#/components/schemas/decimalString'
        details:
          $ref: '#/components/schemas/BankIbanSideDetails'
        type:
          enum:
            - bankIban
          type: string
      required:
        - type
        - details
      type: object
    BankUsSideRequest:
      description: Deliver to a US bank account.
      properties:
        amount:
          $ref: '#/components/schemas/decimalString'
        details:
          $ref: '#/components/schemas/BankUsSideDetails'
        type:
          enum:
            - bankUs
          type: string
      required:
        - type
        - details
      type: object
    BankCanadaDestination:
      properties:
        category:
          enum:
            - fiatAccount
          type: string
        details:
          $ref: '#/components/schemas/BankCanadaDetails'
        party:
          $ref: '#/components/schemas/Party'
        payoutOrigin:
          $ref: '#/components/schemas/PayoutOrigin'
        type:
          enum:
            - bankCanada
          type: string
      required:
        - type
        - category
        - details
      type: object
    BankIbanDestination:
      properties:
        category:
          enum:
            - fiatAccount
          type: string
        details:
          $ref: '#/components/schemas/BankIbanDetails'
        party:
          $ref: '#/components/schemas/Party'
        payoutOrigin:
          $ref: '#/components/schemas/PayoutOrigin'
        type:
          enum:
            - bankIban
          type: string
      required:
        - type
        - category
        - details
      type: object
    BankUsDestination:
      properties:
        category:
          enum:
            - fiatAccount
          type: string
        details:
          $ref: '#/components/schemas/BankUsDetails'
        party:
          $ref: '#/components/schemas/Party'
        payoutOrigin:
          $ref: '#/components/schemas/PayoutOrigin'
        type:
          enum:
            - bankUs
          type: string
      required:
        - type
        - category
        - details
      type: object
    CardDestination:
      properties:
        category:
          enum:
            - fiatAccount
          type: string
        details:
          $ref: '#/components/schemas/CardDetails'
        party:
          $ref: '#/components/schemas/Party'
        payoutOrigin:
          $ref: '#/components/schemas/PayoutOrigin'
        type:
          enum:
            - card
          type: string
      required:
        - type
        - category
        - details
      type: object
    CashDestination:
      properties:
        category:
          enum:
            - cash
          type: string
        details:
          $ref: '#/components/schemas/CashDetails'
        party:
          $ref: '#/components/schemas/Party'
        payoutOrigin:
          $ref: '#/components/schemas/PayoutOrigin'
        type:
          enum:
            - cash
          type: string
      required:
        - type
        - category
        - details
      type: object
    WalletExternalDestination:
      properties:
        category:
          enum:
            - crypto
          type: string
        details:
          $ref: '#/components/schemas/WalletExternalDetails'
        party:
          $ref: '#/components/schemas/Party'
        payoutOrigin:
          $ref: '#/components/schemas/PayoutOrigin'
        type:
          enum:
            - walletExternal
          type: string
      required:
        - type
        - category
        - details
      type: object
    WalletOmsDestination:
      properties:
        category:
          enum:
            - crypto
          type: string
        details:
          $ref: '#/components/schemas/WalletOmsDetails'
        party:
          allOf:
            - $ref: '#/components/schemas/Party'
          description: Structured identity of who is on this side.
        payoutOrigin:
          $ref: '#/components/schemas/PayoutOrigin'
        type:
          enum:
            - walletOms
          type: string
      required:
        - type
        - category
        - details
      type: object
    decimalString:
      description: >-
        Wire-safe decimal string for financial float values (USD amounts,
        percentages).
      type: string
      x-go-type: decimal.Decimal
      x-go-type-import:
        path: github.com/shopspring/decimal
    BankCanadaSideDetails:
      properties:
        accountHolder:
          $ref: '#/components/schemas/AccountHolder'
        asset:
          enum:
            - usd
            - cad
          type: string
        id:
          description: Canadian bank ExternalAccount ID (ext_bankCa_ prefix).
          type: string
        network:
          description: USD uses `swift`; CAD uses `local`. Always explicit.
          enum:
            - swift
            - local
          type: string
      required:
        - id
        - asset
        - network
        - accountHolder
      type: object
    BankIbanSideDetails:
      properties:
        accountHolder:
          $ref: '#/components/schemas/AccountHolder'
        asset:
          enum:
            - usd
          type: string
        id:
          description: IBAN ExternalAccount ID (ext_bankIban_ prefix).
          type: string
        network:
          default: swift
          enum:
            - swift
          type: string
      required:
        - id
        - asset
        - accountHolder
      type: object
    BankUsSideDetails:
      properties:
        accountHolder:
          $ref: '#/components/schemas/AccountHolder'
        asset:
          enum:
            - usd
          type: string
        id:
          description: US bank ExternalAccount ID (ext_bankUs_ prefix).
          type: string
        network:
          enum:
            - ach
            - achSameDay
            - wire
            - rtp
          type: string
      required:
        - id
        - asset
        - network
        - accountHolder
      type: object
    BankCanadaDetails:
      description: Canadian bank account instrument details.
      properties:
        accountNumberLast4:
          type: string
        asset:
          enum:
            - usd
            - cad
          type: string
        bankName:
          type: string
        id:
          type: string
        institutionNumber:
          type: string
        memo:
          type: string
        network:
          enum:
            - swift
            - local
          type: string
        transitNumber:
          type: string
      type: object
    Party:
      discriminator:
        mapping:
          customer:
            $ref: '#/components/schemas/PartyCustomer'
          externalRegistered:
            $ref: '#/components/schemas/PartyExternalRegistered'
          externalUnregistered:
            $ref: '#/components/schemas/PartyExternalUnregistered'
          otherCustomer:
            $ref: '#/components/schemas/PartyOtherCustomer'
        propertyName: relationship
      oneOf:
        - $ref: '#/components/schemas/PartyCustomer'
        - $ref: '#/components/schemas/PartyOtherCustomer'
        - $ref: '#/components/schemas/PartyExternalRegistered'
        - $ref: '#/components/schemas/PartyExternalUnregistered'
      type: object
    PayoutOrigin:
      description: >-
        Where last-mile delivery is sent from. Quote and deposit-address
        responses echo the choice only; the transaction response carries full
        detail (`accountNumber`/`routingNumber`/`txHash`).
      discriminator:
        mapping:
          bank:
            $ref: '#/components/schemas/PayoutOriginBank'
          blockchain:
            $ref: '#/components/schemas/PayoutOriginBlockchain'
        propertyName: type
      oneOf:
        - $ref: '#/components/schemas/PayoutOriginBank'
        - $ref: '#/components/schemas/PayoutOriginBlockchain'
      type: object
    BankIbanDetails:
      description: IBAN bank account instrument details.
      properties:
        BIC:
          type: string
        asset:
          type: string
        bankAddress:
          $ref: '#/components/schemas/Address'
        countryCode:
          type: string
        ibanLast4:
          type: string
        id:
          type: string
        memo:
          type: string
        network:
          enum:
            - swift
          type: string
      type: object
    BankUsDetails:
      description: US bank account instrument details.
      properties:
        accountNumberLast4:
          type: string
        accountType:
          enum:
            - checking
            - savings
          type: string
        asset:
          enum:
            - usd
          type: string
        bankName:
          type: string
        id:
          type: string
        memo:
          type: string
        network:
          enum:
            - ach
            - achSameDay
            - wire
            - rtp
          type: string
        routingNumber:
          type: string
        secCode:
          allOf:
            - $ref: '#/components/schemas/SecCode'
          description: ACH SEC code. Populated only when network is ach or achSameDay.
      type: object
    CardDetails:
      description: Card instrument details.
      properties:
        asset:
          enum:
            - usd
          type: string
        cardNumberLast4:
          type: string
        cardProvider:
          type: string
        id:
          type: string
        memo:
          type: string
        network:
          enum:
            - card
          type: string
      type: object
    CashDetails:
      description: Cash pickup/drop instrument details.
      properties:
        asset:
          type: string
        cashLocationId:
          type: string
        cashLocationReference:
          type: string
        code:
          type: string
        expiresAt:
          type: string
          format: date-time
        locationAddress:
          type: string
        locationName:
          type: string
      type: object
    WalletExternalDetails:
      description: >-
        WalletExternal instrument details: a crypto wallet held in external
        custody.
      properties:
        asset:
          type: string
        blockchainAddress:
          type: string
        blockchainAsset:
          allOf:
            - $ref: '#/components/schemas/BlockchainAsset'
          description: Resolved on-chain asset identity (protocol/chainId/tokenId).
        custodian:
          type: string
        id:
          type: string
        network:
          type: string
        otherCustodian:
          type: string
        txHash:
          type: string
      type: object
    WalletOmsDetails:
      description: 'WalletOms instrument details: an OMS-custodied crypto wallet.'
      properties:
        asset:
          type: string
        blockchainAddress:
          type: string
        blockchainAsset:
          allOf:
            - $ref: '#/components/schemas/BlockchainAsset'
          description: Resolved on-chain asset identity (protocol/chainId/tokenId).
        custodyType:
          enum:
            - custodial
            - embedded
          type: string
        id:
          description: Internal OMS wallet (acc_ prefix).
          type: string
        network:
          type: string
        txHash:
          type: string
      type: object
    AccountHolder:
      description: Who holds the payout bank account. `customer` is the only valid value.
      enum:
        - customer
      type: string
    PartyCustomer:
      description: The owning OMS customer is on this side.
      properties:
        customerId:
          type: string
        entityType:
          $ref: '#/components/schemas/OwnerType'
        relationship:
          enum:
            - customer
          type: string
      required:
        - relationship
        - customerId
      type: object
    PartyExternalRegistered:
      description: A registered counterparty (saved third party) is on this side.
      properties:
        address:
          allOf:
            - $ref: '#/components/schemas/Address'
          nullable: true
          type: object
        counterpartyId:
          type: string
        entityType:
          $ref: '#/components/schemas/OwnerType'
        name:
          nullable: true
          type: string
        relationship:
          enum:
            - externalRegistered
          type: string
      required:
        - relationship
        - counterpartyId
      type: object
    PartyExternalUnregistered:
      description: >-
        An unrecognized external party (no saved record) is on this side. There
        is no

        OMS record behind it, so it carries no entityType.
      properties:
        address:
          allOf:
            - $ref: '#/components/schemas/Address'
          nullable: true
          type: object
        name:
          nullable: true
          type: string
        relationship:
          enum:
            - externalUnregistered
          type: string
      required:
        - relationship
      type: object
    PartyOtherCustomer:
      description: A different OMS customer is on this side.
      properties:
        customerId:
          type: string
        entityType:
          $ref: '#/components/schemas/OwnerType'
        name:
          nullable: true
          type: string
        relationship:
          enum:
            - otherCustomer
          type: string
      required:
        - relationship
        - customerId
      type: object
    PayoutOriginBank:
      description: >-
        Payout originates from a bank account. Fields are wrapped in a `details`
        envelope (matches the `precursor` shape).
        `accountNumber`/`routingNumber` are full sending-account detail rendered
        on the transaction only; null on quote and deposit-address responses.
      properties:
        details:
          $ref: '#/components/schemas/PayoutOriginBankDetails'
        type:
          enum:
            - bank
          type: string
      required:
        - type
        - details
      type: object
    PayoutOriginBlockchain:
      description: Payout originates from an on-chain address.
      properties:
        blockchainAddress:
          type: string
        custodian:
          type: string
        network:
          type: string
        txHash:
          type: string
        type:
          enum:
            - blockchain
          type: string
      required:
        - type
      type: object
    Address:
      description: A postal address. country is an ISO 3166-1 alpha-2 country code.
      properties:
        city:
          type: string
        country:
          description: ISO 3166-1 alpha-2
          type: string
        line1:
          type: string
        line2:
          type: string
        state:
          type: string
        zipCode:
          type: string
      type: object
    SecCode:
      description: >-
        ACH SEC code. Populated only when the destination bank network is `ach`
        or `achSameDay`; null otherwise. Server-derived from the destination
        owner's and the source customer's `entityType`.
      enum:
        - ccd
        - ppd
        - web
      type: string
    BlockchainAsset:
      description: >-
        On-chain identity for an asset: the chain it lives on, the wire-level
        protocol (EVM, SVM, Sui), and the token identifier within that chain.
      properties:
        chainId:
          description: >-
            Chain identifier within the protocol (for example, an EVM chain ID
            or a Solana cluster name).
          type: string
        protocol:
          $ref: '#/components/schemas/BlockchainProtocol'
        tokenId:
          description: >-
            Token identifier on the chain (for example, an ERC-20 contract
            address or an SPL mint address). Use the chain's canonical
            representation for the native asset.
          type: string
      required:
        - protocol
        - chainId
        - tokenId
      type: object
    OwnerType:
      enum:
        - individual
        - business
      type: string
    PayoutOriginBankDetails:
      description: >-
        Bank payout-origin detail. `accountHolder`(+`Name`) is the chosen sender

        identity (echoed on Quote/DA too); `accountNumber`/`routingNumber` are
        the

        full sending-account coordinates (Transaction only, else null);
        `virtualAccountId`

        is the VA the funds were pulled from.
      properties:
        accountHolder:
          $ref: '#/components/schemas/AccountHolder'
        accountHolderName:
          type: string
        accountNumber:
          nullable: true
          type: string
        routingNumber:
          nullable: true
          type: string
        virtualAccountId:
          nullable: true
          type: string
      type: object
    BlockchainProtocol:
      description: >-
        Wire-level protocol family for a chain. `evm` covers Ethereum-compatible
        chains, `svm` covers the Solana virtual machine, and `sui` covers the
        Sui Move VM.
      enum:
        - evm
        - svm
        - sui
      type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Token from POST /auth/token

````