> ## 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 Withdrawal Request

> Submit a withdrawal request from a quote. When the project requires approval, the request waits for another person to approve it; the transaction is created on approval. Without approval, submit creates the transaction at once and can also return any error `POST /transactions` returns.



## OpenAPI

````yaml /api-reference/openapi.yaml post /withdrawal-requests
openapi: 3.0.3
info:
  title: Polygon OMS Public API
  version: v26.11.5-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
  - name: Customers
    description: Customer management and KYC
  - name: CustomerTokens
    description: Customer-bound tokens for browser SDK calls
  - name: Wallets
    description: Embedded wallet association
  - name: Webhooks
    description: Webhook endpoints, signing secrets, and event delivery
  - name: Wallet
  - name: Quote
  - name: Transaction
  - name: Transfer
  - name: CashIns
  - name: CashLocation
  - name: Sandbox
  - name: VirtualAccount
  - name: Counterparty
  - name: Withdrawal Request
  - name: ExternalAccount
  - name: Reference
  - name: DepositAddress
  - name: Indexer
    description: >-
      Read token balances, prices, and transaction history across EVM networks,
      Solana, and Tron. Indexer methods are webRPC calls: each is a `POST` with
      a JSON body, served at `/v1/{Service}/{Method}` on the API host rather
      than under the `/v0.13` base path. Authenticate with a publishable key in
      the `Api-Key` header, or with a bearer token from `POST /auth/token`.
paths:
  /withdrawal-requests:
    post:
      tags:
        - Withdrawal Request
      summary: Create a Withdrawal Request
      description: >-
        Submit a withdrawal request from a quote. When the project requires
        approval, the request waits for another person to approve it; the
        transaction is created on approval. Without approval, submit creates the
        transaction at once and can also return any error `POST /transactions`
        returns.
      operationId: createWithdrawalRequest
      parameters:
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WithdrawalRequestCreateRequest'
      responses:
        '201':
          description: >-
            The request has succeeded and a new resource has been created as a
            result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WithdrawalRequest'
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/InvalidQuoteErrorResponse'
                  - $ref: '#/components/schemas/MetadataKeyTooLongErrorResponse'
                  - $ref: '#/components/schemas/MetadataTooManyKeysErrorResponse'
                  - $ref: '#/components/schemas/MetadataValueTooLongErrorResponse'
        '403':
          description: Access is forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WithdrawalActorNotAllowedErrorResponse'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuoteNotFoundErrorResponse'
        '409':
          description: The request conflicts with the current state of the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WithdrawalQuoteAlreadyUsedErrorResponse'
        '422':
          description: Client error
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/QuoteConsumedErrorResponse'
                  - $ref: '#/components/schemas/QuoteExpiredErrorResponse'
                  - $ref: '#/components/schemas/QuoteMissingCustomerErrorResponse'
                  - $ref: '#/components/schemas/QuoteTypeMismatchErrorResponse'
                  - $ref: '#/components/schemas/ValidationErrorResponse'
                  - $ref: >-
                      #/components/schemas/WithdrawalDestinationNotAllowedErrorResponse
                  - $ref: >-
                      #/components/schemas/WithdrawalSourceNotAllowedErrorResponse
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalErrorResponse'
        '502':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WithdrawalRequest'
        '503':
          description: Service unavailable.
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/ProjectApprovalSettingUnavailableErrorResponse
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:
    WithdrawalRequestCreateRequest:
      type: object
      required:
        - quoteId
      properties:
        quoteId:
          type: string
          description: The quote to withdraw from (`qt_` prefix).
        webSessionId:
          type: string
          description: Web session id of the person submitting, for fraud screening.
        deviceFingerprint:
          type: string
          description: Device fingerprint of the person submitting, for fraud screening.
        metadata:
          type: object
          additionalProperties:
            type: string
          description: >-
            Free-form key-value pairs stored on the request and echoed back on
            reads.
      description: Submit a withdrawal request from a quote.
    WithdrawalRequest:
      type: object
      required:
        - id
        - quoteId
        - status
        - customer
        - source
        - destination
        - pricing
        - createdBy
        - createdAt
        - updatedAt
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/typeId'
          description: Withdrawal request ID (`wdr_` prefix).
        quoteId:
          allOf:
            - $ref: '#/components/schemas/typeId'
          description: >-
            The quote the request was submitted from (`qt_` prefix). Read it for
            the full destination, including the bank rail, when building the
            approval quote.
        status:
          allOf:
            - $ref: '#/components/schemas/WithdrawalRequestStatus'
          description: Current status.
        customer:
          allOf:
            - $ref: '#/components/schemas/CustomerRef'
          description: The customer the withdrawal is for.
        source:
          allOf:
            - $ref: '#/components/schemas/Instrument'
          description: The funding side, with resolved instrument detail.
        destination:
          allOf:
            - $ref: '#/components/schemas/TransactionDestinationInstrument'
          description: The receiving side, with resolved instrument detail.
        pricing:
          allOf:
            - $ref: '#/components/schemas/Pricing'
          description: Pricing from the latest quote.
        createdBy:
          allOf:
            - $ref: '#/components/schemas/Actor'
          description: Who submitted the request.
        reviewedBy:
          allOf:
            - $ref: '#/components/schemas/Actor'
          description: Who approved or rejected the request.
        reviewedAt:
          type: string
          format: date-time
          description: >-
            When the request was approved or rejected. Set for approved and
            rejected requests only.
        transactionId:
          allOf:
            - $ref: '#/components/schemas/typeId'
          description: The transaction an approved request created (`txn_` prefix).
        transaction:
          allOf:
            - $ref: '#/components/schemas/Transaction'
          description: >-
            The transaction an approved request created. Present on submit and
            approve responses only.
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Free-form key-value pairs supplied at submission.
        createdAt:
          type: string
          format: date-time
          description: When the request was created.
        updatedAt:
          type: string
          format: date-time
          description: When the request was last updated.
      description: >-
        A withdrawal submitted from a quote. When the project requires approval
        it waits for a second person, and approving creates the transaction;
        otherwise submitting creates the transaction at once.
    InvalidQuoteErrorResponse:
      type: object
      required:
        - error
        - code
        - msg
      properties:
        error:
          type: string
          enum:
            - InvalidQuote
        code:
          type: number
          enum:
            - 10269
        msg:
          type: string
          enum:
            - invalid quote
        cause:
          type: string
    MetadataKeyTooLongErrorResponse:
      type: object
      required:
        - error
        - code
        - msg
      properties:
        error:
          type: string
          enum:
            - MetadataKeyTooLong
        code:
          type: number
          enum:
            - 10075
        msg:
          type: string
          enum:
            - metadata key must be 64 characters or fewer
        cause:
          type: string
    MetadataTooManyKeysErrorResponse:
      type: object
      required:
        - error
        - code
        - msg
      properties:
        error:
          type: string
          enum:
            - MetadataTooManyKeys
        code:
          type: number
          enum:
            - 10074
        msg:
          type: string
          enum:
            - metadata may have at most 20 keys
        cause:
          type: string
    MetadataValueTooLongErrorResponse:
      type: object
      required:
        - error
        - code
        - msg
      properties:
        error:
          type: string
          enum:
            - MetadataValueTooLong
        code:
          type: number
          enum:
            - 10076
        msg:
          type: string
          enum:
            - metadata value must be 500 characters or fewer
        cause:
          type: string
    WithdrawalActorNotAllowedErrorResponse:
      type: object
      required:
        - error
        - code
        - msg
      properties:
        error:
          type: string
          enum:
            - WithdrawalActorNotAllowed
        code:
          type: number
          enum:
            - 10401
        msg:
          type: string
          enum:
            - the caller is not allowed to act on this withdrawal request
        cause:
          type: string
    QuoteNotFoundErrorResponse:
      type: object
      required:
        - error
        - code
        - msg
      properties:
        error:
          type: string
          enum:
            - QuoteNotFound
        code:
          type: number
          enum:
            - 10260
        msg:
          type: string
          enum:
            - quote not found
        cause:
          type: string
    WithdrawalQuoteAlreadyUsedErrorResponse:
      type: object
      required:
        - error
        - code
        - msg
      properties:
        error:
          type: string
          enum:
            - WithdrawalQuoteAlreadyUsed
        code:
          type: number
          enum:
            - 10404
        msg:
          type: string
          enum:
            - the quote was already used for a withdrawal
        cause:
          type: string
    QuoteConsumedErrorResponse:
      type: object
      required:
        - error
        - code
        - msg
      properties:
        error:
          type: string
          enum:
            - QuoteConsumed
        code:
          type: number
          enum:
            - 10262
        msg:
          type: string
          enum:
            - quote has already been consumed
        cause:
          type: string
    QuoteExpiredErrorResponse:
      type: object
      required:
        - error
        - code
        - msg
      properties:
        error:
          type: string
          enum:
            - QuoteExpired
        code:
          type: number
          enum:
            - 10077
        msg:
          type: string
          enum:
            - quote has expired
        cause:
          type: string
    QuoteMissingCustomerErrorResponse:
      type: object
      required:
        - error
        - code
        - msg
      properties:
        error:
          type: string
          enum:
            - QuoteMissingCustomer
        code:
          type: number
          enum:
            - 10256
        msg:
          type: string
          enum:
            - quote has no customer
        cause:
          type: string
    QuoteTypeMismatchErrorResponse:
      type: object
      required:
        - error
        - code
        - msg
      properties:
        error:
          type: string
          enum:
            - QuoteTypeMismatch
        code:
          type: number
          enum:
            - 10261
        msg:
          type: string
          enum:
            - unsupported quote type for transactions
        cause:
          type: string
    ValidationErrorResponse:
      type: object
      required:
        - error
        - code
        - msg
      properties:
        error:
          type: string
          enum:
            - Validation
        code:
          type: number
          enum:
            - 10030
        msg:
          type: string
          enum:
            - request validation failed
        cause:
          type: string
    WithdrawalDestinationNotAllowedErrorResponse:
      type: object
      required:
        - error
        - code
        - msg
      properties:
        error:
          type: string
          enum:
            - WithdrawalDestinationNotAllowed
        code:
          type: number
          enum:
            - 10403
        msg:
          type: string
          enum:
            - a withdrawal cannot pay a fiat wallet, a card or its own source
        cause:
          type: string
    WithdrawalSourceNotAllowedErrorResponse:
      type: object
      required:
        - error
        - code
        - msg
      properties:
        error:
          type: string
          enum:
            - WithdrawalSourceNotAllowed
        code:
          type: number
          enum:
            - 10402
        msg:
          type: string
          enum:
            - >-
              a withdrawal must be funded by one of the customer's OMS wallets
              or debit cards
        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
    ProjectApprovalSettingUnavailableErrorResponse:
      type: object
      required:
        - error
        - code
        - msg
      properties:
        error:
          type: string
          enum:
            - ProjectApprovalSettingUnavailable
        code:
          type: number
          enum:
            - 10405
        msg:
          type: string
          enum:
            - the project approval setting is temporarily unavailable
        cause:
          type: string
    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`.
      x-go-type: string
    WithdrawalRequestStatus:
      type: string
      enum:
        - pendingApproval
        - approved
        - rejected
        - cancelled
      description: >-
        Lifecycle of a withdrawal request. `pendingApproval` becomes `approved`,
        `rejected` or `cancelled`; the last three are final.
    CustomerRef:
      type: object
      required:
        - id
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/typeId'
          description: The customer id (`cst_` prefix).
      description: >-
        The customer, referenced by id; its name and details are on the customer
        resource.
    Instrument:
      type: object
      oneOf:
        - $ref: '#/components/schemas/WalletCryptoInstrument'
        - $ref: '#/components/schemas/WalletExternalInstrument'
        - $ref: '#/components/schemas/WalletFiatInstrument'
        - $ref: '#/components/schemas/BankUsAccount'
        - $ref: '#/components/schemas/BankIbanAccount'
        - $ref: '#/components/schemas/BankCanadaAccount'
        - $ref: '#/components/schemas/CardInstrument'
        - $ref: '#/components/schemas/CashInstrument'
        - $ref: '#/components/schemas/DepositAddressInstrument'
        - $ref: '#/components/schemas/VirtualAccountInstrument'
      discriminator:
        propertyName: type
        mapping:
          walletCrypto: '#/components/schemas/WalletCryptoInstrument'
          walletExternal: '#/components/schemas/WalletExternalInstrument'
          walletFiat: '#/components/schemas/WalletFiatInstrument'
          bankUs: '#/components/schemas/BankUsAccount'
          bankIban: '#/components/schemas/BankIbanAccount'
          bankCanada: '#/components/schemas/BankCanadaAccount'
          card: '#/components/schemas/CardInstrument'
          cash: '#/components/schemas/CashInstrument'
          depositAddress: '#/components/schemas/DepositAddressInstrument'
          virtualAccount: '#/components/schemas/VirtualAccountInstrument'
      description: >-
        A transaction's source or a transfer's end: one instrument per account
        type. A bank account carries no rail and no ACH options; they are on the
        transfer.
    TransactionDestinationInstrument:
      type: object
      oneOf:
        - $ref: '#/components/schemas/WalletCryptoInstrument'
        - $ref: '#/components/schemas/WalletExternalInstrument'
        - $ref: '#/components/schemas/WalletFiatInstrument'
        - $ref: '#/components/schemas/BankUsAccount'
        - $ref: '#/components/schemas/BankIbanAccount'
        - $ref: '#/components/schemas/BankCanadaAccount'
        - $ref: '#/components/schemas/CardInstrument'
        - $ref: '#/components/schemas/CashPickupInstrument'
      discriminator:
        propertyName: type
        mapping:
          walletCrypto: '#/components/schemas/WalletCryptoInstrument'
          walletExternal: '#/components/schemas/WalletExternalInstrument'
          walletFiat: '#/components/schemas/WalletFiatInstrument'
          bankUs: '#/components/schemas/BankUsAccount'
          bankIban: '#/components/schemas/BankIbanAccount'
          bankCanada: '#/components/schemas/BankCanadaAccount'
          card: '#/components/schemas/CardInstrument'
          cash: '#/components/schemas/CashPickupInstrument'
      description: >-
        The receiving side of a transaction: one instrument per account type.
        The rail, the ACH options and where the payout is sent from are on the
        transaction's payout transfer.
    Pricing:
      type: object
      required:
        - fees
      properties:
        source:
          allOf:
            - $ref: '#/components/schemas/PricingSide'
          description: The source side, in the source asset.
        destination:
          allOf:
            - $ref: '#/components/schemas/PricingSide'
          description: The destination side, in the destination asset.
        fees:
          type: array
          items:
            $ref: '#/components/schemas/PricingFee'
          description: >-
            Every fee charged across both sides. `[]` when there are none —
            never omitted, never null.
        exchangeRate:
          type: string
          description: >-
            Mid-market rate from the source asset to the destination asset, set
            together with the destination amount. Identity: (source.amount − Σ
            source fees) × exchangeRate = destination.amount + Σ destination
            fees.
        fixedAmountSide:
          type: string
          enum:
            - source
            - destination
          description: >-
            The side whose amount was fixed at creation. OMS calculated the
            other side.
        sponsorGas:
          type: boolean
          description: >-
            Present and `true` when OMS absorbs the destination gas cost;
            omitted otherwise.
      description: >-
        Consolidated economics for a quote, transaction or cash-in: per-side
        amounts, a flat fee list, the mid-market rate and gas sponsorship.
    Actor:
      type: object
      required:
        - type
        - id
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/ActorType'
          description: Whether the actor is a person or an API key.
        id:
          type: string
          description: The actor's id.
      description: The person or API key that took an action.
    Transaction:
      type: object
      required:
        - id
        - status
        - subStatus
        - customer
        - source
        - destination
        - pricing
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/typeId'
          description: Transaction ID (`txn_` prefix).
        status:
          allOf:
            - $ref: '#/components/schemas/TransactionStatus'
          description: Current lifecycle status. See `subStatus` for finer granularity.
        subStatus:
          allOf:
            - $ref: '#/components/schemas/TransactionSubStatus'
          description: >-
            Status-scoped sub-state (e.g. `processing.fundsPulled`). Always
            present: each status carries a default member (e.g.
            `processing.initiated`) when no more specific value applies.
        customer:
          allOf:
            - $ref: '#/components/schemas/CustomerRef'
          description: The customer that owns this record — the sender on a transaction.
        precursor:
          allOf:
            - $ref: '#/components/schemas/Precursor'
          description: >-
            What created this transaction, as a uniform `{type, id}` reference —
            dereference the resource by `id` for its full record. A
            custodial-wallet deposit renders `{type: walletDeposit}`. Left out
            for a genuine out-of-band arrival with no recognised origin at all;
            the `manual` arm is reserved for a future operator-initiated
            transaction, distinct from either.
        source:
          allOf:
            - $ref: '#/components/schemas/Instrument'
          description: >-
            The funding side, as an instrument. A bank account carries no rail:
            how the money moved is on the transaction's transfers.
        destination:
          allOf:
            - $ref: '#/components/schemas/TransactionDestinationInstrument'
          description: >-
            The receiving side, as an instrument. The rail and the ACH options
            are on the transaction's payout transfer.
        payoutOrigin:
          allOf:
            - $ref: '#/components/schemas/PayoutOrigin'
          description: >-
            Whose name the payout goes out under. Left out when nothing is paid
            out to a bank account, a card or a wallet.
        pricing:
          allOf:
            - $ref: '#/components/schemas/Pricing'
          description: Consolidated economics.
        transfers:
          type: array
          items:
            $ref: '#/components/schemas/TransferRef'
          description: >-
            The transaction's transfers, in creation order: each movement of its
            money on one rail. Left out until the first transfer exists; fetch
            one with `GET /transfers/{transferId}`.
        failure:
          allOf:
            - $ref: '#/components/schemas/Reason'
          description: Why the transaction failed. Present only when `status` is `failed`.
        hold:
          allOf:
            - $ref: '#/components/schemas/Hold'
          description: >-
            What the partner must do while `status` is `awaitingAction`. Left
            out in every other status.
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Free-form key-value pairs supplied at creation or update.
        createdAt:
          type: string
          format: date-time
          description: When the transaction was created.
        updatedAt:
          type: string
          format: date-time
          description: When the transaction was last updated.
        completedAt:
          type: string
          format: date-time
          description: >-
            When the transaction first reached `completed`: the source leg's
            completion for a single-leg transaction, the payout leg's for a
            multi-leg one. Written once and never moved by a later provider
            notification. Present only while `status` is `completed`: a
            completed transaction that is later reversed (for example a returned
            payout) drops it.
      description: >-
        A single movement of money from a source to a destination. Created by
        accepting a quote, or generated automatically by a deposit address,
        virtual account, or cash-in. Track its progress with status.
    WalletCryptoInstrument:
      type: object
      required:
        - type
        - asset
        - network
      properties:
        type:
          type: string
          enum:
            - walletCrypto
        id:
          allOf:
            - $ref: '#/components/schemas/typeId'
          description: >-
            The wallet (`wlt_`); an older wallet keeps its original `wlt_<uuid>`
            id. Left out while a deposit's receiving wallet is not resolved yet.
        asset:
          type: string
          description: Lowercase asset.
        network:
          type: string
          description: Lowercase blockchain.
        owner:
          $ref: '#/components/schemas/InstrumentOwner'
        details:
          $ref: '#/components/schemas/WalletCryptoInstrumentDetails'
      description: An OMS-custodied crypto wallet.
      title: OMS wallet
    WalletExternalInstrument:
      type: object
      required:
        - type
        - asset
        - network
      properties:
        type:
          type: string
          enum:
            - walletExternal
        id:
          allOf:
            - $ref: '#/components/schemas/typeId'
          description: >-
            The external account (`ext_`). Left out for a sender OMS has no
            record of.
        asset:
          type: string
          description: Lowercase asset.
        network:
          type: string
          description: Lowercase blockchain.
        owner:
          $ref: '#/components/schemas/InstrumentOwner'
        details:
          $ref: '#/components/schemas/WalletExternalInstrumentDetails'
      description: A crypto wallet OMS does not custody.
      title: External wallet
    WalletFiatInstrument:
      type: object
      required:
        - type
        - asset
      properties:
        type:
          type: string
          enum:
            - walletFiat
        id:
          type: string
          pattern: >-
            ^(wlt_fiat_|[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: >-
            The fiat wallet (`wlt_`; an older wallet keeps its original
            `wlt_<uuid>` id, and a `wlt_fiat_` id is also accepted on input).
            Left out on a book-transfer destination until its outbound leg
            exists.
        asset:
          type: string
          enum:
            - usd
          description: Fiat currency of the balance. Only `usd` today.
        network:
          type: string
          enum:
            - bookTransfer
            - intraBank
          description: >-
            On the destination of a virtual account or deposit address
            book-transfer credit: `intraBank`, or `bookTransfer` on a record
            created before the umbrella names were introduced.
        intraBankRail:
          allOf:
            - $ref: '#/components/schemas/IntraBankRail'
          description: Only when `network` is `intraBank`.
        owner:
          $ref: '#/components/schemas/InstrumentOwner'
      description: >-
        A fiat balance wallet OMS holds for the customer at a partner bank. It
        has no details.
      title: Fiat wallet
    BankUsAccount:
      type: object
      required:
        - type
        - asset
      properties:
        type:
          type: string
          enum:
            - bankUs
        id:
          allOf:
            - $ref: '#/components/schemas/typeId'
          description: >-
            The external account (`ext_`). Left out for a sender OMS has no
            record of.
        asset:
          type: string
          enum:
            - usd
          description: Lowercase asset.
        instantRail:
          allOf:
            - $ref: '#/components/schemas/InstantRail'
          description: Only when `network` is `instant`.
        owner:
          $ref: '#/components/schemas/InstrumentOwner'
        details:
          $ref: '#/components/schemas/BankUsInstrumentDetails'
      description: >-
        A US bank account. It carries no rail: how money moved is the transfer's
        `rail`.
      title: US bank account
    BankIbanAccount:
      type: object
      required:
        - type
        - asset
      properties:
        type:
          type: string
          enum:
            - bankIban
        id:
          allOf:
            - $ref: '#/components/schemas/typeId'
          description: >-
            The external account (`ext_`). Left out for a sender OMS has no
            record of.
        asset:
          type: string
          description: Lowercase asset.
        owner:
          $ref: '#/components/schemas/InstrumentOwner'
        details:
          $ref: '#/components/schemas/BankIbanInstrumentDetails'
      description: >-
        An IBAN bank account. It carries no rail: how money moved is the
        transfer's `rail`.
      title: IBAN bank account
    BankCanadaAccount:
      type: object
      required:
        - type
        - asset
      properties:
        type:
          type: string
          enum:
            - bankCanada
        id:
          allOf:
            - $ref: '#/components/schemas/typeId'
          description: >-
            The external account (`ext_`). Left out for a sender OMS has no
            record of.
        asset:
          type: string
          enum:
            - usd
            - cad
          description: Lowercase asset.
        owner:
          $ref: '#/components/schemas/InstrumentOwner'
        details:
          $ref: '#/components/schemas/BankCanadaInstrumentDetails'
      description: >-
        A Canadian bank account. It carries no rail: how money moved is the
        transfer's `rail`.
      title: Canadian bank account
    CardInstrument:
      type: object
      required:
        - type
        - asset
      properties:
        type:
          type: string
          enum:
            - card
        id:
          allOf:
            - $ref: '#/components/schemas/typeId'
          description: The external account (`ext_`).
        asset:
          type: string
          enum:
            - usd
          description: Lowercase asset.
        network:
          type: string
          enum:
            - card
          description: The rail the money moves on.
        owner:
          $ref: '#/components/schemas/InstrumentOwner'
        details:
          $ref: '#/components/schemas/CardInstrumentDetails'
      description: A card.
      title: Card
    CashInstrument:
      type: object
      required:
        - type
        - asset
      properties:
        type:
          type: string
          enum:
            - cash
        asset:
          type: string
          description: Lowercase asset.
        details:
          $ref: '#/components/schemas/CashInstrumentDetails'
      description: A cash location. It has no id; the location is in `details`.
      title: Cash
    DepositAddressInstrument:
      type: object
      required:
        - type
        - asset
        - network
      properties:
        type:
          type: string
          enum:
            - depositAddress
        id:
          allOf:
            - $ref: '#/components/schemas/typeId'
          description: The deposit address (`da_`).
        asset:
          type: string
          description: Lowercase asset.
        network:
          type: string
          description: Lowercase blockchain.
        owner:
          $ref: '#/components/schemas/InstrumentOwner'
        details:
          $ref: '#/components/schemas/DepositAddressInstrumentDetails'
      description: A deposit address.
      title: Deposit address
    VirtualAccountInstrument:
      type: object
      required:
        - type
        - asset
      properties:
        type:
          type: string
          enum:
            - virtualAccount
        id:
          allOf:
            - $ref: '#/components/schemas/typeId'
          description: The virtual account (`va_`).
        asset:
          type: string
          description: Lowercase asset.
        owner:
          $ref: '#/components/schemas/InstrumentOwner'
        details:
          $ref: '#/components/schemas/VirtualAccountInstrumentDetails'
      description: A virtual account.
      title: Virtual account
    CashPickupInstrument:
      type: object
      required:
        - type
        - asset
      properties:
        type:
          type: string
          enum:
            - cash
        asset:
          type: string
          description: Lowercase asset.
        details:
          $ref: '#/components/schemas/CashInstrumentDetails'
        pickupCode:
          type: string
          description: Retail pickup code for a cash payout.
      description: A cash location a payout is collected at.
      title: Cash
    PricingSide:
      type: object
      required:
        - asset
      properties:
        amount:
          type: string
          description: >-
            On the source, the gross amount the customer pays; on the
            destination, the amount that arrives. A decimal string at the
            asset's precision. Always set on the source; set on the destination
            once priced.
        asset:
          type: string
          description: >-
            Lowercase asset of this side, the same as the side's instrument
            asset.
      description: >-
        One side of `pricing`, in that side's asset. Fees are listed in
        `Pricing.fees`.
    PricingFee:
      type: object
      required:
        - type
        - side
        - asset
        - amount
      properties:
        type:
          type: string
          description: >-
            Fee kind. OPEN — clients must tolerate an unrecognised type. Known
            values today: "developer", "oms", "gas", "retailer" (a cash
            provider's retail fee, on `CashIn.providerFee`), "exchange" (the
            exchange fee the crypto purchase realized, on the linked transaction
            once it completes).
        side:
          type: string
          enum:
            - source
            - destination
          description: Which side this fee was deducted from.
        asset:
          type: string
          description: Currency this fee is denominated in — that side's asset.
        amount:
          type: string
          description: Fee amount in `asset`, at the asset's precision.
      description: >-
        A fee charged on one side of a quote, transaction or cash-in. A fee is
        listed only when it is not zero.
    ActorType:
      type: string
      enum:
        - user
        - apiKey
    TransactionStatus:
      type: string
      enum:
        - processing
        - awaitingAction
        - completed
        - failed
      description: >-
        Lifecycle of a transaction. processing: funds in motion. awaitingAction:
        non-terminal, blocked on developer/upstream/compliance (see `hold`);
        returns to processing once cleared. completed: delivered. failed: the
        payment ended without delivering. Both can still change afterwards: a
        bank can take back money that settled (a returned payout or refund reads
        `processing.underReview`, a returned deposit `failed.returnedToSender`),
        a deposit that failed can still settle (a late provider report or an
        operator redrive), and a return to the sender can start after a failure
        (`processing.returningToSender`).
    TransactionSubStatus:
      type: string
      enum:
        - processing.fundsPulled
        - processing.cashPickupReady
        - processing.underReview
        - processing.payoutRetrying
        - processing.payoutUnconfirmed
        - processing.payoutHeld
        - processing.returningToSender
        - completed.cashPickupCollected
        - completed.cashPickupExpired
        - awaitingAction.informationRequested
        - awaitingAction.awaitingSenderAttribution
        - awaitingAction.payoutDestinationMissing
        - awaitingAction.depositAddressFrozen
        - failed.attributionTimeout
        - failed.depositAddressFrozenTimeout
        - failed.depositAddressInactiveTimeout
        - failed.depositAddressClosed
        - processing.awaitingCryptoOut
        - processing.cryptoOut
        - processing.awaitingFiatOut
        - processing.fiatOut
        - processing.inboundPending
        - processing.inboundProcessing
        - failed.inboundFailed
        - failed.returnedToSender
        - processing.initiated
        - completed.settled
        - failed.unspecified
        - failed.expired
        - failed.providerDeclined
        - failed.outboundFailed
      description: >-
        Granular sub-status in dotted form — the prefix before the dot is always
        the coarse `status`. Required and never null: `processing`, `completed`
        and `failed` each carry a default member (`processing.initiated`,
        `completed.settled`, `failed.unspecified`) emitted when no more specific
        value applies; `failed.unspecified` means the transaction failed with no
        recorded reason. `awaitingAction` has no default member: every
        `awaitingAction.*` value names a specific blocking reason, and the ones
        below pair with the transaction's `hold`:
        `awaitingAction.awaitingSenderAttribution` → `hold.code`
        `senderAttribution`, `awaitingAction.payoutDestinationMissing` →
        `payoutDestinationMissing`. Each value means one thing whichever vendor
        or flow produced it: `processing.payoutRetrying` is a new attempt of a
        payout that failed, `processing.payoutUnconfirmed` is a payout we
        stopped waiting on because the provider never confirmed it,
        `processing.payoutHeld` is a payout the provider accepted and holds
        until the partner's prefunded balance covers it (topping up releases
        it), `processing.returningToSender` is a refund in flight, and
        `processing.underReview` is money we hold while we decide what happens
        next. Neither `processing.payoutUnconfirmed` nor
        `processing.underReview` has a deadline: the transaction stays there
        until the provider answers or we resolve it, and its next
        `transaction.statusChanged` event carries the outcome.
        `failed.returnedToSender` means the money reached the sender again,
        whichever way: we sent the deposit back (crypto or bank), or the bank
        returned the deposit (an ACH or wire return). It never means a payout or
        refund the receiving bank returned: that money comes back to us, and the
        transaction reads `processing.underReview` while we decide what happens
        next. New members may be added without an API version bump, so clients
        MUST tolerate unknown values by falling back to the prefix before the
        dot (the dotted form exists precisely for this). The values below are
        the complete set emitted by this release; a client that validates
        against this list, including one generated from this schema, must be
        updated before it can accept a new member.
    Precursor:
      type: object
      required:
        - type
        - id
      properties:
        type:
          type: string
          enum:
            - quote
            - depositAddress
            - virtualAccount
            - cashIn
            - manual
            - walletDeposit
        id:
          type: string
          allOf:
            - $ref: '#/components/schemas/typeId'
          nullable: true
          description: >-
            `qt_` / `da_` / `va_` / `ci_`. Null for `manual` and
            `walletDeposit`.
      description: >-
        What created this transaction, as a uniform `{type, id}` reference.
        Dereference the resource by `id` for its full record — deposit
        instructions live on the Virtual Account / Deposit Address / Cash-In,
        not here. `id` is null only for `manual` (operator-initiated, no origin
        resource) and `walletDeposit` (a custodial-wallet deposit, no
        originating OMS resource). The `precursor` field on Transaction is
        itself nullable separately, for out-of-band arrivals with no originating
        OMS resource and no recognised origin.
    PayoutOrigin:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - bank
            - blockchain
        id:
          $ref: '#/components/schemas/typeId'
        accountHolder:
          allOf:
            - $ref: '#/components/schemas/PayoutOriginAccountHolder'
          description: >-
            Whose legal identity the payment is sent under. Determined by OMS
            from the route's configuration — not a request field. Left out when
            OMS cannot determine it, and on destinations that have no sending
            legal identity (cash payouts, and crypto payouts outside a Deposit
            Address). A bank payout that goes out under the payment provider or
            the partner records that holder just before it is sent to the
            provider, and reports it only while a payout was or may have been
            created there; a send interrupted after the holder was recorded and
            before it went out has an unknown outcome and may report it. A
            failed send known to have created no payout at the provider, and a
            payout sent before holders were recorded whose holder could not be
            recovered afterwards, report the fallback value instead, which may
            differ from the holder actually used. The fallback value, also
            reported before a holder is recorded and for payouts that always go
            out under the customer's own name, is the holder the Deposit Address
            fixed for the destination type the transaction pays on a transaction
            created from a Deposit Address, and the value its route implies on
            any other.
        accountHolderName:
          type: string
          description: >-
            The legal name the payment is sent under, resolved from
            `accountHolder` — the customer's own legal name for `customer`, the
            owning customer's legal name for `partner` (for now; a partner-level
            name may replace it later), or the payment provider's name for
            `paymentProvider`, which differs between a `bank` origin ("Coinme
            Inc FBO its Customers") and a `blockchain` origin. This is what the
            recipient sees as the sender. Like `accountHolder` and unlike `id`,
            it is populated as soon as it is determinable, so it appears on
            Quote, Deposit Address and Virtual Account responses as well as
            Transactions. Left out whenever `accountHolder` is, and when the
            customer's name cannot be read at that moment.
      description: >-
        Where last-mile delivery is sent *from*, as a uniform `{type, id}`
        reference — response-only. `id` is the Virtual Account (`va_`) or OMS
        wallet (`wlt_`) funding the leg; left out before execution (Quote /
        Deposit Address echo the choice only) or when the origin has no
        partner-visible resource. Rail identifiers for the last-mile transfer
        live in the top-level `tracking` array with `leg: destination` — not
        here.
    TransferRef:
      type: object
      required:
        - id
        - role
        - rail
        - attempt
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/typeId'
          description: Transfer ID (`trf_` prefix).
        role:
          $ref: '#/components/schemas/TransferRole'
        rail:
          $ref: '#/components/schemas/TransferRail'
        instantRail:
          allOf:
            - $ref: '#/components/schemas/InstantRail'
          description: Only when `rail` is `instant`.
        intraBankRail:
          allOf:
            - $ref: '#/components/schemas/IntraBankRail'
          description: Only when `rail` is `intraBank`.
        attempt:
          type: integer
          format: int32
          description: >-
            1 for the first send; a payout sent again after a confirmed failure
            is a new transfer with `attempt` + 1.
      description: A transfer of a transaction.
    Reason:
      type: object
      required:
        - code
        - message
        - retryable
      properties:
        code:
          allOf:
            - $ref: '#/components/schemas/ReasonCode'
          description: What went wrong.
        message:
          type: string
          description: A fixed, vendor-neutral sentence for `code`.
        retryable:
          type: boolean
          description: Whether trying the same thing again can succeed.
        bankCode:
          type: string
          description: >-
            The bank's own return code, only on an external account a bank
            return made invalid.
      description: >-
        Why a resource failed, was rejected or became invalid. `message` and
        `retryable` are fixed for each `code`.
    Hold:
      type: object
      required:
        - code
        - message
      properties:
        code:
          allOf:
            - $ref: '#/components/schemas/HoldCode'
          description: Why the resource is held.
        message:
          type: string
          description: A fixed, vendor-neutral sentence for `code`.
        deadline:
          type: string
          format: date-time
          description: >-
            When the hold times out and the transaction fails. Only on
            `senderAttribution`.
        match:
          allOf:
            - $ref: '#/components/schemas/HoldMatch'
          description: >-
            The sender's address and network to register to release the hold.
            Only on `senderAttribution`.
      description: >-
        What the partner must do for a transaction in `awaitingAction`, or a
        deposit address or a virtual account in `inactiveActionRequired`.
        `message` is a fixed sentence for each `code`.
    InstrumentOwner:
      type: object
      required:
        - kind
        - id
      properties:
        kind:
          type: string
          enum:
            - counterparty
            - customer
          description: '`counterparty`, or `customer` for another customer''s account.'
        id:
          allOf:
            - $ref: '#/components/schemas/typeId'
          description: The counterparty (`ctp_`) or customer (`cst_`).
        name:
          type: string
          description: >-
            The counterparty's name. A customer's name is on the customer
            resource.
      description: Who owns an account that is not the resource's customer's.
    WalletCryptoInstrumentDetails:
      type: object
      properties:
        address:
          type: string
          description: On-chain address.
      description: OMS crypto wallet details.
    WalletExternalInstrumentDetails:
      type: object
      properties:
        address:
          type: string
          description: On-chain address.
        custodian:
          type: string
          description: Who custodies the wallet, in lowerCamelCase.
        otherCustodian:
          type: string
          description: The custodian's name when `custodian` is `other`.
        networkFamily:
          $ref: '#/components/schemas/NetworkFamily'
      description: External wallet details.
    IntraBankRail:
      type: string
      enum:
        - bookTransfer
        - crnow
        - ereborRail
      description: >-
        The rail an `intraBank` payment rides between two accounts at the same
        bank: `bookTransfer`, `crnow` or `ereborRail`.
    InstantRail:
      type: string
      enum:
        - rtp
        - fednow
      description: >-
        The rail an `instant` payment rides: `rtp` (RTP over The Clearing House)
        or `fednow`.
    BankUsInstrumentDetails:
      type: object
      properties:
        bankName:
          type: string
        accountNumberLast4:
          type: string
        routingNumber:
          type: string
        accountType:
          $ref: '#/components/schemas/BankAccountType'
        holderName:
          type: string
          description: >-
            The account holder: a counterparty's name, or the sender's name when
            the rail carries it.
        memo:
          type: string
          description: >-
            The free-text message that travelled with the money on this side's
            rail.
      description: US bank account details.
    BankIbanInstrumentDetails:
      type: object
      properties:
        bankName:
          type: string
        ibanLast4:
          type: string
        bic:
          type: string
        countryCode:
          type: string
          description: ISO 3166-1 alpha-2 country of the bank.
        bankAddress:
          $ref: '#/components/schemas/Address'
        holderName:
          type: string
          description: >-
            The account holder: a counterparty's name, or the sender's name when
            the rail carries it.
        memo:
          type: string
          description: >-
            The free-text message that travelled with the money on this side's
            rail.
      description: IBAN bank account details.
    BankCanadaInstrumentDetails:
      type: object
      properties:
        bankName:
          type: string
        accountNumberLast4:
          type: string
        institutionNumber:
          type: string
        transitNumber:
          type: string
        holderName:
          type: string
          description: >-
            The account holder: a counterparty's name, or the sender's name when
            the rail carries it.
        memo:
          type: string
          description: >-
            The free-text message that travelled with the money on this side's
            rail.
      description: Canadian bank account details.
    CardInstrumentDetails:
      type: object
      properties:
        brand:
          $ref: '#/components/schemas/CardBrand'
        last4:
          type: string
        cardType:
          $ref: '#/components/schemas/CardType'
        expiryMonth:
          type: integer
          format: int32
        expiryYear:
          type: integer
          format: int32
        billingAddressSource:
          $ref: '#/components/schemas/BillingAddressSource'
      description: Card details.
    CashInstrumentDetails:
      type: object
      properties:
        locationId:
          type: string
        locationName:
          type: string
        locationAddress:
          $ref: '#/components/schemas/Address'
        locationProvider:
          type: string
          description: >-
            The cash network the location belongs to, lowercase, such as
            `greendot`.
      description: Cash location details.
    DepositAddressInstrumentDetails:
      type: object
      properties:
        address:
          type: string
          description: On-chain address.
      description: Deposit address details.
    VirtualAccountInstrumentDetails:
      type: object
      properties:
        bankName:
          type: string
        accountNumberLast4:
          type: string
        routingNumber:
          type: string
      description: >-
        Virtual account details. The full account number is in the virtual
        account's deposit instructions.
    PayoutOriginAccountHolder:
      type: string
      enum:
        - customer
        - paymentProvider
        - partner
      description: >-
        Whose legal name an outbound payment is sent under — the name that
        appears on the recipient's statement. Determined by which institution
        executes the payout and by your project's configuration, not by anything
        you send: outbound fiat executed by Erebor Bank, N.A. goes out under the
        customer's own legal name (`customer`), while outbound fiat executed by
        Cross River Bank goes out under the payment provider (`paymentProvider`,
        `accountHolderName` "Coinme Inc FBO its Customers") or, on a project
        configured to send under its own name, under the partner (`partner`). A
        Deposit Address created while its customer holds an active Virtual
        Account from the same provider fixes `customer` as its bank holder;
        payouts are not sent from that account, so each of its transactions
        reports the holder described on `PayoutOrigin.accountHolder`. Crypto
        sent from a Deposit Address goes out under whoever holds the sending
        wallet. Read the pair rather than inferring either from a resource's
        `provider` field, which names the custodian of the account and can be a
        different company entirely. On a Virtual Account the pair is reported as
        a top-level `payoutOrigin`, present for its bank and crypto-wallet
        destinations and absent for `walletFiat`. A cash payout has no
        `payoutOrigin`, and a crypto payout outside a Deposit Address leaves the
        pair out. New values may be added.
    TransferRole:
      type: string
      enum:
        - deposit
        - payout
        - refund
      description: >-
        What a transfer does in its transaction. `deposit` brings money in,
        `payout` sends it out and `refund` sends it back to the sender. A bank
        return is the transfer's `returned` status, not a role.
    TransferRail:
      type: string
      enum:
        - ach
        - achSameDay
        - wire
        - internationalWire
        - rtp
        - bookTransfer
        - instant
        - intraBank
        - blockchain
        - card
        - cash
      description: >-
        How a transfer's money moved. `instant` is an RTP or FedNow payout,
        named in `instantRail`; `intraBank` stays inside the bank, named in
        `intraBankRail`. A record created before the umbrella names were
        introduced keeps `rtp` or `bookTransfer`.
    ReasonCode:
      type: string
      enum:
        - providerError
        - providerRejected
        - providerTimeout
        - expired
        - systemError
        - provisioningTimeout
        - insufficientFunds
        - providerAmountBelowMinimum
        - limitExceeded
        - outsideSellBounds
        - outsideSellVelocityBounds
        - unusableAmount
        - unsupportedCorridor
        - outgoingRailNotEnabled
        - ssnNotVerified
        - riskRejected
        - cardDeclined
        - bankSellDeclined
        - payoutFailed
        - priceMoved
        - returningToSender
        - returnedToSender
        - returnFailed
        - depositFailed
        - attributionTimeout
        - assetMismatch
        - chainMismatch
        - misattributedArrival
        - depositAddressNotActive
        - virtualAccountNotActive
        - counterpartyArchived
        - destinationUnavailable
        - walletClaimed
        - walletBoundToCustodialFlow
        - projectSuspended
        - memoInvalid
        - cashDepositFailed
        - noMatchingNetwork
        - blockchainAddressInUse
        - bankAccountInUse
        - bankAccountRejected
        - deletePendingTimeout
        - providerAccountMissing
        - cardInUse
        - cardLimitReached
        - countryProhibited
        - countryNotSupported
        - cardVerificationDeclined
        - bankVerificationDeclined
        - accountClosed
        - accountFrozenByBank
        - routingOrAccountNumberInvalid
        - accountHolderDeceased
        - accountDoesNotSupportTransfers
        - payeeNameMismatch
        - walletUnreachableOnNetwork
        - billingAddressMismatch
        - cardExpired
        - cardClosedOrLostStolen
        - pushToCardUnsupported
        - cardDeclinedByIssuer
      description: The reasons a resource reports in `failure`.
    HoldCode:
      type: string
      enum:
        - senderAttribution
        - payoutDestinationMissing
      description: >-
        Why a transaction is held in `awaitingAction`, or a deposit address in
        `inactiveActionRequired`.
    HoldMatch:
      type: object
      required:
        - address
        - network
      properties:
        address:
          type: string
          description: The sender's on-chain address.
        network:
          allOf:
            - $ref: '#/components/schemas/NetworkFamily'
          description: The network family of the sender's address.
      description: >-
        The address the partner registers to attribute a held deposit to its
        sender.
    NetworkFamily:
      type: string
      enum:
        - evm
        - solana
        - tron
      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.
        A create for a family the provider that provisions this project's
        walletExternal accounts does not serve is refused before anything is
        written, with 422 `NetworkFamilyNotServed`; depending on the provider,
        the refusal can be 403 `VendorConfigMissing` instead.
    BankAccountType:
      type: string
      enum:
        - checking
        - savings
      description: Bank account sub-type for US accounts.
    Address:
      type: object
      properties:
        line1:
          type: string
          description: Street address, line 1.
        line2:
          type: string
          description: Street address, line 2.
        city:
          type: string
          description: City.
        state:
          type: string
          description: State / province / region.
        country:
          type: string
          description: ISO 3166-1 alpha-2
        zipCode:
          type: string
          description: ZIP / postal code.
      description: A postal address. country is an ISO 3166-1 alpha-2 country code.
    CardBrand:
      type: string
      enum:
        - visa
        - mastercard
        - amex
        - discover
      description: >-
        Card network/brand. Derived server-side from the PAN; never accepted on
        a request.
    CardType:
      type: string
      enum:
        - debit
        - credit
        - prepaid
      description: >-
        Card funding type, derived server-side from the PAN. Only `debit` is
        supported today; `credit` and `prepaid` are reserved for future
        push-to-card / pull-from-card support.
    BillingAddressSource:
      type: string
      enum:
        - provided
        - customerDefault
      description: >-
        Where a card's billing address came from. `provided` = supplied on the
        request; `customerDefault` = filled from the owning customer's address
        because the request omitted it.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Token from POST /auth/token

````