openapi: 3.1.0
info:
  title: Numerari Partner API
  version: '1'
  summary: Top Up, Cash Out and Swap for your customers, from your server.
  description: |
    The Partner API lets a partner offer **Top Up** (US dollars from a bank account into the customer's own wallet),
    **Cash Out** (stablecoins from the customer's own wallet to their own US bank account) and **Swap** (one token
    for another inside the customer's own wallet) inside the partner's app. Numerari never holds the customer's
    funds and never takes custody of the wallet.

    ## How it works

    - **Your server calls this API.** Every route here takes a partner API key. Keys are issued to you during
      onboarding. They never go in a browser or a mobile app, and these routes send no CORS headers, so a browser
      cannot call them.
    - **Top Up** is a hosted flow. Your server opens a session and hands the short-lived `client_token` to the Numerari
      Top Up module in your page. The module collects the customer's details, shows the bank instructions and
      follows the order. You follow the order by webhook or by reading it.
    - **Cash Out** is driven by your own screens. Your server opens a session, adds a bank account, prices a
      quote and places an order. The customer then signs one transfer in their own wallet to the order's deposit
      address.
    - **Swap** is a hosted flow. Your server opens a session and hands the short-lived `client_token` to the
      Numerari swap module in your page. The module prices and places the swap in the browser, and the customer's
      wallet signs it. Supported routes are per partner. Your server can list a customer's swaps with
      `GET /v1/swap/orders`. Swap errors are flat (`type`, `code`, `message`, `ref`) and Swap sends no webhooks.
      See the Swap page in the guide.

    ## Conventions

    - **Authentication:** `Authorization: Bearer <partner API key>`. A missing, unknown or revoked key is
      `401 unauthorized` with no detail about which it was. On Swap, a service-wide switched-off Swap is
      `503 swap_unavailable` before the key is checked, and a disabled partner account is also `503 swap_unavailable`.
    - **Format:** JSON in and out. Unknown request fields are refused with `400 validation_error`, and the
      response never repeats what you sent.
    - **Money:** decimal strings, never JSON numbers. Cash Out amounts and fees have exactly two decimals
      (`"250.00"`); requests accept zero to two. Top Up `delivered_amount_usdc` has six decimals, the exact
      amount that reached the wallet.
    - **Ids** are opaque and prefixed (`ses_`, `ord_`, `evt_`, `ofs_`, `bnk_`, `ofq_`, `ofo_`, and `sws_` and `swo_` on
      Swap). Treat them as strings.
    - **Times** are RFC 3339 UTC with a `Z`.
    - **Headers:** every Top Up and Cash Out response has `Request-Id` (quote it to support) and
      `Cache-Control: no-store`. Swap responses have `Cache-Control: no-store` and no `Request-Id`: quote the `ref`
      of a Swap error to support instead.
    - **Rate limits:** `429 rate_limited` with a `Retry-After` header in seconds.
    - **Error references:** every Top Up and Cash Out error has a permanent reference such as `N23`, in
      `error.ref` and at the end of `error.message` as `(N23)`. Give it to support and they will know the
      exact failure. References are never renumbered.
    - **Test and live:** a Cash Out quote or order has `provider_mode` of `mock` or `live`. Never show or send
      funds to a `mock` order outside your own development or staging environment.

    ## Webhooks

    Numerari POSTs every public status change of a Top Up or Cash Out order to your configured `webhook_url` (https only).

    - **Headers:** `Numerari-Event-Id` and `Numerari-Signature: t=<unix seconds>,v1=<hex>`.
    - **Signature:** `v1` is the hex HMAC-SHA256 of `"<t>.<raw body>"` with your webhook key.
    - **You must:** verify against the raw bytes before you parse the JSON, compare in constant time,
      reject when `|now - t|` is more than 300 seconds, dedupe on `id`, and apply an order only when
      `data.order.version` is higher than the one you hold.
    - **Delivery:** each attempt has a 10 second timeout. Any 2xx marks the event delivered. Anything else is retried
      with growing delays (1 minute, 5, 15, 1 hour, 3, 6, then every 6 hours) for 72 hours, then abandoned.
      Order is not guaranteed, which is what `version` is for.
    - **Never in a webhook:** bank details, identity details, or the ids of any provider.
  contact:
    name: Numerari Support
    email: support@numerari.io
servers:
  - url: https://api.numerari.io
    description: Production
security:
  - PartnerKey: []
tags:
  - name: Top Up
    description: Dollars from a US bank account to the customer's own wallet. Hosted flow.
  - name: Cash Out
    description: Stablecoins from the customer's own wallet to their own US bank account.
  - name: Swap
    description: One token for another, inside the customer's own wallet. Hosted flow. Three server routes.
paths:
  /v1/onramp/sessions:
    post:
      tags: [Top Up]
      operationId: createTopUpSession
      summary: Open a Top Up session
      description: |
        Creates a short-lived `client_token` for one Top Up module session. Call it from your server for your own
        signed-in customer, then pass **only** `client_token` to the browser, in the module's `nr:init` message.

        - **First call** for an `external_user_id` creates the customer record. A repeat call refreshes the name and
          email until the customer has been verified, then keeps the verified values.
        - **Wallet:** a different `wallet_address` for an existing customer is `409 wallet_mismatch`. The wallet is
          where the funds land, so changing it is a support request.
        - **Token:** `nct_` plus 43 characters. Numerari stores only a hash, the plaintext appears once in this
          response, and it expires about 60 minutes after creation by default. Read `expires_at` from the response
          rather than assuming a lifetime. The module reuses the token for the length of that one module session, so
          do not discard it after the first call. Mint a new session each time you open the module, including after a
          verification step returns.
        - **Asset and network:** leave `asset` and `network` out for USDC on Base. Naming either locks the
          session to that route. Other routes are enabled for you individually.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TopUpSessionRequest'
            example:
              external_user_id: usr_48213
              first_name: Jordan
              last_name: Rivera
              email: jordan.rivera@example.com
              wallet_address: '0x7A3f2B9C4E81d0a65f3C7B2e9d14a8f0c6e5C91E'
      responses:
        '201':
          description: Session created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopUpSession'
              example:
                session_id: ses_01jz8pzk3m5n7q9s1t3v5x7z9b
                client_token: nct_EXAMPLE_TOKEN_DO_NOT_USE
                expires_at: '2026-10-01T16:00:00Z'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/WalletMismatch'
        '422':
          description: |
            The route cannot be used. `route_not_supported`: not a route Numerari offers, or switched off.
            `route_not_enabled_for_partner`: offered, but not enabled for you. `network_fee_bps_not_allowed`:
            the rate is not one your agreement allows.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/Unavailable'
  /v1/onramp/orders/{order_id}:
    get:
      tags: [Top Up]
      operationId: getTopUpOrder
      summary: Read a Top Up order
      description: |
        Returns one order that belongs to you. Use it to reconcile or to catch up after a missed webhook.
        Another partner's order, and an id that does not exist, are the same `404 order_not_found`.

        `version` goes up by one on every public status change. Ignore anything older than what you hold.
        `wallet_address` is the customer's own wallet. `tx_hash` is the transaction that put the funds there.
      parameters:
        - $ref: '#/components/parameters/TopUpOrderId'
      responses:
        '200':
          description: The order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopUpOrder'
              example:
                order_id: ord_01jz8q7b2d4f6h8k0m2p4r6t8v
                external_user_id: usr_48213
                session_id: ses_01jz8pzk3m5n7q9s1t3v5x7z9b
                status: delivered
                rail: ach
                amount_usdc: '250.00'
                rail_fee_usd: '2.00'
                fees_usd: '4.38'
                total_usd: '256.38'
                delivered_amount_usdc: '250.003700'
                wallet_address: '0x7A3f2B9C4E81d0a65f3C7B2e9d14a8f0c6e5C91E'
                network: base
                asset: USDC
                tx_hash: '0x9f2c0000000000000000000000000000000000000000000000000000000f9f1a'
                explorer_url: 'https://basescan.org/tx/0x9f2c0000000000000000000000000000000000000000000000000000000f9f1a'
                created_at: '2026-10-01T15:02:00Z'
                expires_at: '2026-10-08T15:02:00Z'
                funds_received_at: '2026-10-01T15:11:40Z'
                delivered_at: '2026-10-01T15:20:02Z'
                updated_at: '2026-10-01T15:20:02Z'
                version: 3
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/OrderNotFound'
        '503':
          $ref: '#/components/responses/Unavailable'
  /v1/offramp/sessions:
    post:
      tags: [Cash Out]
      operationId: createCashOutSession
      summary: Open a Cash Out session
      description: |
        Starts or resumes a Cash Out session for one customer, and tells you whether the customer may cash out yet.

        - **Idempotent per `external_user_id`.** While the customer has an unexpired session (60 minutes) it is
          returned again with `200` instead of `201`, with the eligibility read fresh. The same
          `external_user_id` under another partner is another customer.
        - **Wallet:** `wallet_address` is the customer's own wallet and the deposit is expected from it. A
          different wallet for an existing customer is `409 wallet_mismatch`.
        - **Name:** a full name, two or more words.
        - **Eligibility:** `verified` (continue), `needed` (the customer must be verified first),
          `pending` (under review, ask again in a minute), or `rejected` (cannot cash out; the quote, bank
          account and order routes answer `409 identity_required`).
        - **When `needed`:** if the response has `kyc_required: true`, collect the details and send them to
          `POST /v1/offramp/sessions/{session_id}/kyc`. If it has an `identity_frame_url`, open that https page for
          the customer. If `identity_frame_frameable` is `false` the page refuses to be framed, so open it in a
          new tab; if it is absent, try a frame with `allow="camera"`.
        - **Re-checks:** a `verified` customer is re-read on each call. Verification can be withdrawn later.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CashOutSessionRequest'
            example:
              external_user_id: usr_48213
              email: jordan.rivera@example.com
              name: Jordan Rivera
              wallet_address: '0x7A3f2B9C4E81d0a65f3C7B2e9d14a8f0c6e5C91E'
      responses:
        '200':
          description: An existing session, returned again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashOutSession'
        '201':
          description: Session created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashOutSession'
              example:
                session_id: ofs_01jz9a2b4c6d8e0f2g4h6j8k0m
                eligibility: verified
                expires_at: '2026-10-01T16:00:00Z'
                rails:
                  - id: ach
                    fee_usd: '2.00'
                    min_usd: '10.00'
                    max_usd: '100000.00'
                    advertised_min_usd: '10.00'
                    advertised_max_usd: '100000.00'
                routes:
                  - route: usdc_base
                    asset: usdc
                    network: base
                    display_name: USDC on Base
                    min_usd: '10.00'
                    max_usd: '100000.00'
                    advertised_min_usd: '10.00'
                    advertised_max_usd: '100000.00'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/WalletMismatch'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/CashOutUnavailable'
  /v1/offramp/kyc/requirements:
    get:
      tags: [Cash Out]
      operationId: getCashOutKycRequirements
      summary: Read what to show a new customer
      description: |
        For partners on in-app onboarding. Returns the terms and privacy links with their versions, and the lists of
        answers to offer. Render the lists from `options`; never hard-code them. Show the links next to an
        unticked checkbox. The result is cached for ten minutes.
      responses:
        '200':
          description: Terms and answer lists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KycRequirements'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '503':
          $ref: '#/components/responses/CashOutUnavailable'
  /v1/offramp/sessions/{session_id}/kyc:
    post:
      tags: [Cash Out]
      operationId: submitCashOutKyc
      summary: Verify a new customer
      description: |
        Sends a new customer's details and answers in one request, after they accepted the terms.

        - **Not stored.** The date of birth, SSN and address go on to the verifier in this one call and are dropped.
          They are never stored, logged or echoed by Numerari, and your app must not log or keep them either.
        - **Result:** `eligibility` of `verified`, `pending`, `rejected` or `needed`. `pending` means the account is
          in review, usually for a minute. Call `POST /v1/offramp/sessions` again to read it.
        - **Errors:** `400 validation_error` names the failing `fields`, never their values. `429` is limited per
          person. `502 provider_error` is temporary, so retry.
      parameters:
        - $ref: '#/components/parameters/CashOutSessionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KycSubmission'
            example:
              terms_accepted: true
              terms_version: '2026-10'
              privacy_version: '2026-10'
              employment_status: employed
              most_recent_occupation: '132011'
              source_of_funds: salary
              account_purpose: personal_or_living_expenses
              account_purpose_other: ''
              acting_as_intermediary: false
              expected_monthly_payments_usd: '0_4999'
              birth_date: '1990-05-20'
              address:
                line1: 100 Main St
                line2: ''
                city: Austin
                state: TX
                postal_code: '78701'
                country: US
              ssn: '000-00-0000'
      responses:
        '200':
          description: The eligibility after the check.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Eligibility'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/SessionNotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/ProviderError'
        '503':
          $ref: '#/components/responses/CashOutUnavailable'
  /v1/offramp/sessions/{session_id}/photo-id:
    post:
      tags: [Cash Out]
      operationId: submitCashOutPhotoId
      summary: Send a photo ID and selfie
      description: |
        A customer may be asked for a photo ID and a live selfie. The session `eligibility` tells you when. Send them
        here. The files go straight on to the verifier.

        - **Images** are JPEG or PNG data URIs. `image_back` is optional (a passport has one side).
        - **Not stored.** The images and the document number are never stored, logged, echoed or put in an error.
        - **Result:** `eligibility` is `verified`, `pending` or `rejected`. The review is the verifier's, and
          anything short of a clear approval is `pending`.
        - **Errors:** `400 validation_error` names fields only. `422 photo_id_rejected` has a message that ends with
          the reason name, for example `(document_number_invalid)`. `409 photo_id_not_available` when the customer
          has no verification record yet.
      parameters:
        - $ref: '#/components/parameters/CashOutSessionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhotoIdSubmission'
      responses:
        '200':
          description: The eligibility after the review.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Eligibility'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/SessionNotFound'
        '409':
          description: '`photo_id_not_available`: the customer has no verification record yet.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: '`photo_id_rejected`: the verifier refused the document. The message ends with the reason name.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/ProviderError'
        '503':
          $ref: '#/components/responses/CashOutUnavailable'
  /v1/offramp/sessions/{session_id}/bank-accounts:
    post:
      tags: [Cash Out]
      operationId: addCashOutBankAccount
      summary: Add the customer's bank account
      description: |
        Adds the account the customer will be paid into. Requires `eligibility: verified`. The account must be the
        customer's own. At most 10 accounts per customer; rejected accounts, and forms left pending for 24 hours, do
        not count.

        **Send the details here** with a JSON body. The wallet collects them and they pass through this API straight
        to the payout provider. The routing and account numbers exist in memory for this one call. They are never
        stored, logged, echoed or put in an error. Only the provider's id, the status and the last four digits are kept.

        - **Required:** `account_owner_name`, `routing_number`, `account_number`, `address`, and
          `owner_attested: true`.
        - **Optional:** `first_name`, `last_name`, `bank_name`, `account_type` (`checking` or `savings`),
          `owner_type` (`individual` by default, or `business`).
        - **Address:** `line1` up to 35 characters, `state` two letters, `postal_code` five digits or ZIP+4,
          `country` `US`.

        **With no body** the call returns a hosted bank form instead (`bank_frame_url`), for providers that
        offer one. A body sent to a provider that only has a form is `409 bank_details_unsupported`.
      parameters:
        - $ref: '#/components/parameters/CashOutSessionId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankAccountDetails'
            example:
              account_owner_name: Jane Sample
              first_name: Jane
              last_name: Sample
              owner_attested: true
              bank_name: Example Bank
              routing_number: '000000000'
              account_number: '000000000000'
              account_type: checking
              address:
                line1: 100 Main St
                city: Austin
                state: TX
                postal_code: '78701'
                country: US
      responses:
        '201':
          description: |
            With details: the account `{ref, status, last4, holder_name_matches}`. With no body: the form
            `{bank_frame_url, ref}`. Pass `ref` to `POST /v1/offramp/orders` as `bank_account_ref`.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/BankAccount'
                  - $ref: '#/components/schemas/BankFrame'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/SessionNotFound'
        '409':
          description: |
            `identity_required` (not verified), `bank_account_limit_reached`, or `bank_details_unsupported`
            (this provider only has a hosted form; send the request without a body).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: |
            `bank_details_rejected`: the provider refused the account. The message ends with the reason name,
            for example `(bank_name_required)`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: '`bank_frame_unavailable` (no hosted form available) or `offramp_unavailable`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/offramp/sessions/{session_id}/bank-accounts/{ref}:
    get:
      tags: [Cash Out]
      operationId: getCashOutBankAccount
      summary: Read a bank account
      description: |
        Returns the account's status. Only the session customer's own accounts are visible; any other is
        `404 bank_account_not_found`. A pending account is re-read from the provider at most once every 30 seconds
        however often you poll, and a verified one is never re-read.
      parameters:
        - $ref: '#/components/parameters/CashOutSessionId'
        - name: ref
          in: path
          required: true
          description: The `bnk_` reference from the create call.
          schema:
            type: string
      responses:
        '200':
          description: The account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccount'
              example:
                ref: bnk_01jz9a3c5e7g9j1m3p5r7t9w1y
                status: verified
                last4: '6789'
                holder_name_matches: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: '`session_not_found` or `bank_account_not_found`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/CashOutUnavailable'
  /v1/offramp/quotes:
    post:
      tags: [Cash Out]
      operationId: createCashOutQuote
      summary: Price a Cash Out
      description: |
        Prices one cash out. The quote lives **5 minutes**; an order at or after `expires_at` is
        `422 quote_expired`.

        - **Asset and network:** `asset` is `usdc` or `usdt` and `network` is `base`, `ethereum` or `polygon`, in lower case. A
          missing `asset` means `usdc` and a missing `network` means `base`, so `usdt` needs
          its `network` (`ethereum` or `polygon`) spelled out. A pair that is not enabled for you is `422 asset_network_unavailable`
          and is never swapped for another. A pair whose sell side is switched off is `422 route_not_supported`.
        - **Amount:** `amount_usdc` is the amount **of the stablecoin you chose**, for both assets.
        - **Rail:** `ach` or `wire`. `fednow` is a Top Up rail and is `400 rail_invalid`.
        - **`network_fee_bps`** is required. You state the rate and it must be one your agreement allows,
          otherwise `422 network_fee_bps_not_allowed`.
        - **Fees:** `processing_fee` is set by the rail. `network_and_gas_fee` is `network_fee_bps` of the amount,
          rounded up to the cent. `total` is both, and `receive_usd` is `amount_usdc` less `total`.
          `customer_price` is the whole price ready to show, so you add nothing up yourself.
        - **`fee_transfer`:** present only when your account pays the network fee as its own transfer. See
          `POST /v1/offramp/orders/{order_id}/fee-transfer`.
        - **Limits:** outside the allowed range is `422 amount_out_of_range`, with the range in the message.
        - **Rate limit:** 20 quotes a minute per customer.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CashOutQuoteRequest'
            example:
              session_id: ofs_01jz9a2b4c6d8e0f2g4h6j8k0m
              asset: usdc
              network: base
              amount_usdc: '250.00'
              rail: ach
              network_fee_bps: 175
      responses:
        '201':
          description: The quote.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashOutQuote'
        '400':
          description: '`validation_error` or `rail_invalid`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/SessionNotFound'
        '409':
          $ref: '#/components/responses/IdentityRequired'
        '422':
          description: |
            `amount_out_of_range`, `asset_network_unavailable`, `route_not_supported` or
            `network_fee_bps_not_allowed`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/CashOutUnavailable'
  /v1/offramp/orders:
    post:
      tags: [Cash Out]
      operationId: createCashOutOrder
      summary: Place a Cash Out order
      description: |
        Turns a quote into an order and returns the **deposit address** the customer sends to.

        - **`Idempotency-Key`** is required: 1 to 200 printable ASCII characters. Generate one per quote and
          reuse it on every retry.
        - **Checks, in order:** the quote is yours and has not expired; the key is not bound to another quote; the
          customer is still verified; the asset, network and rate are still allowed; the bank account is the
          customer's own and `verified`.
        - **Send exactly `amount_usdc`** of `asset` on `network` to `deposit_address`, from the session wallet. A
          different amount may not be paid out.
        - **`deposit_address`** can be `null` while one is still being issued (read the order again), and is `null`
          again once the order is `paid`, `failed` or `expired`. Never send to an address you stored earlier.
        - **Replays:** the same key, quote and bank account returns the same order with `200`, and the provider is
          called once. The same key and quote with a different bank account is `409 idempotency_key_reused`. The
          same quote under another key is `409 quote_already_used`.
        - **After an error:** `502 provider_error` after a timeout means the attempt may exist. Retry with the
          **same** key. After a definite refusal the quote is released and can be used again under any key.
        - **`409 order_in_progress`** means another attempt holds the quote. Retry, and if you then get
          `quote_already_used`, take a new quote.
        - **Fee transfer:** when the quote has a `fee_transfer`, send the fee, the cash-out amount and anything else
          together. `fee_tx_hash` may be included here, or reported afterwards.
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 200
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CashOutOrderRequest'
            example:
              quote_id: ofq_01jz9a5n7q9s1t3v5x7z9b1d3f
              bank_account_ref: bnk_01jz9a3c5e7g9j1m3p5r7t9w1y
      responses:
        '200':
          description: A replay of an order already placed under this key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashOutOrder'
        '201':
          description: Order placed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashOutOrder'
        '400':
          description: '`validation_error` or `idempotency_key_required`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: '`quote_not_found` or `bank_account_not_found`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: |
            `identity_required`, `bank_account_not_ready`, `quote_already_used`, `idempotency_key_reused` or
            `order_in_progress`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: |
            `quote_expired`, `amount_out_of_range`, `asset_network_unavailable`, `route_not_supported`,
            `network_fee_bps_not_allowed`, `fee_tx_invalid`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: |
            `provider_error`, or `payout_mismatch` (the payout would fall outside the quoted amount; nothing was
            created and the quote is released).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/CashOutUnavailable'
  /v1/offramp/orders/{order_id}:
    get:
      tags: [Cash Out]
      operationId: getCashOutOrder
      summary: Read a Cash Out order
      description: |
        Returns one of your orders. Another partner's order, an unknown id, and a quote that never became an
        order are all the same `404 order_not_found`. A non-final order older than 30 seconds is re-read from the
        provider, so polling cannot turn into provider calls.
      parameters:
        - $ref: '#/components/parameters/CashOutOrderId'
      responses:
        '200':
          description: The order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashOutOrder'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/OrderNotFound'
        '503':
          $ref: '#/components/responses/CashOutUnavailable'
  /v1/offramp/orders/{order_id}/fee-transfer:
    post:
      tags: [Cash Out]
      operationId: reportCashOutFeeTransfer
      summary: Report the fee transfer
      description: |
        For a quote that has a `fee_transfer`: report the transaction hash of the fee transfer. It answers `200` with
        the order and never waits for the chain; the transfer is checked in the background.

        - **Before it is verified,** a hash can be replaced by another one with this call. Once the chain has verified
          a fee, a different hash is `422 fee_tx_invalid`.
        - **Errors:** `422 fee_tx_invalid`, `409 fee_tx_reused` (that hash was used for another order),
          `400 validation_error` (not a well formed hash).
        - **If it never arrives,** or turns out to be the wrong transfer, the order stands and the fee is billed to
          the customer.
      parameters:
        - $ref: '#/components/parameters/CashOutOrderId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [fee_tx_hash]
              properties:
                fee_tx_hash:
                  type: string
                  description: The fee transfer's transaction hash (0x and 64 hex characters).
            example:
              fee_tx_hash: '0x0000000000000000000000000000000000000000000000000000000000000001'
      responses:
        '200':
          description: The order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashOutOrder'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/OrderNotFound'
        '409':
          description: '`fee_tx_reused`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: '`fee_tx_invalid`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/CashOutUnavailable'
  /v1/swap/sessions:
    post:
      tags: [Swap]
      operationId: createSwapSession
      summary: Open a Swap session
      description: |
        Opens a session for one customer's wallet and one route, and returns the short-lived `client_token` for the
        Numerari swap module. Call it from your server, then pass **only** `client_token` to the browser.

        - **Route:** named by `from` and `to`. Supported routes are per partner: Numerari enables them for you. A
          pair that is not offered, or not enabled for you, is `422 swap_no_route`. The body is read first (invalid
          JSON or an unknown field is `400 validation_error`), then the route is checked, then `user_id` and
          `wallet_address`. Opening sessions is rate limited per partner, and that limit is checked after the key and
          before the body is read, so a `429` can come before a `400`.
        - **Switched off:** while Swap is switched off for the whole service, every Swap server route answers
          `503 swap_unavailable` before the key is checked. While it is switched off for your account only, this route
          answers `503 swap_unavailable` (after the key, the rate limit and the body), and the two read routes keep
          answering. A disabled partner account is `503 swap_unavailable` on every Swap server route, not `401`.
        - **Token:** `nsw_` prefix. Numerari stores only a hash and the plaintext appears once, in this response.
          Never log it or put it in a URL. Read `expires_at` rather than assuming a lifetime.
        - **Funds:** opening a session moves nothing. The customer's own wallet signs and sends the swap.
        - **Errors** on the Swap routes are flat (`type`, `code`, `message`, `ref`), not wrapped in an `error`
          object. The browser routes the module calls with the client token are not part of this reference.
        - **Webhooks:** Swap sends no events to your webhook URL.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SwapSessionRequest'
            example:
              user_id: usr_48213
              wallet_address: '0x7A3f2B9C4E81d0a65f3C7B2e9d14a8f0c6e5C91E'
              from:
                network: base
                symbol: USDC
              to:
                network: base
                symbol: ETH
      responses:
        '201':
          description: Session created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SwapSession'
              example:
                session_id: sws_EXAMPLE_SESSION_ID
                route: usdc_base_to_eth_base
                client_token: nsw_EXAMPLE_TOKEN_DO_NOT_USE
                expires_at: '2026-10-01T16:20:00Z'
        '400':
          $ref: '#/components/responses/SwapValidationError'
        '401':
          $ref: '#/components/responses/SwapUnauthorized'
        '422':
          $ref: '#/components/responses/SwapNoRoute'
        '429':
          $ref: '#/components/responses/SwapRateLimited'
        '500':
          $ref: '#/components/responses/SwapInternalError'
        '502':
          $ref: '#/components/responses/SwapTemporary'
        '503':
          $ref: '#/components/responses/SwapUnavailable'
  /v1/swap/sessions/{session_id}:
    get:
      tags: [Swap]
      operationId: getSwapSession
      summary: Read a Swap session
      description: |
        Reads one of your own sessions. It never returns the client token, and it carries no swap or order status.
        Another partner's session and an unknown id are the same `404 not_found`. It keeps answering while Swap is
        switched off for your account only. Read the swaps themselves with `GET /v1/swap/orders`.
      parameters:
        - $ref: '#/components/parameters/SwapSessionId'
      responses:
        '200':
          description: The session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SwapSessionView'
              example:
                session_id: sws_EXAMPLE_SESSION_ID
                route: usdc_base_to_eth_base
                user_id: usr_48213
                wallet_address: '0x7A3f2B9C4E81d0a65f3C7B2e9d14a8f0c6e5C91E'
                expires_at: '2026-10-01T16:20:00Z'
        '401':
          $ref: '#/components/responses/SwapUnauthorized'
        '404':
          $ref: '#/components/responses/SwapNotFound'
        '500':
          $ref: '#/components/responses/SwapInternalError'
        '502':
          $ref: '#/components/responses/SwapTemporary'
        '503':
          $ref: '#/components/responses/SwapUnavailable'
  /v1/swap/orders:
    get:
      tags: [Swap]
      operationId: listSwapOrders
      summary: List a customer's Swaps
      description: |
        Returns the swaps one of your customers has placed, newest first. `user_id` and `wallet_address` are both
        required, and the answer is only ever for that user and that wallet, within the sessions your own key opened.
        Another partner's, another user's and another wallet's swaps are never returned, and are not an error.

        - **Freshness:** read from what Numerari has stored. Nobody else is asked, so it is as fresh as the last status
          change Numerari received.
        - **Size:** up to 50 swaps without `limit`, and never more than 100.
        - **Checks:** a bad `limit`, `user_id` or `wallet_address` is `400 validation_error`, checked before the rate
          limit. Reading is rate limited per partner: `429 rate_limited` carries `Retry-After`.
        - **Switched off:** while Swap is switched off for the whole service, or your partner account is disabled, it
          answers `503 swap_unavailable`. While Swap is switched off for your account only, it keeps answering.
        - No signing request, token or outside reference ever appears in an item.
      parameters:
        - name: user_id
          in: query
          required: true
          description: The `user_id` you sent when you opened the session. Matched exactly.
          schema:
            type: string
            pattern: '^[A-Za-z0-9._:@+-]{1,128}$'
        - name: wallet_address
          in: query
          required: true
          description: The customer's wallet. Matched without regard to letter case.
          schema:
            type: string
            pattern: '^0x[0-9a-fA-F]{40}$'
        - name: limit
          in: query
          required: false
          description: A whole number of 1 or more. A larger number is cut to 100, but a number too large to read as a whole number is `400 validation_error`. Without it, up to 50 swaps.
          schema:
            type: integer
            minimum: 1
      responses:
        '200':
          description: The swaps, newest first. An empty `items` array when there are none.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SwapOrderList'
              example:
                items:
                  - order_id: swo_EXAMPLE_ORDER_ID
                    status: completed
                    route: usdc_base_to_eth_base
                    user_id: usr_48213
                    wallet_address: '0x7A3f2B9C4E81d0a65f3C7B2e9d14a8f0c6e5C91E'
                    pay:
                      amount: '25'
                      symbol: USDC
                      network: base
                    get:
                      amount: '0.0071'
                      symbol: ETH
                      network: base
                    created_at: '2026-10-01T16:00:00Z'
                    updated_at: '2026-10-01T16:05:00Z'
        '400':
          $ref: '#/components/responses/SwapListValidationError'
        '401':
          $ref: '#/components/responses/SwapUnauthorized'
        '429':
          $ref: '#/components/responses/SwapRateLimited'
        '500':
          $ref: '#/components/responses/SwapInternalError'
        '502':
          $ref: '#/components/responses/SwapTemporary'
        '503':
          $ref: '#/components/responses/SwapUnavailable'
webhooks:
  topUpOrder:
    post:
      tags: [Top Up]
      summary: A Top Up order changed status
      parameters:
        - $ref: '#/components/parameters/WebhookSignature'
        - $ref: '#/components/parameters/WebhookEventId'
      description: |
        Sent on every public status change. `type` is `onramp_order.awaiting_funds`, `onramp_order.funds_received`,
        `onramp_order.delivered`, `onramp_order.cancelled`, `onramp_order.expired` or `onramp_order.failed`.
        `data.order` has the same shape as `GET /v1/onramp/orders/{order_id}`. Ignore fields you do not know.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TopUpWebhook'
      responses:
        '200':
          description: Return any 2xx to mark the event delivered.
  cashOutOrder:
    post:
      tags: [Cash Out]
      summary: A Cash Out order changed status
      parameters:
        - $ref: '#/components/parameters/WebhookSignature'
        - $ref: '#/components/parameters/WebhookEventId'
      description: |
        Sent on every public status change. `type` is `offramp_order.created`, `offramp_order.deposit_detected`,
        `offramp_order.converting`, `offramp_order.paid`, `offramp_order.failed` or `offramp_order.expired`.
        `data.order` has the same shape as `GET /v1/offramp/orders/{order_id}`. A finished order has
        `deposit_address: null`.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CashOutWebhook'
      responses:
        '200':
          description: Return any 2xx to mark the event delivered.
components:
  securitySchemes:
    PartnerKey:
      type: http
      scheme: bearer
      description: |
        Your partner API key, from onboarding. Keep it on your server in a secret store. Keys look like
        `npk_live_...` or `npk_test_...`. Numerari stores only a hash, and a key can be rotated with an overlap.
  parameters:
    SwapSessionId:
      name: session_id
      in: path
      required: true
      description: The `sws_` id from `POST /v1/swap/sessions`.
      schema:
        type: string
    WebhookSignature:
      name: Numerari-Signature
      in: header
      required: true
      description: '`t=<unix seconds>,v1=<hex>`. `v1` is the hex HMAC-SHA256 of `"<t>.<raw body>"` under your webhook key.'
      schema:
        type: string
    WebhookEventId:
      name: Numerari-Event-Id
      in: header
      required: true
      description: The event id, the same as `id` in the body. Dedupe on it.
      schema:
        type: string
    TopUpOrderId:
      name: order_id
      in: path
      required: true
      description: The `ord_` id.
      schema:
        type: string
    CashOutSessionId:
      name: session_id
      in: path
      required: true
      description: The `ofs_` id from `POST /v1/offramp/sessions`.
      schema:
        type: string
    CashOutOrderId:
      name: order_id
      in: path
      required: true
      description: The `ofo_` id.
      schema:
        type: string
  responses:
    SwapValidationError:
      description: '`validation_error` (N201): the body is invalid JSON or has an unknown field, or, once the route is accepted, `user_id` or `wallet_address` is missing or invalid. A missing or empty `from` or `to` is `swap_no_route` instead.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SwapError'
          example:
            type: error
            code: validation_error
            message: wallet_address must be the customer's own EVM wallet address. (N201)
            ref: N201
    SwapListValidationError:
      description: '`validation_error` (N201): `user_id`, `wallet_address` or `limit` is missing or invalid.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SwapError'
          example:
            type: error
            code: validation_error
            message: user_id is not valid. (N201)
            ref: N201
    SwapUnauthorized:
      description: '`unauthorized` (N202): the partner key is missing, unknown or revoked. No detail is given about which.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SwapError'
    SwapNoRoute:
      description: |
        `swap_no_route` (N206): the pair is not offered, or is not enabled for you. Supported routes are per partner.
        Do not retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SwapError'
          example:
            type: error
            code: swap_no_route
            message: This swap is not available for this partner. (N206)
            ref: N206
    SwapNotFound:
      description: '`not_found` (N204): unknown id, or another partner''s session.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SwapError'
    SwapRateLimited:
      description: '`rate_limited` (N210). Wait `Retry-After` seconds.'
      headers:
        Retry-After:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SwapError'
    SwapInternalError:
      description: '`internal_error` (N230): something went wrong on our side. Retry.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SwapError'
    SwapTemporary:
      description: '`swap_unavailable` (N230): a temporary failure on our side. Retry shortly.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SwapError'
    SwapUnavailable:
      description: '`swap_unavailable` (N205): Swap is switched off, or your partner account is disabled. See the route description for which routes a partner-level switch affects.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SwapError'
    ValidationError:
      description: |
        `validation_error`: a field is missing or invalid. `fields` names the fields, never their values.
        `invalid_destination` (Top Up): the wallet is not a usable destination.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: validation_error
              message: Some details look incomplete. Check them and try again. (N2)
              fields: [wallet_address]
              ref: N2
    Unauthorized:
      description: The key is missing, unknown or revoked. No detail is given about which.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    WalletMismatch:
      description: '`wallet_mismatch`: a different wallet is already on file for this customer.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    SessionNotFound:
      description: '`session_not_found`: unknown, expired, or belongs to another partner.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    OrderNotFound:
      description: '`order_not_found`. Also returned for another partner''s order.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    IdentityRequired:
      description: '`identity_required`: the customer is not verified, or verification was withdrawn.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: '`rate_limited`. Wait `Retry-After` seconds.'
      headers:
        Retry-After:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ProviderError:
      description: '`provider_error`: a temporary failure on our side or the provider''s. Retry.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unavailable:
      description: '`onramp_unavailable`: Top Up is switched off for you.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    CashOutUnavailable:
      description: |
        `offramp_unavailable`: Cash Out is switched off for you.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    SwapError:
      type: object
      required: [type, code, message, ref]
      properties:
        type:
          type: string
          enum: [error]
        code:
          type: string
          enum:
            - validation_error
            - unauthorized
            - session_expired
            - not_found
            - swap_unavailable
            - swap_no_route
            - swap_refused
            - swap_quote_expired
            - swap_price_moved
            - rate_limited
            - internal_error
          description: Stable and machine readable. Branch on this, never on the message.
        message:
          type: string
          description: Ends with the reference, for example `(N206)`.
        ref:
          type: string
          description: Permanent Numerari error reference in the N200 to N299 range, for example `N206`.
    SwapSide:
      type: object
      additionalProperties: false
      required: [network, symbol]
      properties:
        network:
          type: string
          description: The network, for example `base`. Matched without regard to case.
        symbol:
          type: string
          description: The token symbol, for example `USDC`. Matched without regard to case.
    SwapSessionRequest:
      type: object
      additionalProperties: false
      required: [user_id, wallet_address, from, to]
      properties:
        user_id:
          type: string
          pattern: '^[A-Za-z0-9._:@+-]{1,128}$'
          description: Your stable id for the customer. 1 to 128 characters from `A-Za-z0-9._:@+-`.
        wallet_address:
          type: string
          pattern: '^0x[0-9a-fA-F]{40}$'
          not:
            anyOf:
              - pattern: '^0x0{40}$'
              - pattern: '^0x0{36}[dD][eE][aA][dD]$'
          description: The customer's own wallet. The zero address and the burn address are refused.
        from:
          $ref: '#/components/schemas/SwapSide'
        to:
          $ref: '#/components/schemas/SwapSide'
    SwapSession:
      type: object
      required: [session_id, route, client_token, expires_at]
      properties:
        session_id:
          type: string
          description: The `sws_` id.
        route:
          type: string
          description: The name of the route the session is locked to, for example `usdc_base_to_eth_base`.
        client_token:
          type: string
          description: Goes to the browser only. Never log it or put it in a URL. Shown once.
        expires_at:
          type: string
          format: date-time
    SwapAmount:
      type: object
      required: [amount, symbol, network]
      properties:
        amount:
          type: string
          description: A decimal string, never a JSON number.
        symbol:
          type: string
        network:
          type: string
    SwapOrderItem:
      type: object
      required: [order_id, status, route, user_id, wallet_address, pay, created_at, updated_at]
      properties:
        order_id:
          type: string
          description: The `swo_` id.
        status:
          type: string
          enum: [created, pending, delayed, completed, partial, refunded, failed, expired, canceled]
          description: '`completed`, `partial`, `refunded`, `failed`, `expired` and `canceled` are final.'
        route:
          type: string
          description: The name of the route the swap was placed on, for example `usdc_base_to_eth_base`.
        user_id:
          type: string
          description: The `user_id` of the session that placed the swap.
        wallet_address:
          type: string
          description: The wallet of the session that placed the swap.
        pay:
          $ref: '#/components/schemas/SwapAmount'
        get:
          $ref: '#/components/schemas/SwapAmount'
          description: What the wallet receives. Left out until the amount is known.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    SwapOrderList:
      type: object
      required: [items]
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/SwapOrderItem'
    SwapSessionView:
      type: object
      required: [session_id, route, user_id, wallet_address, expires_at]
      properties:
        session_id:
          type: string
        route:
          type: string
        user_id:
          type: string
        wallet_address:
          type: string
        expires_at:
          type: string
          format: date-time
    Error:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message, ref]
          properties:
            code:
              type: string
              description: Stable and machine readable. Branch on this, never on the message.
            message:
              type: string
              description: Written for developers. Ends with the reference, for example `(N23)`.
            ref:
              type: string
              description: Permanent Numerari error reference, for example `N23`.
            fields:
              type: array
              description: Field paths only, never values.
              items:
                type: string
    TopUpSessionRequest:
      type: object
      additionalProperties: false
      required: [external_user_id, first_name, last_name, email, wallet_address]
      properties:
        external_user_id:
          type: string
          description: Your stable id for the customer. 1 to 128 characters from `A-Za-z0-9_.:-`.
        first_name:
          type: string
          description: 1 to 100 characters. The name the customer is verified and their bank details are issued in.
        last_name:
          type: string
          description: 1 to 100 characters.
        email:
          type: string
          format: email
          maxLength: 254
        wallet_address:
          type: string
          description: |
            The customer's own wallet, as an EIP-55 checksummed address. This is where the funds land. The zero
            address and the burn address are refused.
        asset:
          type: string
          enum: [usdc, usdt]
          description: Optional. Naming `asset` or `network` locks the session to that route.
        network:
          type: string
          enum: [base, ethereum, polygon]
          description: Optional. Which routes are open to you is part of your agreement.
        network_fee_bps:
          type: integer
          description: Optional. Only a rate your agreement allows; otherwise `422 network_fee_bps_not_allowed`.
        amount_usdc:
          type: string
          description: Optional. The most the customer may top up in this session, when a reduced rate applies.
    TopUpSession:
      type: object
      required: [session_id, client_token, expires_at]
      properties:
        session_id:
          type: string
        client_token:
          type: string
          description: Goes to the browser only. Never log it or put it in a URL.
        expires_at:
          type: string
          format: date-time
        asset:
          type: string
        network:
          type: string
        network_fee_bps:
          type: integer
          description: Echoed only when the request set it.
        amount_usdc:
          type: string
          description: Echoed only when the request set it.
        destination_address:
          type: string
          description: The customer's own wallet. Present when the session names a route.
        routes:
          type: array
          description: The routes the module may choose from. Present only when there is a choice or the session names a route.
          items:
            $ref: '#/components/schemas/TopUpRoute'
    TopUpRoute:
      type: object
      properties:
        route:
          type: string
        asset:
          type: string
        network:
          type: string
        display_name:
          type: string
        approximate:
          type: boolean
        approx_label:
          type: string
        min_usd:
          type: string
        max_usd:
          type: string
        daily_limit_usd:
          type: string
    TopUpOrder:
      type: object
      required: [order_id, external_user_id, status, rail, rail_fee_usd, fees_usd, total_usd, wallet_address, network, asset, created_at, expires_at, updated_at, version]
      properties:
        order_id:
          type: string
        external_user_id:
          type: string
        session_id:
          type: string
          description: The session the order was made through. Omitted when there is none.
        status:
          type: string
          enum: [awaiting_funds, funds_received, delivered, cancelled, expired, failed]
          description: |
            `awaiting_funds`: bank instructions issued. `funds_received`: the transfer arrived and the funds are on
            their way. `delivered`: the funds are in the customer's wallet. `cancelled`, `expired` (the payment window
            closed with no transfer) and `failed` (refunded, returned or failed) are final.
        rail:
          type: string
          enum: [fednow, ach, wire]
        amount_usdc:
          type: string
          description: What the customer asked to receive, two decimals.
        rail_fee_usd:
          type: string
          description: The bank-rail fee.
        fees_usd:
          type: string
          description: Network and gas fees, as a dollar amount.
        total_usd:
          type: string
          description: What the customer sends from their bank. `rail_fee_usd + fees_usd = total_usd - amount_usdc`.
        processing_fee_usd:
          type: string
        network_and_gas_fee_usd:
          type: string
        network_fee_bps:
          type: integer
        delivered_amount_usdc:
          type: ['string', 'null']
          description: Six decimals, the exact amount that reached the wallet. `null` until delivered.
        wallet_address:
          type: string
          description: The customer's own wallet.
        network:
          type: string
        asset:
          type: string
        approximate:
          type: boolean
          description: True while the amount is only an estimate, for some stablecoins.
        tx_hash:
          type: ['string', 'null']
        explorer_url:
          type: ['string', 'null']
        created_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        funds_received_at:
          type: ['string', 'null']
          format: date-time
        delivered_at:
          type: ['string', 'null']
          format: date-time
        updated_at:
          type: string
          format: date-time
        version:
          type: integer
          description: Goes up by one on every public status change. Ignore anything older than what you hold.
    TopUpWebhook:
      type: object
      required: [id, type, created_at, data]
      properties:
        id:
          type: string
          description: The event id. Dedupe on it.
        type:
          type: string
          enum:
            - onramp_order.awaiting_funds
            - onramp_order.funds_received
            - onramp_order.delivered
            - onramp_order.cancelled
            - onramp_order.expired
            - onramp_order.failed
        created_at:
          type: string
          format: date-time
        data:
          type: object
          required: [order]
          properties:
            order:
              $ref: '#/components/schemas/TopUpOrder'
    CashOutSessionRequest:
      type: object
      additionalProperties: false
      required: [external_user_id, email, name, wallet_address]
      properties:
        external_user_id:
          type: string
        email:
          type: string
          format: email
        name:
          type: string
          description: A full name, two or more words.
        wallet_address:
          type: string
          description: The customer's own wallet, EIP-55 checksummed. The deposit is expected from it.
    CashOutSession:
      type: object
      required: [session_id, eligibility, expires_at]
      properties:
        session_id:
          type: string
        eligibility:
          type: string
          enum: [verified, needed, pending, rejected]
        kyc_required:
          type: boolean
          description: True when you should collect the customer's details and call the `kyc` route.
        identity_frame_url:
          type: string
          description: An https page to open for the customer, present only when there is a hosted step.
        identity_frame_frameable:
          type: boolean
          description: Present, and `false`, only when the page refuses to be framed. Absent means try the frame.
        expires_at:
          type: string
          format: date-time
        rails:
          type: array
          items:
            $ref: '#/components/schemas/Rail'
        routes:
          type: array
          items:
            $ref: '#/components/schemas/CashOutRoute'
    Rail:
      type: object
      properties:
        id:
          type: string
        fee_usd:
          type: string
        min_usd:
          type: string
        max_usd:
          type: string
        advertised_min_usd:
          type: string
        advertised_max_usd:
          type: string
    CashOutRoute:
      type: object
      properties:
        route:
          type: string
        asset:
          type: string
        network:
          type: string
        display_name:
          type: string
        min_usd:
          type: string
        max_usd:
          type: string
        advertised_min_usd:
          type: string
        advertised_max_usd:
          type: string
        daily_limit_usd:
          type: string
    Eligibility:
      type: object
      required: [eligibility]
      properties:
        eligibility:
          type: string
          enum: [verified, needed, pending, rejected]
    KycRequirements:
      type: object
      properties:
        terms:
          type: object
          properties:
            url:
              type: string
            privacy_url:
              type: string
            terms_version:
              type: string
            privacy_version:
              type: string
        options:
          type: object
          properties:
            employment_statuses:
              type: array
              items:
                type: string
            occupations:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  name:
                    type: string
            sources_of_funds:
              type: array
              items:
                type: string
            account_purposes:
              type: array
              items:
                type: string
            expected_monthly_payments_usd:
              type: array
              items:
                type: string
            account_purpose_other_max_length:
              type: integer
    KycSubmission:
      type: object
      additionalProperties: false
      required: [terms_accepted, terms_version, privacy_version, employment_status, most_recent_occupation, source_of_funds, account_purpose, acting_as_intermediary, expected_monthly_payments_usd, birth_date, address, ssn]
      properties:
        terms_accepted:
          type: boolean
          description: Must be `true`. Show the terms and privacy links next to an unticked checkbox.
        terms_version:
          type: string
        privacy_version:
          type: string
        employment_status:
          type: string
        most_recent_occupation:
          type: string
          description: An occupation `code` from the requirements.
        source_of_funds:
          type: string
        account_purpose:
          type: string
        account_purpose_other:
          type: string
          description: Only for the purpose `other`.
        acting_as_intermediary:
          type: boolean
          description: Required. Whether the customer is acting on behalf of someone else.
        expected_monthly_payments_usd:
          type: string
        birth_date:
          type: string
          description: '`YYYY-MM-DD`. The customer must be 18 or older.'
        address:
          type: object
          required: [line1, city, state, postal_code, country]
          properties:
            line1:
              type: string
            line2:
              type: string
            city:
              type: string
            state:
              type: string
            postal_code:
              type: string
            country:
              type: string
              enum: [US]
        ssn:
          type: string
          description: Sent on to the verifier and dropped. Never stored or logged.
    PhotoIdSubmission:
      type: object
      additionalProperties: false
      required: [residence_country, document, selfie]
      properties:
        residence_country:
          type: string
        document:
          type: object
          required: [type, issuing_country, number, image_front]
          properties:
            type:
              type: string
              description: For example `drivers_license` or `passport`.
            issuing_country:
              type: string
            number:
              type: string
            image_front:
              type: string
              description: A JPEG or PNG data URI.
            image_back:
              type: string
              description: Optional. A JPEG or PNG data URI.
        selfie:
          type: string
          description: A JPEG or PNG data URI.
    BankAccountDetails:
      type: object
      additionalProperties: false
      required: [account_owner_name, owner_attested, routing_number, account_number, address]
      properties:
        account_owner_name:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        owner_attested:
          type: boolean
          description: Must be `true`. The customer confirms the account is their own.
        owner_type:
          type: string
          enum: [individual, business]
          default: individual
        bank_name:
          type: string
        routing_number:
          type: string
        account_number:
          type: string
        account_type:
          type: string
          enum: [checking, savings]
        address:
          type: object
          required: [line1, city, state, postal_code, country]
          properties:
            line1:
              type: string
              maxLength: 35
            line2:
              type: string
            city:
              type: string
            state:
              type: string
              minLength: 2
              maxLength: 2
            postal_code:
              type: string
            country:
              type: string
              enum: [US]
    BankAccount:
      type: object
      required: [ref, status, last4, holder_name_matches]
      properties:
        ref:
          type: string
        status:
          type: string
          enum: [pending_details, verified, rejected]
        last4:
          type: ['string', 'null']
          description: The last four digits, or `null`. The full numbers are never returned.
        holder_name_matches:
          type: boolean
          description: True once the account is verified under the customer's own verified identity.
    BankFrame:
      type: object
      required: [bank_frame_url, ref]
      properties:
        bank_frame_url:
          type: string
        ref:
          type: string
    CashOutQuoteRequest:
      type: object
      additionalProperties: false
      required: [session_id, amount_usdc, rail, network_fee_bps]
      properties:
        session_id:
          type: string
        asset:
          type: string
          enum: [usdc, usdt]
          default: usdc
        network:
          type: string
          enum: [base, ethereum, polygon]
          default: base
        amount_usdc:
          type: string
          description: The amount of the chosen stablecoin, up to two decimals.
        rail:
          type: string
          enum: [ach, wire]
        network_fee_bps:
          type: integer
          description: The rate you assert. It must be one your agreement allows.
    CustomerPrice:
      type: object
      description: The whole price, ready to show. `you_send - total_fee = you_receive`.
      properties:
        you_send:
          type: string
          description: Everything the customer sends in the quote's asset, including the fee transfer when there is one.
        total_fee:
          type: string
        fees:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum: [processing_fee, network_and_gas_fee]
              amount:
                type: string
        you_receive:
          type: string
          description: What reaches the bank.
    FeeTransfer:
      type: object
      properties:
        asset:
          type: string
        network:
          type: string
        amount:
          type: string
        recipient:
          type: string
        expires_at:
          type: string
          format: date-time
    CashOutQuote:
      type: object
      required: [quote_id, network, asset, rail, amount_usdc, processing_fee, network_fee_bps, network_and_gas_fee, total, receive_usd, provider_mode, expires_at, customer_price]
      properties:
        quote_id:
          type: string
        network:
          type: string
        asset:
          type: string
        rail:
          type: string
        amount_usdc:
          type: string
        processing_fee:
          type: string
        network_fee_bps:
          type: integer
        network_and_gas_fee:
          type: string
        total:
          type: string
        receive_usd:
          type: string
          description: What reaches the bank, to the cent.
        provider_mode:
          type: string
          enum: [mock, live]
        expires_at:
          type: string
          format: date-time
        fee_transfer:
          $ref: '#/components/schemas/FeeTransfer'
        customer_price:
          $ref: '#/components/schemas/CustomerPrice'
    CashOutOrderRequest:
      type: object
      additionalProperties: false
      required: [quote_id, bank_account_ref]
      properties:
        quote_id:
          type: string
        bank_account_ref:
          type: string
        fee_tx_hash:
          type: string
          description: Optional. The fee transfer's hash, when the quote has a `fee_transfer`.
    CashOutOrder:
      type: object
      required: [order_id, external_user_id, status, deposit_address, network, asset, rail, amount_usdc, processing_fee, network_fee_bps, network_and_gas_fee, total, receive_usd, customer_price, bank_account_ref, failure_reason, provider_mode, expires_at, created_at, updated_at, completed_at, version]
      properties:
        order_id:
          type: string
        external_user_id:
          type: string
        status:
          type: string
          enum: [awaiting_deposit, deposit_detected, converting, paid, failed, expired]
          description: |
            `awaiting_deposit`: send to the deposit address. `deposit_detected`: the deposit arrived. `converting`:
            on its way to the bank. `paid`, `failed` and `expired` are final. Statuses only move forward.
        deposit_address:
          type: ['string', 'null']
          description: |
            Where the customer sends exactly `amount_usdc`. `null` while one is issued, and again once the order is
            finished.
        network:
          type: string
        asset:
          type: string
        rail:
          type: string
        amount_usdc:
          type: string
        processing_fee:
          type: string
        network_fee_bps:
          type: integer
        network_and_gas_fee:
          type: string
        total:
          type: string
        receive_usd:
          type: string
        customer_price:
          $ref: '#/components/schemas/CustomerPrice'
        bank_account_ref:
          type: ['string', 'null']
        failure_reason:
          type: ['string', 'null']
        provider_mode:
          type: string
          enum: [mock, live]
        expires_at:
          type: string
          format: date-time
          description: The deposit window.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        completed_at:
          type: ['string', 'null']
          format: date-time
        version:
          type: integer
          description: Goes up by one on every public change. Ignore anything older than what you hold.
    CashOutWebhook:
      type: object
      required: [id, type, created_at, data]
      properties:
        id:
          type: string
        type:
          type: string
          enum:
            - offramp_order.created
            - offramp_order.deposit_detected
            - offramp_order.converting
            - offramp_order.paid
            - offramp_order.failed
            - offramp_order.expired
        created_at:
          type: string
          format: date-time
        data:
          type: object
          required: [order]
          properties:
            order:
              $ref: '#/components/schemas/CashOutOrder'
