openapi: 3.0.3
info:
  title: Atum Payment Gateway API
  description: |
    The Atum Payment Gateway API enables secure, cross-chain payments with built-in escrow protection 
    and settlement verification. This API facilitates decentralized payment routing across multiple blockchain 
    networks while ensuring transaction atomicity and settlement guarantees.
    
    ## Supported Blockchains
    - Ethereum and EVM-compatible chains (Arbitrum, Optimism, Base, etc.)
    - Solana
    - Tron

    ## Authentication

    No API key, token, or authorization header is required on any operation.
    A payment carries its own authorization: the `sender_auth` signed messages prove
    control of the funding account, and are verified on every submission.
  version: 1.0.0
servers:
  - url: https://payment-gw.production-mainnet.atum.xyz
    description: Mainnet
  - url: https://payment-gw.production-testnet.atum.xyz
    description: Testnet

# No operation requires credentials. An empty top-level `security` is how OpenAPI
# states that, and it stops code generators emitting auth parameters for an API
# that has none.
security: []

tags:
  - name: Payments
    description: Submit a payment and follow it to settlement, by payment id, by your own request id, or step by step.
  - name: Authorizations
    description: Counterparty authorization requested while a payment is being accepted.
  - name: Quote Requests
    description: The two-phase quote flow - open a quote-request batch, poll it, then award one quote.
  - name: Chain Defaults
    description: The per-chain corridor addresses a client needs before it can build and sign a payment.
  - name: Health
    description: Liveness probe for the gateway.

paths:
  /v1/payments:
    post:
      summary: Submit a payment request
      description: |
       Initiates a payment by submitting a cryptographically signed payment request.
        
        The payment gateway will:
        1. Validate the request and signatures
        2. Find optimal settlement routes across chains/assets
        3. Secure funds in escrow
        4. Coordinate with settlement agents for execution
        5. Return a real-time result if the payout reaches the destination chain inside the
           synchronous window, otherwise return a payment ID and status for polling

        **Idempotency.** `request_id` is the idempotency key, scoped to the source account
        and originator. Submitting the same `request_id` again returns the ORIGINAL payment
        instead of charging a second time, so a client whose request timed out or failed
        in transit can safely re-submit.

        Because a re-submission must be admissible on its own, some fields legitimately
        differ between attempts and are excluded from the comparison: `quote_deadline` and
        `fulfillment_deadline` (both must be in the future, so a later attempt has to move
        them), and the `sender_auth` signature they are signed into.

        What must NOT differ is the payment's economics — source account and asset,
        destination accounts and assets, `fulfillment_amount`, and `max_source_amount` (the
        payer's own risk cap; lowering it on a retry describes a different payment, not the
        same one with less headroom). Re-using one `request_id` for a genuinely different
        payment is a client bug that would otherwise be silently collapsed onto the first
        payment, so it is rejected with `409` and `IDEMPOTENCY_TERMS_MISMATCH`. Use a
        distinct `request_id` per payment.

        **Auto-accept.** With `auto_accept=true` the gateway awards the first valid quote it
        receives at or under `max_source_amount` instead of waiting for `quote_deadline`, so
        set `max_source_amount` to the price you accept. `quote_deadline` still bounds the
        quote window, and a request with no qualifying quote by then fails as usual. The flag
        is not part of the signed request and is never sent to settlers, although an award that
        arrives before `quote_deadline` shows the winning settler it was set. A re-submission
        returns the original payment, so the first submission's value applies.
      operationId: submitPayment
      tags:
        - Payments
      parameters:
        - name: auto_accept
          in: query
          required: false
          description: Award the first valid quote at or under `max_source_amount` instead of waiting for `quote_deadline`; faster, but gives up competitive pricing. Requires `max_source_amount`.
          schema:
            type: boolean
            default: false
        - name: X-Atum-Producer
          in: header
          required: false
          description: >-
            Optional. Names the client library that built the request body, such as `sdk-ts`,
            `sdk-go`, `x402` or `mppx`. Used for compatibility diagnostics only; it never changes
            how the payment is processed.
          schema:
            type: string
          example: sdk-ts
        - name: X-Atum-Deposit-Request-Hash-V2
          in: header
          required: false
          description: >-
            Optional. The depositRequestHash version 2 the client computed over the body it posts,
            as `0x` and 64 lowercase hex digits. The gateway checks it against its own reading of
            the body for compatibility diagnostics only; it is never trusted and never changes how
            the payment is processed. A client sends `X-Atum-Producer` without it when its reading
            refuses the body, which a version 2 deposit could not pay.
          schema:
            type: string
          example: "0x3f1c0e4f6d2b8a9c7e5d1b3a2f4c6e8d0b9a7c5e3d1f2b4a6c8e0d2f4b6a8c0e"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
      responses:
        '200':
          description: Payment request submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        '400':
          description: Invalid request, including `auto_accept=true` without `max_source_amount`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Signature or sender authorization could not be verified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Payment declined during counterparty authorization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: |
            The `request_id` has already been used for a payment with different economics
            (`IDEMPOTENCY_TERMS_MISMATCH`). Re-submitting one `request_id` is how a retry is
            made safe, so it must identify one payment; use a distinct `request_id` per
            payment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Payment request too large to process
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: |
            With `code` `INSUFFICIENT_FUNDS` or `MISSING_TOKEN_APPROVAL`, the paying account could not
            fund the deposit: its source token balance, or its Permit2 approval, is below the amount
            this payment needs. Fix the paying account, then submit with a new `request_id`;
            re-submitting the same `request_id` answers `200` with `status` `failed` and
            `idempotent_replay` `true`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error. A body that carries a `payment_id` names a payment that exists and
            may still settle (with `code` `SETTLEMENT_OUTCOME_UNKNOWN`, settlement may already have
            started), so reconcile before acting: read `GET /v1/payments/{paymentId}/status`, where
            `paymentId` is that `payment_id`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: |
            With `code` `SETTLEMENT_FAILED`, settlement was attempted and did not complete. The
            on-chain outcome is not guaranteed either way, so reconcile before acting: read
            `GET /v1/payments/{paymentId}/status` for the failure detail and
            `GET /v1/payments/{paymentId}/timeline` for the chain trace, where `paymentId` is the
            `payment_id` in this body. Re-submitting the same `request_id` answers `200` with
            `status` `failed` and `idempotent_replay` `true`, so a genuine re-attempt needs a new
            `request_id`. A `502` with any other `code`, or none, is not a settlement failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: >-
            The request was not accepted: a dependency is temporarily unavailable, or
            this operation is paused (`SERVICE_PAUSED`). Nothing was submitted, so the
            request is safe to retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/payments/{paymentId}/status:
    get:
      summary: Get payment status
      description: Retrieve the status of a payment by its ID
      operationId: getPaymentStatus
      tags:
        - Payments
      parameters:
        - name: paymentId
          in: path
          required: true
          description: The ID of the payment to query
          schema:
            type: string
      responses:
        '200':
          description: Payment status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPaymentStatusResponse'
        '404':
          description: Payment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/payments/resolve:
    get:
      summary: Resolve a request ID to a payment ID
      description: |
        Looks up the payment ID associated with a given client-supplied request ID.
        Used by tooling like the payment explorer so callers can look a payment up
        by the request ID they originally submitted.
      operationId: resolvePayment
      tags:
        - Payments
      parameters:
        - name: request_id
          in: query
          required: true
          description: The client-supplied request ID embedded in the payment request
          schema:
            type: string
      responses:
        '200':
          description: Payment found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResolvePaymentResponse'
        '400':
          description: Missing request_id parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No payment found for the given request ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/payments/{paymentId}/timeline:
    get:
      summary: Get step-by-step payment timeline
      description: |
        Returns the settlement timeline for a payment, including every step the
        payment has passed through, per-step durations, chain IDs, transaction
        hashes, and — if the payment has failed — a structured error describing
        where and why it failed.
      operationId: getPaymentTimeline
      tags:
        - Payments
      parameters:
        - name: paymentId
          in: path
          required: true
          description: The ID of the payment to query
          schema:
            type: string
      responses:
        '200':
          description: Timeline retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentTimelineResponse'
        '404':
          description: Payment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/payments/authorizations:
    post:
      summary: Request counterparty authorization
      description: |
        Submits a PaymentRequest for counterparty authorization before settlement.
        The call blocks synchronously until the beneficiary PSP responds or the
        timeout expires (default 30 seconds).

        If authorized, the response includes the counterparty's proof which can
        be attached to the subsequent SubmitPayment call.

        Authorization and RFQ submission are separate steps. This endpoint does
        NOT trigger an auction — the originator must call SubmitPayment separately.
      operationId: authorizePayment
      tags:
        - Authorizations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
      responses:
        '200':
          description: Authorization decision received (authorized or declined)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationResult'
        '400':
          description: |
            The request was rejected before authorization was attempted, so no
            authorization outcome exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: |
            The counterparty's proof was rejected (`PROOF_INVALID` or `PROOF_STALE`).
            This is an authorization outcome, so the body is an `AuthorizationResult`
            with `status: error`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationResult'
        '404':
          description: |
            Counterparty not found (no registration for the resolved DID). An
            authorization outcome, so the body is an `AuthorizationResult` with
            `status: error` and `error_code: COUNTERPARTY_NOT_FOUND`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationResult'
        '500':
          description: |
            Either shape, depending on where the failure happened. A failure before
            authorization was attempted returns `ErrorResponse`. A failure carrying an
            authorization outcome returns `AuthorizationResult` with `status: error`.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorResponse'
                  - $ref: '#/components/schemas/AuthorizationResult'
        '502':
          description: |
            Counterparty webhook error (HTTP error or connection failure). An
            authorization outcome, so the body is an `AuthorizationResult` with
            `status: error` and `error_code: WEBHOOK_ERROR` or
            `WEBHOOK_CONNECTION_ERROR`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationResult'
        '504':
          description: |
            Authorization timed out (the counterparty did not respond). An
            authorization outcome, so the body is an `AuthorizationResult` with
            `status: timeout`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationResult'

  /v1/payments/quote-requests:
    post:
      summary: Create a quote-request batch
      description: |
        Opens a quote-request batch: broadcasts the corridor to settlement agents and collects
        their signed quotes. This is the first phase of the two-phase quote → award flow — the
        originator later picks one quote and commits in a separate POST /v1/payments/awards call.
        No spend authorization is supplied here; `sender_auth` is deferred to award time.

        Wait modes (the `wait` query parameter):
        - `wait=false` (default): return 202 immediately with status `collecting`; poll
          GET /v1/payments/quote-requests/{quoteRequestId} until status is `ready`.
        - `wait=true`: hold the connection for up to
          min(quote_deadline, quote_sync_wait_seconds) and return 200 with the collected quotes
          (status `ready`). If the sync cap fires before the quote deadline, return 200 with
          status `collecting` and poll the status endpoint.

        Collection continues server-side until the quote deadline regardless of the HTTP
        connection, so quotes remain retrievable via the status endpoint in either mode.

        **Idempotency.** `request_id` is the idempotency key, scoped to the source account
        and originator — the same key, and the same contract, as POST /v1/payments.
        Submitting the same `request_id` again returns the ORIGINAL batch instead of opening
        a second one, so a client whose request timed out or failed in transit can safely
        re-submit and recover its `quote_request_id`.

        Because a re-submission must be admissible on its own, some fields legitimately
        differ between attempts and are excluded from the comparison: `quote_deadline` and
        `fulfillment_deadline` (both must be in the future, so a later attempt has to move
        them) and the `proof` that covers them. An expired `quote_deadline` on a
        re-submission is NOT an error — the request is resolved onto the batch that already
        exists rather than used to open one. There is no `sender_auth` to re-sign here: this
        endpoint rejects it, because the spend authorization belongs to the award call.

        The collection window belongs to the BATCH, not to the request. Asking again with a
        later `quote_deadline` does not extend a window already open; `quote_deadline` in the
        response is the batch's own, and `status` says whether collection is still running.

        What must NOT differ is the corridor's economics — source account and asset,
        destination accounts and assets, `fulfillment_amount`, and `max_source_amount`.
        Re-using one `request_id` for a genuinely different corridor is a client bug that
        would otherwise be silently collapsed onto the first batch, returning quotes for a
        corridor that was never requested. It is rejected with `409` and
        `IDEMPOTENCY_TERMS_MISMATCH`. Use a distinct `request_id` per quote-request.
      operationId: createQuoteRequest
      tags:
        - Quote Requests
      parameters:
        - name: wait
          in: query
          required: false
          description: Return a handle immediately (`false`, default) or hold the connection for collected quotes (`true`).
          schema:
            type: boolean
            default: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateQuoteRequest'
      responses:
        '200':
          description: |
            Quote-request resolved synchronously. `status` is `ready` when quotes were collected,
            or `collecting` when the sync wait cap fired before the quote deadline.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuoteRequestResponse'
        '202':
          description: Quote-request accepted; collection continues asynchronously.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuoteRequestAccepted'
        '400':
          description: |
            Invalid request. `QUOTE_DEADLINE_NOT_FUTURE` is the one worth planning for: a NEW
            quote-request whose `quote_deadline` has already passed is refused, because there is
            no window left to collect quotes in. It does not apply to a re-submission — an
            already-used `request_id` resolves onto the batch that exists and its expired
            deadline is ignored, which is what makes a retry recoverable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: |
            The `request_id` has already been used for a quote-request with different
            economics (`IDEMPOTENCY_TERMS_MISMATCH`). Re-submitting one `request_id` is how a
            retry is made safe, so it must identify one batch; use a distinct `request_id`
            per quote-request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: >-
            The request was not accepted: a dependency is temporarily unavailable, or
            this operation is paused (`SERVICE_PAUSED`). Nothing was submitted, so the
            request is safe to retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/payments/quote-requests/{quoteRequestId}:
    get:
      summary: Get quote-request batch status
      description: |
        Returns the current state of a quote-request batch: a derived status, the collected
        quotes (each with its settler-signed `award_deadline`), and the awarded
        (quote_id, payment_id) pairs once a quote has been awarded. Used for async polling,
        connection-drop recovery, and re-reading quotes before awarding.

        The `status` here describes the quote-request batch lifecycle
        (`collecting`/`ready`/`awarded`/`expired`) and is disjoint from the payment-status enum
        returned by the award and payment-status endpoints.
      operationId: getQuoteRequestStatus
      tags:
        - Quote Requests
      parameters:
        - name: quoteRequestId
          in: path
          required: true
          description: The ID of the quote-request batch to query
          schema:
            type: string
      responses:
        '200':
          description: Quote-request status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuoteRequestStatusResponse'
        '404':
          description: Quote-request not found, or not owned by the caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/payments/awards:
    post:
      summary: Award a quote
      description: |
        Commits to a payment by awarding one quote from a previously-collected batch. The
        originator submits two signatures from their wallet: `sender_auth` (the Permit2 deposit
        authorization) and a fully-formed `bid_award` declaration whose `authorization` carries
        the Escrow reserve-witness signature naming the chosen settler. The awarded quote is
        identified server-side by content-hashing `bid_award.fulfillment_quote_json` — there is
        no `quote_id` on the wire.

        From this call onward the `status` field describes the payment lifecycle (disjoint from the
        quote-request batch status). Track the payment afterward via
        GET /v1/payments/{paymentId}/status — a separate endpoint with its own status vocabulary
        (an in-progress payment reads as `pending` there).

        Wait modes (the `wait` query parameter):
        - `wait=false` (default): return 202 immediately with `payment_id` and status `awarding`;
          poll GET /v1/payments/{paymentId}/status.
        - `wait=true`: hold the connection for up to payment_sync_wait_seconds and
          return 200 with the payment result. If the sync cap fires first, return 200 with a
          non-terminal status (`awarding`); poll GET /v1/payments/{paymentId}/status.
      operationId: awardQuote
      tags:
        - Quote Requests
      parameters:
        - name: wait
          in: query
          required: false
          description: Return a handle immediately (`false`, default) or hold the connection for the payment result (`true`).
          schema:
            type: boolean
            default: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AwardRequest'
      responses:
        '200':
          description: |
            Award resolved synchronously. `status` is `completed` when settlement finished within
            the sync wait, or a non-terminal payment status (e.g. `awarding`) if the cap fired first.
            The payment's transactions are read from GET /v1/payments/{paymentId}/status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardResponse'
        '202':
          description: Award accepted; settlement continues asynchronously.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardAccepted'
        '400':
          description: Invalid request (bad signatures, expired quote, or ownership mismatch)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: |
            The quote, or another quote in the same batch, has already been awarded
            (single-award-per-batch, FR-09).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/defaults:
    get:
      summary: Get chain defaults
      description: |
        The addresses needed to build a payment on a chain: the escrow, the accounts named
        in the deposit authorization, and the fulfillment verifier. Fetch these rather than
        hardcoding them - they change when a chain's contracts are redeployed.

        With `chain_id`, returns that chain. Without it, or with an empty value, returns
        every chain the gateway serves, keyed by CAIP-2 chain id.

        A chain that is not fully configured is still returned when asked for by
        `chain_id`, with the missing address empty, but is left out of the full listing.
        Treat an empty address as a chain you cannot pay on.
      operationId: getDefaults
      tags:
        - Chain Defaults
      parameters:
        - name: chain_id
          in: query
          required: false
          description: >-
            CAIP-2 chain identifier. Omit it, or send it empty, to receive every chain
            the gateway serves, keyed by chain id.
          schema:
            type: string
          example: "eip155:84532"
      responses:
        '200':
          description: >-
            Chain defaults. A single object when `chain_id` was supplied, otherwise an
            object keyed by CAIP-2 chain id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDefaultsResult'
        '400':
          description: The `chain_id` is not a valid CAIP-2 chain identifier
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: >-
            The requested chain is not served by this gateway, or - when `chain_id` was
            omitted - no chain could be resolved at all
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: A dependency is temporarily unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /health:
    get:
      summary: Health check
      description: Returns the health status of the service
      operationId: healthCheck
      tags:
        - Health
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok

components:
  schemas:
    AuthorizationResult:
      type: object
      description: |
        The result of a counterparty authorization request. Contains either
        the PSP's authorization decision (authorized/declined with proof) or
        an error indicating why authorization could not be completed.
      required:
        - payment_id
        - counterparty_did
        - status
      properties:
        payment_id:
          type: string
          description: Correlation key for this authorization
          example: "0x761989729fefb4b0cb8b3e6f787301a3878c91e8fba35ed362a079292879f34f"
        counterparty_did:
          type: string
          description: The beneficiary PSP's DID
          example: "did:pkh:eip155:1:0xdeadbeef"
        status:
          type: string
          description: |
            Authorization outcome. "authorized" or "declined" when the PSP responded.
            "error" or "timeout" when the authorization could not be completed.
          enum:
            - authorized
            - declined
            - error
            - timeout
          example: "authorized"
        authorization_response:
          type: object
          description: The PSP's raw authorization response (present when status is authorized or declined)
          additionalProperties: true
        error_code:
          type: string
          description: |
            Machine-readable error code (present when status is error or timeout).
            Counterparty-sourced codes are derived from the error code the
            Counterparty Gateway publishes. GATEWAY_TIMEOUT, PROOF_INVALID, and
            PROOF_STALE are raised by this gateway itself (no counterparty envelope corresponds).
          enum:
            - COUNTERPARTY_NOT_FOUND
            - COUNTERPARTY_TIMEOUT
            - WEBHOOK_ERROR
            - WEBHOOK_CONNECTION_ERROR
            - INTERNAL_ERROR
            - GATEWAY_TIMEOUT
            - PROOF_INVALID
            - PROOF_STALE
          x-enum-description: |
            COUNTERPARTY_NOT_FOUND, COUNTERPARTY_TIMEOUT, WEBHOOK_ERROR,
            WEBHOOK_CONNECTION_ERROR, and INTERNAL_ERROR are derived from the
            error code the Counterparty Gateway publishes.
            GATEWAY_TIMEOUT is emitted by the gateway when no authorization
            response is received within the system-wide timeout — source unknown
            (counterparty delay, transport failure, or gateway unavailability).
            Originator should retry; counterparty-side idempotency prevents PSP re-charge
            if the original was already processed.

            PROOF_INVALID is emitted when the W3C Data Integrity proof on the
            beneficiary PSP's AuthorizationResponse fails verification: signature
            recovery failed, recovered DID does not match the destination DID,
            response shape is malformed (missing @context / payment_id /
            counterparty_did / proof), or the suite type is unsupported. The
            underlying reason cardinality is collapsed so originators see one
            actionable category.

            PROOF_STALE is emitted when proof.created falls outside the
            configured freshness window. Originators should retry with a fresh
            request — the freshness window closes a replay attack vector where a
            captured-but-cryptographically-valid proof could otherwise be replayed
            indefinitely.
        error_message:
          type: string
          description: Human-readable error description
        webhook_http_status:
          type: integer
          description: HTTP status code from the PSP webhook (only for WEBHOOK_ERROR)

    PaymentRequest:
      description: |-
        Structured payment request with sender authorization and optional W3C Verifiable Credentials
      type: object
      required:
        - version
        - request_id
        - source
        - destination
        - fulfillment_amount
        - sender_auth
        - quote_deadline
        - fulfillment_deadline
        - fulfillment_verifier
        - escrow_contract_address
      properties:
        version:
          type: string
          description: Semver-shaped declaration version (MAJOR.MINOR). The major component is locked to this schema's parent directory (v1 → major must be 1). Producers MUST emit the canonical value exported by the bindings' Version constant; the canonical bumps on each additive minor evolution.
          pattern: ^1\.[0-9]+$
          example: "1.0"
        request_id:
          type: string
          description: Unique identifier for this payment request (used for idempotency)
          example: req_123456789
        source:
          $ref: '#/components/schemas/OwnedAsset'
        destination:
          type: array
          description: |-
            Array of destination assets for the settlement agent to choose from (at least one required, at most 16).
            The ceiling bounds the fan-out one request can buy: every consumer iterates this list.
          minItems: 1
          maxItems: 16
          items:
            $ref: '#/components/schemas/OwnedAsset'
        fulfillment_amount:
          type: string
          description: |-
            The exact amount to be received at the destination (in the smallest unit, e.g., wei for ETH, cents for USD).
          example: "1000000"
        max_source_amount:
          type: string
          description: The maximum amount willing to be spent from the source (in the smallest unit).
          example: "1000000"
        quote_deadline:
          type: string
          format: date-time
          description: |-
            Required. The deadline for receiving price quotes from settlement providers. After this
            point no new quotes are accepted. The gateway injects no default and validates the value
            is in the future. The originator must supply it, and a request that omits it or supplies
            a past value is rejected with 400.

            Keep this window short. A settler holds its quoted price for a limited period of its
            own choosing, and the gateway selects only once the window has closed, so a deadline
            set beyond that hold leaves no quote still awardable and the request is declined with
            QUOTE_WINDOW_TOO_LONG. That hold is set by each settler and is not part of this
            contract, so treat 60 seconds as a practical upper bound and prefer a shorter window
            where your integration allows. A submit with auto_accept can be awarded before the
            window closes, but settlers still decline a window longer than their hold, so keep it
            short either way.
          example: "2024-12-25T10:30:00Z"
        fulfillment_deadline:
          type: string
          format: date-time
          description: |-
            Required. The time by which the payout to the recipient must be mined on the destination
            chain. If no payout is mined by then, your escrowed funds are refunded. The payout does
            not have to be final by then: `completed` follows once the
            destination chain judges it final. Leave room for your deposit to confirm on the source
            chain first, which on some chains takes minutes. The gateway injects no default
            and validates the value is in the future. The originator must supply it, and a request
            that omits it or supplies a past value is rejected with 400.
          example: "2024-12-25T11:00:00Z"
        executor:
          description: Who performs each leg of the payment. Omitted on the wire means settler for every leg. The split object keeps deposit, reserve, and fulfill as separate keys.
          oneOf:
            - type: string
              enum:
                - settler
                - originator
            - type: object
              additionalProperties: false
              required:
                - deposit
                - reserve
                - fulfill
              properties:
                deposit:
                  type: string
                  enum:
                    - settler
                    - originator
                reserve:
                  type: string
                  enum:
                    - settler
                    - originator
                fulfill:
                  type: string
                  enum:
                    - settler
                    - originator
        deposit_nonce:
          type: string
          description: 'The nonce the payer passed to the escrow''s directDeposit, as a decimal uint256. Only on an originator-executed deposit (executor.deposit is originator), where it is required: with the source account, chain and escrow it names the deposit the payer funded. Each nonce funds one deposit per account, forever.'
          minLength: 1
          maxLength: 78
          pattern: ^[0-9]+$
        settler_auth_required:
          type: object
          description: Policy requirements for settler authentication. Keys are policy names, values indicate if the policy is required.
          additionalProperties:
            type: boolean
        sender_auth:
          $ref: '#/components/schemas/SenderAuth'
        originator_auth:
          $ref: '#/components/schemas/VerifiableCredentialAuth'
        quote_selector:
          type: string
          description: |-
            Wallet address or public key of a trusted service that will automatically select
            the best exchange rate for your payment. Leave empty to use the default selector.
          example: "0x742D35cC6634c0532925a3b844Bc9e7595F41360"
        fulfillment_verifier:
          type: object
          description: |-
            The verification service that confirms the payment was delivered before the escrow
            releases the source funds, and the account it signs with. Required on every chain:
            the gateway's `/v1/defaults` response supplies it for each chain.
          required:
            - account
            - endpoint
          properties:
            account:
              type: string
              description: The wallet address or public key of the verification service
              example: "0x892BB2e4F6b14a2B5b82Ba8d33E5925D42D4431F"
            endpoint:
              type: string
              format: uri
              description: |-
                Origin of the fulfillment verifier service, with no path — the caller
                appends the verifier's own API paths. The gateway's `/v1/defaults` response
                supplies the default fulfillment verifier for each chain.
              example: https://veri-fill.production-testnet.atum.xyz
        escrow_contract_address:
          type: string
          description: Escrow contract on the source chain that holds the source funds until proof of fulfillment has been verified. Required on every chain. Take the value for the source chain from the payment gateway's GET /v1/defaults (`escrow_contract`).
          example: "0x742D35cC6634c0532925a3b844Bc9e7595F41360"
        fulfillment_proxy:
          type: string
          description: |-
            Fulfillment Proxy contract address, used to emit proof of fulfillment on the destination chain. Leave empty to use the default.
          example: "0x892BB2e4F6b14a2B5b82Ba8d33E5925D42D4431F"
        settler_requirements:
          type: object
          description: Optional settler filtering requirements. If whitelist is present, only whitelisted settlers may win. If blacklist is present, blacklisted settlers are excluded. Both can be specified; blacklist takes precedence (a settler in both lists is rejected).
          properties:
            whitelist:
              type: array
              uniqueItems: true
              minItems: 1
              maxItems: 100
              description: List of settler DIDs permitted to fulfill this request. If present and non-empty, only these settlers may win. Use W3C DID format (e.g., did:pkh:eip155:1:0xABC...).
              items:
                type: string
                pattern: ^did:[a-z][a-z0-9]*:[a-zA-Z0-9._:%-]+$
              example:
                - did:pkh:eip155:1:0x742D35cC6634c0532925a3b844Bc9e7595F41360
            blacklist:
              type: array
              uniqueItems: true
              minItems: 1
              maxItems: 100
              description: List of settler DIDs excluded from fulfilling this request. If present and non-empty, these settlers are rejected. Use W3C DID format (e.g., did:pkh:eip155:1:0xABC...).
              items:
                type: string
                pattern: ^did:[a-z][a-z0-9]*:[a-zA-Z0-9._:%-]+$
              example:
                - did:pkh:eip155:1:0x892bb2E4F6b14a2B5b82bA8D33e5925d42d4432f

    FulfillmentAuthorization:
      description: |-
        Authorization for an originator to fulfill a payment request. The settler produces this declaration after authorizeFulfillment when the payment request's fulfill executor is "originator". A settler fulfill does not produce it.

        Canonical JSON Schema: schemas/declarations/FulfillmentAuthorization/v1/schema.json
        Published at https://schemas.atum.xyz/declarations/FulfillmentAuthorization/v1
      type: object
      additionalProperties: false
      required:
        - version
        - scheme
        - authorization
        - fulfillment_quote_json
        - evidence
      properties:
        version:
          type: string
          description: Semver-shaped declaration version (MAJOR.MINOR). The major component is locked to this schema's parent directory (v1 → major must be 1).
          pattern: ^1\.[0-9]+$
          example: "1.0"
        scheme:
          type: string
          description: 'Authorization scheme: EIP-3009 for an EVM destination.'
          enum:
            - EIP-3009
        authorization:
          description: Signed authorization. For scheme EIP-3009, message_prehash is the EIP-712 TransferWithAuthorization typed data as a JSON string ({domain, types, primaryType, message}, with uint256 values as decimal strings), message is its EIP-712 digest, signature is the settler's 65-byte signature over that digest, and payload is absent. message.validBefore is the payment request's fulfillment_deadline in whole unix seconds, and message.nonce is the fulfillment quote hash.
          $ref: '#/components/schemas/SignedMessage'
        fulfillment_quote_json:
          type: string
          description: Raw JSON of the fulfillment quote (schemas/declarations/FulfillmentQuote/v1/schema.json), including proof metadata so its canonical quote hash can be computed.
        evidence:
          type: object
          description: Pointer to the on-chain evidence of the fulfillment authorization.
          additionalProperties: false
          required:
            - transaction_id
            - log_index
          properties:
            transaction_id:
              type: string
              minLength: 1
              description: Chain transaction identifier. EVM transactions are 0x-prefixed hex, Tron transactions are hex without that prefix, and Solana transactions are base58.
            log_index:
              type: integer
              minimum: 0

    OwnedAsset:
      type: object
      description: Represents a cryptocurrency or token in a specific wallet. This tells the system what asset you're sending/receiving and which wallet to use.
      required:
        - asset_identifier
        - account
      properties:
        asset_identifier:
          type: string
          description: |-
            A unique identifier for the asset using CAIP-19 format.
            CAIP-19 is a standard way to identify blockchain assets: {chain_id}/{asset_namespace}:{asset_reference}
            Examples:
            - Ethereum USDC: "eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
            - Arbitrum USDC: "eip155:42161/erc20:0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
            - Solana USDC: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
            - Tron USDT: "tron:mainnet/trc20:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"
          pattern: ^[a-z0-9]+:[a-zA-Z0-9_-]+/[a-z0-9-]{3,8}:[-.%a-zA-Z0-9]{1,128}(/[-.%a-zA-Z0-9]{1,78})?$
          example: eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
        account:
          type: string
          description: |-
            The wallet address that owns this asset.
            Format depends on the blockchain:
            - Ethereum/EVM: 0x-prefixed hex address (42 characters)
            - Solana: Base58 encoded address
            - Tron: T-prefixed Base58 address

            A destination account is checked at ingress and must be payable on the chain named by
            its `asset_identifier`: it parses for that chain, carries a valid EIP-55 checksum when
            mixed-case, has no surrounding whitespace, and is not the zero address. A receiver that
            fails any of these is refused with `INVALID_DESTINATION_ACCOUNT`, before any funds move.
          minLength: 1
          maxLength: 128
          example: "0x742D35cC6634c0532925a3b844Bc9e7595F41360"

    SenderAuth:
      type: object
      description: Authorization from the asset owner to execute the payment. The exact format depends on the source blockchain's authorization mechanism.
      required:
        - message_scheme
        - signed_messages
      properties:
        verifiable_credential:
          $ref: '#/components/schemas/VerifiableCredentialAuth'
          deprecated: true
          description: 'DEPRECATED: inner-document credential carrier. Credentials MUST ride ONLY in the holder-signed PaymentRequestEnvelope (PRE); the inner PaymentRequest carries no credential and its Data Integrity signature EXCLUDES this field (stripped before canonicalization on both producer and verifier). Populated only for one back-compat rollout cycle, then removed.'
        message_scheme:
          $ref: '#/components/schemas/SenderAuthMessageScheme'
        signed_messages:
          type: array
          description: Array of signed messages (at least one required)
          minItems: 1
          items:
            $ref: '#/components/schemas/SignedMessage'

    SenderAuthMessageScheme:
      type: string
      description: |-
        The signature method used for authorizing this payment:
        - `EVM_PERMIT2`: Gasless token approvals for Ethereum/EVM chains
        - `EVM_PERMIT2_ESCROW`: Gasless approvals with escrow support
        - `SOLANA`: Standard Solana transaction signatures
        - `TRON`: Tron transaction signatures
      enum:
        - EVM_PERMIT2
        - EVM_PERMIT2_ESCROW
        - SOLANA
        - TRON

    SignedMessage:
      type: object
      description: A message that has been cryptographically signed to prove authorization. The signature proves you control the wallet that's sending funds.
      required: [message, signature]
      properties:
        message:
          type: string
          description: The data that was signed, hex-encoded with a 0x prefix on every supported chain. For the deposit (signed_messages[0]) it is the 32-byte hash of message_prehash.
          example: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
        message_prehash:
          type: string
          description: |-
            The original data that `message` is the hash of. Required on every entry of a payment
            request's `sender_auth.signed_messages`: the gateway reads the signed terms from it.
          example: '{"permit":{"token":"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48","amount":"1000000"}}'
        signature:
          type: string
          description: The cryptographic signature proving you authorized this message. Hex-encoded with a 0x prefix on every supported chain. The signer's own public key is base58 on Solana, but the signature itself is not.
          example: "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab1c"
        payload:
          type: object
          description: Optional chain-specific payload containing additional signing context (e.g., delegate_signer for Solana). Preserved through the pipeline for downstream consumers.
          additionalProperties: true
          example:
            delegate_signer: 9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin

    VerifiableCredentialAuth:
      type: object
      description: |-
        Optional identity verification using cryptographic credentials.

        DEPRECATED. Credentials are moving to a holder-signed W3C VerifiablePresentation that
        travels alongside a request rather than inside it. That envelope is not part of this
        HTTP contract, so there is nothing here to move them to yet: treat this as a legacy
        carrier, and do not build a new integration on it.
      required:
        - verifiable_credential
        - verification_method_id
        - signature
      properties:
        verifiable_credential:
          $ref: '#/components/schemas/VerifiableCredential'
        verification_method_id:
          type: string
          description: Reference to verification method from the DID Document
        signature:
          type: string
          description: Cryptographic signature matching the verification method type

    VerifiableCredential:
      type: object
      description: W3C Verifiable Credential structure conforming to the W3C Verifiable Credentials Data Model v1.1
      required:
        - '@context'
        - id
        - type
        - issuer
        - issuanceDate
        - credentialSubject
        - proof
      properties:
        '@context':
          type: array
          description: JSON-LD context array, must include 'https://www.w3.org/2018/credentials/v1'
          items:
            type: string
          example:
            - https://www.w3.org/2018/credentials/v1
        id:
          type: string
          description: Unique identifier for this credential
        type:
          type: array
          description: Credential types, must include 'VerifiableCredential'
          items:
            type: string
          example:
            - VerifiableCredential
            - KYCVerifiedCredential
        issuer:
          oneOf:
            - type: string
            - type: object
          description: DID or issuer object of the credential issuer
        issuanceDate:
          type: string
          format: date-time
          description: When the credential was issued
        expirationDate:
          type: string
          format: date-time
          description: When the credential expires
        credentialSubject:
          type: object
          description: Claims about the credential subject (structure varies by issuer)
          additionalProperties: true
        credentialStatus:
          type: object
          description: Information for credential revocation checking. Not consulted by the verifier today.
          additionalProperties: true
        proof:
          type: object
          description: Cryptographic proof of credential integrity
          additionalProperties: true

    PaymentStatus:
      type: string
      description: |
        Where your payment is in its lifecycle. One payment reads the same however you ask
        about it.

        - `pending`: accepted and in progress. Nothing has reached the recipient yet.
        - `finalizing`: the transaction paying your recipient is on chain, but its chain has
          not yet judged it final. NOT FINAL, see below.
        - `completed`: delivered and final on the destination chain.
        - `failed`: did not complete. Any funds held in escrow are returned, and `error`
          describes what went wrong.
        - `refunding`: the settler will not deliver this payment and your funds are being
          returned from escrow. NOT FINAL: it becomes `refund_available` or `refunded`, and it
          can still become `completed` or `failed`.
        - `refund_available`: the settler did not deliver and the refund is authorized for you
          to submit. GET /v1/payments/{paymentId}/status returns `refund_signature`, which you
          submit to the source escrow to return your funds. The other responses report this
          status without the signature. NOT FINAL: the funds are still in escrow, so it becomes
          `refunded` once the refund lands, or `completed` if the settler delivers late and is
          paid first. Do not pay again while it is `refund_available`.
        - `refunded`: your funds were returned from the source escrow. `transactions.refund` is
          the refund transaction, when it is known.

        `completed`, `failed` and `refunded` are final and will not change afterwards.
        `pending`, `finalizing`, `refunding` and `refund_available` will.

        **Do not treat `finalizing` as delivered.** It says the payment has been made on
        chain but is not yet irreversible, much as a card authorization is not yet a
        settlement. It normally becomes `completed`, after seconds on some chains and minutes
        on others. If a chain reorganization drops the transaction before it is final, your
        funds are refunded instead. Acting on
        `finalizing` — releasing goods, crediting an account — means accepting that risk
        deliberately, at whatever threshold suits you rather than the one we wait for.

        `finalizing` is about paying the recipient. While your own funds are still being
        committed on the source chain the payment is `pending`, because nothing has reached
        the recipient yet.

      enum:
        - pending
        - finalizing
        - completed
        - failed
        - refunding
        - refund_available
        - refunded
      example: pending

    PaymentTransaction:
      type: object
      description: |
        One on-chain transaction belonging to a payment: which chain, which transaction, and
        which block it landed in.

        Whether the payment has actually happened is answered by `status`, not here. Read this
        to look the transaction up on chain and to verify it yourself.
      required:
        - transaction_hash
        - chain_id
      properties:
        transaction_hash:
          type: string
          description: |
            The transaction's hash on its chain. Hex hashes carry the `0x` prefix, including on
            Tron, whose own tooling omits it.
          pattern: "^(0x[a-fA-F0-9]{64}|[1-9A-HJ-NP-Za-km-z]{32,88})$"
          example: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
        chain_id:
          type: string
          description: CAIP-2 identifier of the chain the transaction is on.
          pattern: "^[a-z0-9]+:[a-zA-Z0-9_-]+$"
          example: "eip155:42161"
        block_number:
          type: integer
          description: |
            The block the transaction landed in. Absent until it has been mined.

            Provisional while `status` is `finalizing`: a reorganization can still move the
            transaction to a different block. Settled once `status` is `completed` — keep it as
            a final record only from then.
          example: 61234567

    PaymentTransactions:
      type: object
      description: |
        The transactions a payment has produced, one entry per stage, added as each becomes
        known. A stage absent here has produced no transaction yet.

        These are the movements that decide whether your payment happened: your funds being
        committed, your recipient being paid, and your funds being returned when the payment
        is refunded. Present on every outcome, so a payment that did not complete can still be
        traced on chain.

        Where a stage is attempted more than once, the entry describes the attempt that
        counts — the one that succeeded, or the last one if none did.
      properties:
        deposit:
          allOf:
            - $ref: '#/components/schemas/PaymentTransaction'
          description: Committing your funds on the source chain.
        fulfillment:
          allOf:
            - $ref: '#/components/schemas/PaymentTransaction'
          description: Paying your recipient on the destination chain.
        refund:
          allOf:
            - $ref: '#/components/schemas/PaymentTransaction'
          description: |
            Returning your funds from the escrow on the source chain. Can be absent on a
            `refunded` payment when the refund transaction is not known.

    RefundSignature:
      type: object
      description: |
        The refund authorization for a `refund_available` payment, as the verifier signed it.
        Submit it to the source chain's escrow `refund` to return your funds yourself.

        Anyone holding it can submit the refund, but the escrow only ever pays the depositor. If
        the settler delivers late and is paid first, the refund no longer goes through.
        On Solana the submitter also receives the rent of the deposit account the refund closes.
      required:
        - signature
        - message_hash
        - message_prehash
      properties:
        signature:
          type: string
          description: |
            The verifier's signature over `message_hash`. Hex with the `0x` prefix on EVM and
            Tron chains, hex without it on Solana.
        message_hash:
          type: string
          description: The signed digest, hex without the `0x` prefix.
        message_prehash:
          type: string
          description: |
            The signed message as JSON. On EVM and Tron chains it carries the RefundWitness the
            escrow's `refund` takes.

    PaymentResponse:
      type: object
      description: |
        Response from submitting a payment request. If settlement completes inside the
        gateway's synchronous window, the response is `completed` and `transactions` carries
        both the deposit and the payout. The window also ends when the payment reaches `finalizing`,
        so the response normally carries the payout transaction (`transactions.fulfillment`)
        within seconds. Otherwise you receive a payment_id plus the payment's current
        `status`, and can poll /v1/payments/{paymentId}/status for updates.

        Read `status` before deciding what to do next: a `pending` or `finalizing` payment is
        in flight and must NOT be re-submitted under a new request_id (that would be a second
        payment), whereas a `failed` one is terminal — re-submitting it under the SAME
        request_id resolves to the same terminal payment, so a genuine re-attempt needs a
        new request_id.

        **A synchronously-completed payment carries proof of QUOTE as well as of delivery.** When
        settlement lands inside the window you get `status: completed`, the deposit and payout in
        `transactions`, and — since a quote necessarily was awarded to get there —
        `quote_id` and `fulfillment_quote`. The fast path therefore needs no follow-up call to
        verify: recompute `quote_hash` over the returned quote and compare it against the on-chain
        commitment from this response alone.

        `status` is present on every response. `completed` is always accompanied by
        `transactions.deposit` and `transactions.fulfillment`: either one missing from a
        `completed` payment is a gateway fault, to report with the `payment_id`. `failed` is
        accompanied by `error` where a reason has been recorded.
      required:
        - payment_id
        - status
        - idempotent_replay
      properties:
        payment_id:
          type: string
          description: |
            Unique ID for tracking this payment. Save this to check status later.
          example: "0x761989729fefb4b0cb8b3e6f787301a3878c91e8fba35ed362a079292879f34f"
        status:
          $ref: '#/components/schemas/PaymentStatus'
        transactions:
          $ref: '#/components/schemas/PaymentTransactions'
        idempotent_replay:
          type: boolean
          description: |
            Whether this response describes a payment that already existed, rather than one
            created by this request. `true` means the request_id had been used before and you
            are being handed the ORIGINAL payment — no second payment was created and nothing
            additional was charged.

            **Re-attempting a payment.** Re-submit the same request and you get the same payment
            back. You may re-send the original bytes unchanged: the deadlines will have expired by
            then — `quote_deadline` bounds the auction and is short, while this endpoint may hold a
            submission for up to 30 seconds — and an expired deadline on a re-submission is not an
            error, because the request is resolved onto the payment that already exists rather than
            used to create one.

            Re-signing with fresh deadlines is equally fine and returns the same payment. What you
            must NOT change is the request_id, and what you must not change under it is the
            payment's economics — source, destination, fulfillment_amount, max_source_amount — which
            are rejected with 409 IDEMPOTENCY_TERMS_MISMATCH. Deadlines and the signature are
            exempt precisely so that a re-attempt is possible.

            A genuinely new payment needs a NEW request_id. In particular a `failed` payment is
            terminal: re-submitting its request_id keeps returning that dead payment, so recovering
            means starting a new one under a new key.

            Present on every response, `false` for a newly created payment. A response without
            the field is from a gateway predating it, not a newly created payment.

            This is the field to read when reconciling a suspected double charge: two
            submissions where the second reports `true` are one payment, whereas two both
            reporting `false` are two. It says nothing about how far the payment has got —
            read `status` for that.
          example: false
        quote_id:
          type: string
          description: |
            The winning quote's ID. Present when `status` is `completed` — a payment cannot settle
            without an award — and absent on a `pending` response, where no quote has been selected
            yet. Same value and meaning as on GET /v1/payments/{paymentId}/status.
          example: "0x9a3b...e8d4"
        fulfillment_quote:
          type: object
          description: |
            The settler-signed FulfillmentQuote for the winning quote, returned verbatim as an
            opaque signed document — the PREIMAGE of the `quote_hash` committed on-chain. Same
            value, semantics and canonicalization caveats as on
            GET /v1/payments/{paymentId}/status; see that field for how to verify it.

            Present when `status` is `completed`. It may be absent even then, if the stored quote
            is unreadable: the award is reported through `quote_id` regardless, so a present
            `quote_id` with no `fulfillment_quote` means "verification preimage unavailable" and
            never "no quote was awarded". A consumer that requires the preimage should fall back to
            the status endpoint rather than treat the payment as unverified.
        fulfillment_authorization:
          type: object
          description: |
            The settler-signed FulfillmentAuthorization for this payment, returned verbatim as an
            opaque signed document (structurally the canonical FulfillmentAuthorization/v1 declaration at
            https://schemas.atum.xyz/declarations/FulfillmentAuthorization/v1; see also
            `#/components/schemas/FulfillmentAuthorization`). The inner declaration requires
            `version`, `scheme`, `authorization` (the signed EIP-3009 transfer, in `authorization.message_prehash`), `fulfillment_quote_json`,
            and `evidence` (the on-chain authorizeFulfillment transaction). On the wire the settler
            typically wraps that declaration in JSON-LD with `@context`, `type`, and `proof` — those
            envelope fields ride alongside the declaration and MUST be preserved byte-for-byte.

            Present when the settler authorized an originator fulfill. Until the originator
            fulfills, `transactions.fulfillment` is absent.

            The service returns these bytes verbatim and does not re-serialize through a typed
            representation (which would normalize timestamps and reorder JSON-LD envelope fields).
        error:
          $ref: '#/components/schemas/PaymentFailure'
        refund_reason:
          allOf:
            - $ref: '#/components/schemas/PaymentFailure'
          description: |
            Why the settler did not deliver, as it reported when it gave up. Present only when
            `status` is `refunding`, `refund_available` or `refunded`, and absent when the refund
            started without a reason from the settler. `status` decides what to do next: its
            `retry_classification` and `request_id_reusable` describe the settler's error, not
            this payment, and never mean paying again while it is `refunding` or `refund_available`.
        requested_count:
          type: integer
          description: |
            How many settler agents this payment's auction was broadcast to. Accompanies
            `decline_summary` and is present under the same condition. Same meaning and same
            absence rule as on GET /v1/payments/{paymentId}/status: absent means unknown, never
            zero.
          example: 8
        decline_summary:
          type: array
          description: |
            Why the payment drew few or no quotes, carried on the submission response so that a
            `failed` payment explains itself here rather than requiring a follow-up read. A
            payment that ran out its quote deadline reports `NO_QUOTES_RECEIVED` on `error`;
            this is what the settlers actually said.

            Present when `status` is `failed`, alongside `error`. A submission rejected before
            its auction opened is answered as an error response rather than this type and carries
            no breakdown, and GET /v1/payments/{paymentId}/status reports the breakdown in every
            state.

            Same counting rules as GET /v1/payments/{paymentId}/status: every declining agent is
            counted exactly once under its most recent reason, empty means no agent declined,
            absent means the breakdown could not be read. The free-form decline detail is never
            relayed.
          items:
            $ref: '#/components/schemas/DeclineSummaryEntry'

    GetPaymentStatusResponse:
      type: object
      properties:
        payment_id:
          type: string
          description: |
            The payment ID you're checking status for.
          example: "0x761989729fefb4b0cb8b3e6f787301a3878c91e8fba35ed362a079292879f34f"
        status:
          $ref: '#/components/schemas/PaymentStatus'
        transactions:
          $ref: '#/components/schemas/PaymentTransactions'
        updated_at:
          type: string
          format: date-time
          description: When the status was last updated
        quote_id:
          type: string
          description: |
            The winning quote's ID. Present once a quote has been awarded for this payment;
            absent while the payment is still collecting or awarding. Cross-references the
            `quote_id` returned by GET /v1/payments/quote-requests/{quoteRequestId}.
          example: "0x9a3b...e8d4"
        fulfillment_quote:
          type: object
          description: |
            The settler-signed FulfillmentQuote for the winning quote, returned verbatim as an
            opaque signed document (structurally the canonical FulfillmentQuote/v1 declaration at
            https://schemas.atum.xyz/declarations/FulfillmentQuote/v1). Present once a quote has
            been awarded — including after the payment completes and `transactions.fulfillment` is
            populated, since that is precisely when a consumer verifies.

            This is the PREIMAGE of the `quote_hash` committed on-chain in the escrow deposit and
            reserve witnesses. On-chain we commit only the hash, so a quote-selector consumer
            recomputes quote_hash over these bytes and compares it against the on-chain commitment
            to confirm the payment settled against the quote it selected ("trust but verify"), and
            verifies the settler signature over the same bytes.

            quote_hash is canonicalization-based (URDNA2015), so it is stable across JSON
            key-order/whitespace normalization and across JSON string-escaping differences. The
            returned bytes are hash-equivalent to, but not necessarily byte-identical with, what
            the settler emitted (quotes are stored as JSONB, which normalizes on write). The
            gateway still never re-serializes the quote through a typed struct (that renormalizes
            timestamp values and WOULD change quote_hash), so the Go binding exposes it as a raw
            JSON passthrough.
        fulfillment_authorization:
          type: object
          description: |
            The settler-signed FulfillmentAuthorization for this payment, returned verbatim as an
            opaque signed document (structurally the canonical FulfillmentAuthorization/v1 declaration at
            https://schemas.atum.xyz/declarations/FulfillmentAuthorization/v1; see also
            `#/components/schemas/FulfillmentAuthorization`). The inner declaration requires
            `version`, `scheme`, `authorization` (the signed EIP-3009 transfer, in `authorization.message_prehash`), `fulfillment_quote_json`,
            and `evidence` (the on-chain authorizeFulfillment transaction). On the wire the settler
            typically wraps that declaration in JSON-LD with `@context`, `type`, and `proof` — those
            envelope fields ride alongside the declaration and MUST be preserved byte-for-byte.

            Present when the settler authorized an originator fulfill. Until the originator
            fulfills, `transactions.fulfillment` is absent.

            The service returns these bytes verbatim and does not re-serialize through a typed
            representation (which would normalize timestamps and reorder JSON-LD envelope fields).
        error:
          $ref: '#/components/schemas/PaymentFailure'
        refund_reason:
          allOf:
            - $ref: '#/components/schemas/PaymentFailure'
          description: |
            Why the settler did not deliver, as it reported when it gave up. Present only when
            `status` is `refunding`, `refund_available` or `refunded`, and absent when the refund
            started without a reason from the settler. `status` decides what to do next: its
            `retry_classification` and `request_id_reusable` describe the settler's error, not
            this payment, and never mean paying again while it is `refunding` or `refund_available`.
        refund_signature:
          allOf:
            - $ref: '#/components/schemas/RefundSignature'
          description: Present only when `status` is `refund_available`.
        requested_count:
          type: integer
          description: |
            How many settler agents this payment's auction was broadcast to. Absent means
            unknown, never zero.
          example: 8
        decline_summary:
          type: array
          description: |
            Why the payment drew few or no quotes. Read from the same settler reports as the
            quote-request endpoints, keyed by this payment, so a payment that failed on an expired
            quote deadline can say WHY nobody funded it instead of only that nobody did.

            Every declining agent is counted exactly once under its most recent reason. Empty means
            no agent declined against this payment, absent means the breakdown could not be read. A
            payment awarded out of a quote-request batch was bid on at quote time, so its declines
            are keyed to that batch and are read from the batch's status endpoint rather than here.
            As on the quote-request endpoints, the free-form decline detail is never relayed.
          items:
            $ref: '#/components/schemas/DeclineSummaryEntry'

    PaymentFailure:
      type: object
      description: |
        Why a payment failed, or why its settler gave up. As `error` it is present only when
        `status` is `failed`, as `refund_reason` only on the refund statuses, and it is identical
        however you ask about the payment.

        `code` is the stable, machine-readable identity of the failure — branch on it
        rather than on `message`, which is written for a person and may be reworded.
        `docs_url` points at the page describing that code.
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: |
            Public error category in SCREAMING_SNAKE_CASE. Common codes:
            - `SETTLEMENT_FAILED`: the settlement could not be completed
            - `NO_QUOTES_RECEIVED`: no quotes arrived within the auction window
            - `QUOTES_EXPIRED`: quotes arrived but none could be selected
            - `NO_SETTLER_FOR_CORRIDOR`: no settler serves this source and destination pair
            - `INSUFFICIENT_FUNDS`: the paying account held too little of the source token to fund the deposit
            - `MISSING_TOKEN_APPROVAL`: the paying account had not approved Permit2 for enough of the source token
            - `INTERNAL_ERROR`: an unexpected error occurred

            An auction that closes without a usable quote fails the payment here, under
            `status` `failed`, never as an HTTP error on `POST /v1/payments`. These outcomes
            are terminal for the `request_id`, so a genuine re-attempt needs a new one.
          example: "SETTLEMENT_FAILED"
        message:
          type: string
          description: |
            Human-readable description of the failure, for a person reading it. Do not
            branch on this text.
          example: "No quotes received within the auction window"
        domain:
          type: string
          description: |
            Which part of the system reported the failure.
          enum:
            - PAYMENT_GATEWAY
            - SETTLER_GATEWAY
            - SETTLER_AGENT
            - WALLET_ORCHESTRATION
            - VERIFICATION_SERVICE
            - BLOCKCHAIN
            - EXTERNAL_SERVICE
          example: "PAYMENT_GATEWAY"
        docs_url:
          type: string
          format: uri
          description: Link to the documentation page for this public code.
        retry_classification:
          type: string
          description: >-
            What the caller should do next. Absent means the condition has not been
            classified, which is not the same as safe to retry.

            Re-sending the same `request_id` is an idempotent replay and always safe.
            This value is about submitting a new one, which starts a new payment. See
            https://docs.atum.xyz/errors for the value set.
          example: "RECONCILE_THEN_DECIDE"
        request_id_reusable:
          type: boolean
          description: >-
            Whether the caller may re-send the `request_id` this payment was created
            under. On this shape it is almost always false, because a payment exists
            by definition, but it is carried rather than assumed so a caller reads the
            same field here as on a synchronous error. Absent means undetermined,
            which a caller should read as false.
          example: false
        blockchain_context:
          $ref: '#/components/schemas/PaymentBlockchainContext'

    PaymentBlockchainContext:
      type: object
      description: |-
        Where on chain a failed payment failed. Present only when the failure happened
        on chain — an escrow revert, or a fulfillment that could not be delivered — so a
        payment that failed before any transaction was sent carries no context here.
      properties:
        chain_id:
          type: string
          description: CAIP-2 chain identifier
          pattern: ^[a-z0-9]+:[a-zA-Z0-9_-]+$
        transaction_hash:
          type: string
          description: Failed transaction hash
          pattern: ^(0x[a-fA-F0-9]{64}|[1-9A-HJ-NP-Za-km-z]{32,88})$
        block_number:
          type: integer
          description: Block number where error occurred
        contract_address:
          type: string
          description: Contract that caused the error
          pattern: ^(0x[a-fA-F0-9]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$
        revert_reason:
          type: string
          description: Smart contract revert reason
        gas_used:
          type: string
          description: Gas consumed before failure
        estimated_gas_needed:
          type: string
          description: Estimated gas needed for success

    ResolvePaymentResponse:
      type: object
      required:
        - payment_id
      properties:
        payment_id:
          type: string
          description: The payment ID that corresponds to the given request ID
          example: "0x8b73c3c69bb8fe3d512ecc4cf759cc79239f7b179b0ffacaa9a75d522b39400f"

    PaymentTimelineResponse:
      type: object
      description: |
        Step-by-step view of a payment's settlement lifecycle. Includes a route
        summary, a list of steps with timings, and if the payment failed, a
        structured error describing where and why.
      required:
        - payment_id
        - status
        - created_at
        - updated_at
        - steps
      properties:
        payment_id:
          type: string
          example: "0x8b73c3c69bb8fe3d512ecc4cf759cc79239f7b179b0ffacaa9a75d522b39400f"
        status:
          $ref: '#/components/schemas/PaymentStatus'
        transactions:
          $ref: '#/components/schemas/PaymentTransactions'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        total_duration_ms:
          type: integer
          format: int64
          description: Total time from first step to last completed step (only set for terminal states)
        summary:
          $ref: '#/components/schemas/PaymentSummary'
        error:
          $ref: '#/components/schemas/PaymentFailure'
        refund_reason:
          allOf:
            - $ref: '#/components/schemas/PaymentFailure'
          description: |
            Why the settler did not deliver, as it reported when it gave up. Present only when
            `status` is `refunding`, `refund_available` or `refunded`, and absent when the refund
            started without a reason from the settler. `status` decides what to do next: its
            `retry_classification` and `request_id_reusable` describe the settler's error, not
            this payment, and never mean paying again while it is `refunding` or `refund_available`.
        steps:
          type: array
          items:
            $ref: '#/components/schemas/TimelineStep'

    PaymentSummary:
      type: object
      description: Top-level context about the payment (parties, assets, amounts)
      properties:
        source_asset:
          type: string
          description: CAIP-19 identifier of the source asset
          example: "eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
        source_account:
          type: string
          example: "0x742D35cC6634c0532925a3b844Bc9e7595F41360"
        dest_asset:
          type: string
          example: "eip155:42161/erc20:0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
        dest_account:
          type: string
          example: "0x892BB2e4F6b14a2B5b82Ba8d33E5925D42D4431F"
        fulfillment_amount:
          type: string
          description: Raw fulfillment amount in smallest token units
          example: "1000000"
        display_amount:
          type: string
          description: |
            Human-readable formatted amount with symbol, e.g. "1.00 USDC".
            Only set when the source asset's decimals are known via the token registry.
          example: "1.00 USDC"
        max_source_amount:
          type: string
          description: Raw max source amount in smallest token units
          example: "1005000"
        request_id:
          type: string
          example: "req_123456789"

    TimelineStep:
      type: object
      required:
        - name
        - label
        - status
      properties:
        name:
          type: string
          description: Internal name of the step (matches settlement event type)
          example: "BID_AWARDED"
        label:
          type: string
          description: Human-readable label
          example: "Best Bid Selected"
        status:
          type: string
          enum: [completed, in_progress, pending, failed, skipped]
          description: |
            Current status of this step:
            - `completed`: Step finished successfully
            - `in_progress`: Step currently executing
            - `pending`: Step hasn't started yet
            - `failed`: Step errored out
            - `skipped`: Step will never execute because an earlier step failed
        timestamp:
          type: string
          format: date-time
          description: When the step completed (if it has)
        duration_ms:
          type: integer
          format: int64
          description: Time this step took, measured from the previous step
        chain_id:
          type: string
          description: CAIP-2 chain this step happened on (if on-chain)
          example: "eip155:1"
        transaction_hash:
          type: string
          description: Transaction hash associated with this step (if on-chain)
        details:
          type: object
          description: Additional step-specific data (e.g. block_number, settler, reason)
          additionalProperties: true

    ErrorResponse:
      type: object
      description: >-
        Safe, outward-facing error. Derived from an internal error through the
        shared error catalog. The public code identifies the category and the
        message is a curated, safe description.


        A panic is caught by shared middleware that responds
        `{"error": "Internal server error occurred"}` instead, so a 500 is not
        guaranteed to carry this shape.
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Public, machine-readable error category in SCREAMING_SNAKE_CASE.
          pattern: "^[A-Z][A-Z0-9_]*$"
          example: "INVALID_SOURCE_ASSET"
        message:
          type: string
          description: Curated, safe, human-readable message.
          maxLength: 500
          example: "The source asset identifier is not a valid CAIP-19 asset."
        request_id:
          type: string
          description: Correlation id to quote to support to locate the internal error record.
          example: "req_123456789"
        payment_id:
          type: string
          description: >-
            The payment this error was raised against. Absent when the error is not
            about a specific payment.
          example: "0xc7108e200d11580e7e75185991084b42a535af588ba8267cd0d1e7df089e5c9c"
        docs_url:
          type: string
          format: uri
          description: Link to the documentation page for this public code.
        domain:
          type: string
          description: Originating service domain.
          example: "PAYMENT_GATEWAY"
        retry_classification:
          type: string
          description: >-
            What the caller should do next. Absent means the condition has not been
            classified, which is not the same as safe to retry.

            Re-sending the same `request_id` is an idempotent replay and always safe.
            This value is about submitting a new one, which starts a new operation. See
            https://docs.atum.xyz/errors for the value set.
          example: "RECONCILE_THEN_DECIDE"
        request_id_reusable:
          type: boolean
          description: >-
            Whether the caller may re-send this same request_id. True means no payment
            was created for it, so the id is still free. False means a payment exists
            for it, so the id is spent and re-sending only replays this outcome. Absent
            means undetermined, which a caller should read as false. Separate from
            retry_classification, which answers what the caller must change rather than
            whether the id survived.
          example: false
    CreateQuoteRequest:
      type: object
      description: |
        Request body for opening a quote-request batch. Structurally the existing PaymentRequest
        with `sender_auth` omitted (the spend authorization is deferred to the award call); see
        schemas/declarations/PaymentRequest/v1/schema.json.
      required:
        - version
        - request_id
        - source
        - destination
        - fulfillment_amount
        - quote_deadline
        - fulfillment_deadline
        - fulfillment_verifier
        - escrow_contract_address
      properties:
        version:
          type: string
          description: |
            Semver-shaped declaration version (MAJOR.MINOR), locked to major 1 for v1. Producers emit
            the canonical value exported by the bindings' Version constant.
          pattern: '^1\.[0-9]+$'
          example: "1.0"
        request_id:
          type: string
          description: |
            Client-supplied idempotency key for this quote-request. The same request_id from the
            same originator returns the same quote_request_id. Independent of the award-call request_id.
          example: "qr-2026-04-29-001"
        source:
          $ref: '#/components/schemas/OwnedAsset'
        destination:
          type: array
          description: |
            Array of destination assets for the settlement agent to choose from (at least one required, at most 16).
            The ceiling bounds the fan-out one request can buy: every consumer iterates this list.
          minItems: 1
          maxItems: 16
          items:
            $ref: '#/components/schemas/OwnedAsset'
        fulfillment_amount:
          type: string
          description: The exact amount to be received at the destination (smallest unit, e.g. wei or cents).
          example: "100000000"
        max_source_amount:
          type: string
          description: |
            Optional cap on what the originator is willing to spend from source (smallest unit).
            Quotes with source_amount above this are filtered. No cap applied if omitted.
          example: "101000000"
        quote_deadline:
          type: string
          format: date-time
          description: |
            Required. End of the collection window. After this point no new quotes are accepted.
            The gateway injects no default and never mutates the originator-supplied body, so the
            value is carried through verbatim to the award call. It must be supplied and must be in
            the future. Must be strictly earlier than fulfillment_deadline.

            Keep this window short. A settler holds its quoted price for a limited period of its
            own choosing, and the gateway selects only once the window has closed, so a deadline
            set beyond that hold leaves no quote still awardable and the request is declined with
            QUOTE_WINDOW_TOO_LONG. That hold is set by each settler and is not part of this
            contract, so treat 60 seconds as a practical upper bound and prefer a shorter window
            where your integration allows.
          example: "2026-04-29T12:00:03Z"
        fulfillment_deadline:
          type: string
          format: date-time
          description: |
            Required. The time by which the payout to the recipient must be mined on the
            destination chain. If no payout is mined by then, your escrowed funds are refunded.
            The payout does not have to be final by then: `completed`
            follows once the destination chain judges it final. The gateway injects no default and
            never mutates the originator-supplied body, so the value is carried through verbatim to
            the award call. It must be supplied and must be in the future. Must be strictly later
            than quote_deadline.
          example: "2026-04-29T12:30:00Z"
        settler_auth_required:
          type: object
          description: Policy requirements for settler authentication. Keys are policy names, values indicate if required.
          additionalProperties:
            type: boolean
        originator_auth:
          $ref: '#/components/schemas/VerifiableCredentialAuth'
        quote_selector:
          type: string
          description: |
            Wallet address or public key of a trusted service that auto-selects the best rate.
            Leave empty to use the default selector.
          example: "0x742D35cC6634c0532925a3b844Bc9e7595F41360"
        fulfillment_verifier:
          type: object
          description: |
            The verification service that confirms the payment was delivered before the escrow
            releases the source funds, and the account it signs with. Required on every chain:
            the gateway's `/v1/defaults` response supplies it for each chain.
          required:
            - account
            - endpoint
          properties:
            account:
              type: string
              description: The wallet address or public key of the verification service
              example: "0x892BB2e4F6b14a2B5b82Ba8d33E5925D42D4431F"
            endpoint:
              type: string
              format: uri
              description: |
                Origin of the fulfillment verifier service, with no path — the caller
                appends the verifier's own API paths. The gateway's `/v1/defaults` response
                supplies the default fulfillment verifier for each chain.
              example: "https://veri-fill.production-testnet.atum.xyz"
        escrow_contract_address:
          type: string
          description: |
            Escrow contract on the source chain that holds the source funds until proof of
            fulfillment has been verified. Required on every chain: the gateway's `/v1/defaults`
            response supplies it for each chain (`escrow_contract`).
          example: "0x742D35cC6634c0532925a3b844Bc9e7595F41360"
        fulfillment_proxy:
          type: string
          description: Optional fulfillment-proxy contract address on the destination chain. Leave empty to use the default.
          example: "0x892BB2e4F6b14a2B5b82Ba8d33E5925D42D4431F"
        settler_requirements:
          type: object
          description: |
            Optional settler filtering. If whitelist is present, only whitelisted settlers may win.
            If blacklist is present, blacklisted settlers are excluded. Both can be specified;
            blacklist takes precedence (a settler in both is rejected).
          properties:
            whitelist:
              type: array
              description: Settler DIDs permitted to fulfill this request (W3C DID format). If present, only these may win.
              minItems: 1
              maxItems: 100
              uniqueItems: true
              items:
                type: string
                pattern: "^did:[a-z][a-z0-9]*:[a-zA-Z0-9._:%-]+$"
              example:
                - "did:pkh:eip155:1:0x742D35cC6634c0532925a3b844Bc9e7595F41360"
            blacklist:
              type: array
              description: Settler DIDs excluded from fulfilling this request (W3C DID format).
              minItems: 1
              maxItems: 100
              uniqueItems: true
              items:
                type: string
                pattern: "^did:[a-z][a-z0-9]*:[a-zA-Z0-9._:%-]+$"
              example:
                - "did:pkh:eip155:1:0x892bb2E4F6b14a2B5b82bA8D33e5925d42d4432f"
        "@context":
          type: array
          description: |
            Optional JSON-LD context URLs — present when the originator wraps the request in a W3C
            Data Integrity envelope so a downstream verifier can recover the signer identity.
          items:
            type: string
        proof:
          $ref: '#/components/schemas/DataIntegrityProof'
        verifiableCredential:
          type: array
          description: Optional document-level W3C Verifiable Credentials (e.g. KnownToAtum about the request producer).
          items:
            $ref: '#/components/schemas/VerifiableCredential'

    DataIntegrityProof:
      type: object
      description: W3C Data Integrity proof conforming to the Data Integrity 1.0 specification. Which of jws or proofValue is required depends on the cryptosuite named in type, and that pairing is checked where the proof is verified rather than by this schema, so a document can satisfy the schema and still be refused at verification.
      required:
        - type
        - created
        - verificationMethod
        - proofPurpose
      properties:
        type:
          type: string
          description: Proof type identifier. ECDSA-secp256k1 (recoverable, EVM-compatible) for did:pkh:eip155:* signers; Ed25519 for did:pkh:solana:* signers.
          example: EcdsaSecp256k1RecoverySignature2020
        created:
          type: string
          format: date-time
          description: 'ISO 8601 timestamp when the proof was created. Canonicalize the value exactly as it appears in the raw JSON: parsing it into a date-time and re-serializing can change the spelling (Z versus +00:00), and a different spelling canonicalizes to different bytes, so the signature no longer verifies.'
          example: "2026-04-29T12:00:00Z"
        verificationMethod:
          type: string
          description: DID URL identifying the verification method, e.g., 'did:pkh:eip155:1:0x...#blockchainAccountId' for ECDSA or 'did:pkh:solana:<chain>:<addr>#SolanaMethod2021' for Ed25519 on Solana.
          example: did:pkh:eip155:42161:0xabc...#blockchainAccountId
        proofPurpose:
          type: string
          description: Purpose of the proof (e.g., assertionMethod, authentication).
          example: assertionMethod
        jws:
          type: string
          description: Detached JWS signature in <base64url(header)>..<base64url(sig)> form, header {alg:ES256K-R, b64:false, crit:[b64]}. Required at runtime for EcdsaSecp256k1RecoverySignature2020.
        proofValue:
          type: string
          description: Multibase-encoded raw signature bytes. Required at runtime for Ed25519Signature2020; mutually exclusive with jws in practice.

    Quote:
      type: object
      description: One collected quote — the content-hash identifier plus the verbatim settler-signed FulfillmentQuote.
      required:
        - quote_id
        - fulfillment_quote
      properties:
        quote_id:
          type: string
          description: |
            Canonical content-hash of the signed quote bytes; identifies the quote server-side at
            award time. Provided as a convenience — the gateway re-derives it from
            bid_award.fulfillment_quote_json.
          example: "0x4e7f...c2a1"
        fulfillment_quote:
          type: object
          description: |
            The settler-signed FulfillmentQuote (structurally the canonical FulfillmentQuote/v1
            declaration at https://schemas.atum.xyz/declarations/FulfillmentQuote/v1), returned
            verbatim as an opaque signed document. A client recomputes quote_hash over the returned
            bytes and verifies the settler signature, then re-embeds them into
            bid_award.fulfillment_quote_json at award. quote_hash is canonicalization-based
            (URDNA2015), so it is stable across JSON key-order/whitespace normalization. The
            returned bytes are hash-equivalent to, but not necessarily byte-identical with, what the
            settler emitted (quotes are stored as JSONB, which normalizes on write). The gateway
            still never re-serializes the quote through a typed struct (that renormalizes timestamp
            values and WOULD change quote_hash), so the Go binding exposes it as a raw JSON passthrough.

    AwardedQuote:
      type: object
      description: A collected quote in the status response, annotated with its award linkage.
      required:
        - quote_id
        - fulfillment_quote
      properties:
        quote_id:
          type: string
          example: "0x9a3b...e8d4"
        fulfillment_quote:
          type: object
          description: |
            The settler-signed FulfillmentQuote (structurally the canonical FulfillmentQuote/v1
            declaration at https://schemas.atum.xyz/declarations/FulfillmentQuote/v1), returned
            verbatim as an opaque signed document. A client recomputes quote_hash over the returned
            bytes and verifies the settler signature, then re-embeds them into
            bid_award.fulfillment_quote_json at award. quote_hash is canonicalization-based
            (URDNA2015), so it is stable across JSON key-order/whitespace normalization. The
            returned bytes are hash-equivalent to, but not necessarily byte-identical with, what the
            settler emitted (quotes are stored as JSONB, which normalizes on write). The gateway
            still never re-serializes the quote through a typed struct (that renormalizes timestamp
            values and WOULD change quote_hash), so the Go binding exposes it as a raw JSON passthrough.
        awarded_payment_id:
          type: string
          nullable: true
          description: |
            payment_id if this quote was awarded; null otherwise. Under MVP single-award, at most
            one quote per batch carries a non-null value.
          example: "0x761989729fefb4b0cb8b3e6f787301a3878c91e8fba35ed362a079292879f34f"

    AwardedPayment:
      type: object
      description: A (quote_id, payment_id) pair for an awarded quote in a batch.
      required:
        - quote_id
        - payment_id
      properties:
        quote_id:
          type: string
          example: "0x9a3b...e8d4"
        payment_id:
          type: string
          example: "0x761989729fefb4b0cb8b3e6f787301a3878c91e8fba35ed362a079292879f34f"

    QuoteRequestResponse:
      type: object
      description: |
        Synchronous response to POST /v1/payments/quote-requests. Self-contained — the corridor
        fields are echoed at the response root so a drop-recovery client can build the award call
        without retaining the original request body.

        The corridor echoed here describes the batch you actually receive. On an idempotent
        replay that is the ORIGINAL batch's corridor and window, which may differ from what you
        just sent in the ways a retry is allowed to differ (the deadlines, and address casing).
      required:
        - quote_request_id
        - status
        - idempotent_replay
      properties:
        quote_request_id:
          type: string
          description: Gateway-generated resource ID for the batch, used in subsequent status reads and awards.
          example: "qr_a1b2c3d4-5678-90ef-1234-567890abcdef"
        status:
          type: string
          enum:
            - collecting
            - ready
          description: |
            Collection-phase outcome of the create call:
            - `ready` — collection complete; `quotes` populated. If no settler bid, this is still
              `ready` with an empty `quotes` array (a successful "no quotes available" result —
              distinct from `expired`, which only applies to collected quotes that later lapse).
            - `collecting` — the sync wait cap fired before the quote deadline; poll the status endpoint for quotes.
            The `awarded` and `expired` lifecycle states are observed only via the status endpoint, not here.
          example: "ready"
        idempotent_replay:
          type: boolean
          description: |
            Whether this response describes a batch that already existed, rather than one opened
            by this request. `true` means the `request_id` had been used before and you are being
            handed the ORIGINAL batch — no second batch was opened and no second broadcast went
            out to settlement agents.

            **Re-attempting a quote-request.** Re-submit the same request and you get the same
            batch back. You may re-send the original bytes unchanged: `quote_deadline` bounds the
            collection window and is short, so it will usually have expired by the time you
            retry, and an expired deadline on a re-submission is not an error — the request is
            resolved onto the batch that already exists rather than used to open one.
            Re-signing with fresh deadlines is equally fine and returns the same batch.

            The window is NOT extended either way: it belongs to the batch, and `quote_deadline`
            in this response is the batch's own. Read `status` to see whether collection is
            still running.

            What you must not change under one `request_id` is the corridor's economics —
            accounts, assets, or amounts — which are rejected with 409
            IDEMPOTENCY_TERMS_MISMATCH rather than resolved onto the first batch. A genuinely
            different corridor needs a new `request_id`.

            Present on every response, `false` for a newly opened batch. A response without the
            field is from a gateway predating it, not a newly opened batch.
        source:
          $ref: '#/components/schemas/OwnedAsset'
        destination:
          type: array
          items:
            $ref: '#/components/schemas/OwnedAsset'
        fulfillment_amount:
          type: string
          example: "100000000"
        max_source_amount:
          type: string
          example: "101000000"
        fulfillment_deadline:
          type: string
          format: date-time
          example: "2026-04-29T12:30:00Z"
        quote_deadline:
          type: string
          format: date-time
          example: "2026-04-29T12:00:03Z"
        quotes:
          type: array
          description: Collected quotes. Present when status is `ready` — an empty array if no settler bid.
          items:
            $ref: '#/components/schemas/Quote'
        requested_count:
          type: integer
          description: |
            How many agents the request was broadcast to, so silence is distinguishable from a
            decline without a second call. Same meaning and same absence rule as on the status
            endpoint: absent means unknown, never zero.
          example: 8
        decline_summary:
          type: array
          description: |
            Why the request drew few or no quotes, carried here so that a `ready` response with an
            empty `quotes` array explains itself rather than requiring a follow-up read.

            Same counting rules as the status endpoint: every declining agent counted exactly once
            under its most recent reason, empty when nobody declined, absent when the detail could not
            be read. Provisional while `status` is `collecting`, because agents are still responding.
          items:
            $ref: '#/components/schemas/DeclineSummaryEntry'

    QuoteRequestAccepted:
      type: object
      description: |
        Asynchronous (202) response to POST /v1/payments/quote-requests. Returns the batch handle
        plus the echoed corridor; quotes are retrieved via the status endpoint.

        The corridor echoed here describes the batch you actually receive. On an idempotent
        replay that is the ORIGINAL batch's corridor and window, which may differ from what you
        just sent in the ways a retry is allowed to differ (the deadlines, and address casing).
      required:
        - quote_request_id
        - status
        - idempotent_replay
      properties:
        quote_request_id:
          type: string
          example: "qr_a1b2c3d4-5678-90ef-1234-567890abcdef"
        status:
          type: string
          enum:
            - collecting
          description: |
            Always `collecting` — a constant on this response, not a report of the batch's state.
            On an idempotent replay the batch's window may already have closed; read
            GET /v1/payments/quote-requests/{quoteRequestId} for its actual state.
          example: "collecting"
        idempotent_replay:
          type: boolean
          description: |
            Whether this response describes a batch that already existed, rather than one opened
            by this request. `true` means the `request_id` had been used before and you are being
            handed the ORIGINAL batch — no second batch was opened and no second broadcast went
            out to settlement agents.

            The idempotency contract is the same as on the synchronous (200) response: a
            re-submission may carry expired deadlines and is resolved onto the existing batch
            rather than rejected, the collection window is the batch's own and is not extended,
            and differing economics are rejected with 409 IDEMPOTENCY_TERMS_MISMATCH rather than
            collapsed onto the first batch.

            Present on every response, `false` for a newly opened batch. A response without the
            field is from a gateway predating it, not a newly opened batch.
        source:
          $ref: '#/components/schemas/OwnedAsset'
        destination:
          type: array
          items:
            $ref: '#/components/schemas/OwnedAsset'
        fulfillment_amount:
          type: string
          example: "100000000"
        max_source_amount:
          type: string
          example: "101000000"
        fulfillment_deadline:
          type: string
          format: date-time
          example: "2026-04-29T12:30:00Z"
        quote_deadline:
          type: string
          format: date-time
          example: "2026-04-29T12:00:03Z"

    QuoteRequestStatusResponse:
      type: object
      description: |
        Response to GET /v1/payments/quote-requests/{quoteRequestId}. The `status` enum describes
        the quote-request batch lifecycle and is disjoint from the payment-status enum.
      required:
        - quote_request_id
        - status
      properties:
        quote_request_id:
          type: string
          example: "qr_a1b2c3d4-5678-90ef-1234-567890abcdef"
        status:
          type: string
          enum:
            - collecting
            - ready
            - awarded
            - expired
          description: |
            Derived batch lifecycle, computed at read time (not a stored state machine). Disjoint
            from the payment-status enum returned by the award and payment-status endpoints.
            - `collecting` — collection window still open; `quotes` lists those collected so far
              (a quote is awardable from arrival, by its own `award_deadline`; more may arrive until
              `collection_close`).
            - `ready` — collection complete; none awarded yet; either at least one quote is still
              within its `award_deadline`, or no settler bid (empty `quotes` array — the successful
              "no quotes available" result).
            - `awarded` — a quote produced a payment row; no further awards accepted (MVP).
            - `expired` — collection closed, nothing awarded, and every collected quote is now past
              its `award_deadline` ("quotes lapsed"). An empty batch is `ready`, not `expired` — the
              two are deliberately distinct ("no quotes available" vs "quotes lapsed").
          example: "awarded"
        quotes:
          type: array
          description: Collected quotes with award linkage — those collected so far while `collecting`, the full set once the window closes.
          items:
            $ref: '#/components/schemas/AwardedQuote'
        payments:
          type: array
          description: Flat list of awarded (quote_id, payment_id) pairs. At most one entry under MVP single-award.
          items:
            $ref: '#/components/schemas/AwardedPayment'
        requested_count:
          type: integer
          description: |
            How many agents the request was broadcast to. The only auction count that is not
            derivable from the rest of this response:

            - quoted = `quotes` length
            - declined = sum of `decline_summary[].count`
            - participated = quoted + declined
            - silent = `requested_count` - participated

            Silence and a decline are different signals, which is why the denominator is surfaced
            rather than left implicit.

            ABSENT when the number is unknown, which happens when the broadcast count was never
            recorded or when the auction detail could not be read. Absence means unknown, never zero,
            so `silent` is derivable only when this field is present.
          example: 8
        decline_summary:
          type: array
          description: |
            Why the request drew few or no quotes, so a caller can tell "nobody can fund this right
            now" from "my request was malformed".

            EXHAUSTIVE over agents: every agent that declined is counted exactly once, under its most
            recent reason, so the counts sum to the number of agents that declined. An agent that
            declined more than once with different reasons is counted once, not once per reason.

            Empty means nobody declined. ABSENT means the auction detail could not be read, so the
            breakdown is unknown. While `status` is `collecting` it is provisional, because agents are
            still responding.

            The free-form decline detail is never relayed, because that detail carries an agent's
            balances and would let a caller map inventory by polling cheap quote-requests across
            corridors.
          items:
            $ref: '#/components/schemas/DeclineSummaryEntry'

    DeclineSummaryEntry:
      type: object
      required:
        - reason
        - count
      properties:
        reason:
          $ref: '#/components/schemas/DeclineReason'
        count:
          type: integer
          description: |
            Agents whose most recent decline reason was this one. Counts agents, never rows, and an
            agent appears under one reason only.
          example: 4
        retry_classification:
          type: string
          description: |
            What would have to change for a settler giving this reason to submit a price quote,
            drawn from the same closed set as the `retry_classification` on an error response so
            a caller reads one vocabulary.

            It describes the decline only. The authoritative instruction for the payment is the
            `retry_classification` on its own error response: a payment can fail for a reason no
            settler named, and it can succeed while some settlers declined.

            Optional, and a pattern-constrained string for the same reason `DeclineReason` is.
          pattern: "^[A-Z][A-Z0-9_]*$"
          example: "RETRY_AFTER_DELAY"
        docs_url:
          type: string
          format: uri
          description: |
            Link to the documentation for this reason. Absent rather than empty when no page is
            published, so a reader never follows a link to the site root.
          example: "https://docs.atum.xyz/decline-reasons#insufficient-liquidity"

    DeclineReason:
      type: string
      description: |
        A settler's reason for not bidding, projected from its internal reason code through
        the shared decline catalog (`apis/decline/v1/catalog.json`), which is the single
        source of truth for the reason set. Several internal codes may map to one public
        reason.

        Deliberately a pattern-constrained string rather than a closed enum. The set grows
        whenever a settler gains a cause worth naming, and a consumer whose generated client
        closes the set rejects the whole response on a value it has not seen. Treat an
        unrecognised value as `OTHER`.

        `OTHER` covers a reason whose detail is settler-authored free text, and any reason
        this gateway does not recognise. Both are counted so the summary stays exhaustive,
        without relaying text we neither author nor validate.
      pattern: "^[A-Z][A-Z0-9_]*$"
      example: "INSUFFICIENT_LIQUIDITY"

    AwardRequest:
      type: object
      description: |
        Request body for POST /v1/payments/awards. Carries the two originator-signed artifacts:
        `sender_auth` (Permit2 deposit authorization) and a fully-formed `bid_award` declaration.
        The awarded quote is derived server-side from bid_award.fulfillment_quote_json — no
        explicit quote_id on the wire.
      required:
        - request_id
        - sender_auth
        - bid_award
      properties:
        request_id:
          type: string
          description: Client-supplied idempotency key for this award call. Independent of the quote-request's request_id.
          example: "award-2026-04-29-001"
        sender_auth:
          $ref: '#/components/schemas/SenderAuth'
        bid_award:
          $ref: '#/components/schemas/BidAward'

    BidAward:
      type: object
      description: |
        Fully-formed, originator-signed bid award. Mirrors schemas/declarations/BidAward/v1/schema.json.
        `authorization` carries the Escrow reserve-witness signature naming the chosen settler;
        `fulfillment_quote_json` is the verbatim settler-signed quote string received in the quote
        response (carrying the settler's proof).
      required:
        - version
        - authorization
        - fulfillment_quote_json
      properties:
        version:
          type: string
          pattern: '^1\.[0-9]+$'
          description: |
            Semver-shaped declaration version (MAJOR.MINOR), locked to major 1 for v1. Producers emit
            the canonical value exported by the bindings' Version constant.
          example: "1.0"
        authorization:
          $ref: '#/components/schemas/SignedMessage'
        fulfillment_quote_json:
          type: string
          description: |
            The settler-signed FulfillmentQuote received in the quote response, forwarded verbatim.
            Verification is canonicalization-based — the settler's W3C Data Integrity proof is checked
            over the canonicalized form, and `quote_id` is derived as the canonical content-hash — so a
            JSON decode/re-encode that only changes key order or whitespace does not invalidate it.
            Clients SHOULD still forward the received bytes as-is rather than rebuild the object; the
            SDK helpers do this and also expose settler-proof verification.
        "@context":
          type: array
          description: Optional JSON-LD context URLs when the award is wrapped in a W3C Data Integrity envelope.
          items:
            type: string
        proof:
          $ref: '#/components/schemas/DataIntegrityProof'
        verifiableCredential:
          type: array
          description: Optional W3C Verifiable Credentials attesting the award producer.
          items:
            $ref: '#/components/schemas/VerifiableCredential'

    AwardResponse:
      type: object
      description: |
        Synchronous response to POST /v1/payments/awards. The `status` field describes the payment
        lifecycle. Note there are two distinct status surfaces for a Quote-API payment, with
        different vocabularies: (1) this award response (`awarding`/`completed`/…), and
        (2) the separate GET /v1/payments/{paymentId}/status endpoint you poll afterward, which
        reports the same payment under its own values (an in-progress payment reads as `pending`
        there). Both are disjoint from the quote-request batch status on the quote-request endpoints.
      required:
        - payment_id
        - status
      properties:
        payment_id:
          type: string
          example: "0x761989729fefb4b0cb8b3e6f787301a3878c91e8fba35ed362a079292879f34f"
        status:
          type: string
          enum:
            - awarding
            - completed
            - failed
            - cancelled
          description: |
            Payment lifecycle status on the award response:
            - `completed` — settlement finished within the sync wait.
            - `awarding` — settlement still in progress when the sync cap fired (or on wait=false);
              poll GET /v1/payments/{paymentId}/status.
            - `failed` — settlement reached a terminal failure (e.g. the settler could not fulfill, or
              an on-chain step was rejected).
            - `cancelled` — the payment was terminated before settlement completed and will not proceed.
            `failed` and `cancelled` are terminal states surfaced here only when they occur within the
            sync wait; otherwise the response is `awarding` and the terminal state is read from the
            payment-status endpoint.
          example: "completed"
        fulfillment_authorization:
          type: object
          description: |
            The settler-signed FulfillmentAuthorization for this payment, returned verbatim as an
            opaque signed document (structurally the canonical FulfillmentAuthorization/v1 declaration at
            https://schemas.atum.xyz/declarations/FulfillmentAuthorization/v1; see also
            `#/components/schemas/FulfillmentAuthorization`). The inner declaration requires
            `version`, `scheme`, `authorization` (the signed EIP-3009 transfer, in `authorization.message_prehash`), `fulfillment_quote_json`,
            and `evidence` (the on-chain authorizeFulfillment transaction). On the wire the settler
            typically wraps that declaration in JSON-LD with `@context`, `type`, and `proof` — those
            envelope fields ride alongside the declaration and MUST be preserved byte-for-byte.

            Present when the settler authorized an originator fulfill within the sync wait.

            The service returns these bytes verbatim and does not re-serialize through a typed
            representation (which would normalize timestamps and reorder JSON-LD envelope fields).

    AwardAccepted:
      type: object
      description: Asynchronous (202) response to POST /v1/payments/awards — just the payment handle.
      required:
        - payment_id
        - status
      properties:
        payment_id:
          type: string
          example: "0x761989729fefb4b0cb8b3e6f787301a3878c91e8fba35ed362a079292879f34f"
        status:
          type: string
          enum:
            - awarding
          description: Always `awarding` — settlement is in progress server-side.
          example: "awarding"

    ChainDefaults:
      type: object
      description: |
        The addresses for one chain. Optional fields appear only where they apply to that
        chain; an absent optional field is not an error.
      required:
        - chain_id
        - quote_selector
        - escrow_contract
        - fulfillment_proxy
        - fulfillment_verifier
      properties:
        chain_id:
          type: string
          description: CAIP-2 identifier of the chain these defaults describe, normalised to lower case.
          example: "eip155:84532"
        quote_selector:
          type: string
          description: >-
            The account named as the reserver in the deposit authorization. Sign against
            this exact value; a deposit reserved by anyone else is rejected.
          example: "0xd0f080E23F95571D26eEb1FAD24a5F3d66835195"
        escrow_contract:
          type: string
          description: >-
            The escrow the deposit is made into, and the spender of the token approval.
            Empty when the chain is not fully configured.
          example: "0xa61a0C025943Aa79B73D8D07E3aDbEe1873738b4"
        fulfillment_proxy:
          type: string
          description: >-
            The contract that pays the receiver. Read this from the DESTINATION chain's
            defaults, not the source chain's. Empty when the chain is not fully configured.
          example: "0x09A5a0d6955E5394A661Cd9E7007076fa63B4158"
        fulfillment_verifier:
          type: object
          description: The service that attests settlement, and the account it signs with.
          required:
            - account
            - endpoint
          properties:
            account:
              type: string
              description: >-
                The account named as the releaser in the deposit authorization. Sign
                against this exact value.
              example: "0x27050EE47befC43F4dF7807a7AA8073039e5fa89"
            endpoint:
              type: string
              format: uri
              description: >-
                Base URL of the fulfillment verifier serving this chain.
              example: "https://veri-fill.example.com"
        permit2_contract:
          type: string
          minLength: 1
          description: >-
            The Permit2 this chain's escrow verifies against, sent only when it is not the
            canonical deployment. When absent, use the canonical Permit2 address for the
            chain. EVM and Tron only.
          example: "0x000000000022D473030F116dDEE9F6B43aC78BA3"
        tokens:
          type: array
          description: >-
            Tokens this chain's escrow accepts for deposit. Absent when the gateway has no
            listing for the chain, which does not mean no token is accepted.
          items:
            type: object
            required:
              - symbol
              - address
              - decimals
            properties:
              symbol:
                type: string
                example: "USDC"
              address:
                type: string
                description: Token contract address, in the chain's native address format.
                example: "0x036cbd53842c5426634e7929541ec2318f3dcf7e"
              decimals:
                type: integer
                description: Decimal places, for converting a human amount to base units.
                example: 6
        svm_signature_cluster_id:
          type: string
          description: >-
            Solana only. The cluster the escrow's signing domain is bound to, needed to
            build the deposit hash. Absent for EVM and Tron.
          example: "devnet"
        svm_signature_domain_version:
          type: integer
          minimum: 1
          description: >-
            Solana only. The escrow's signature domain version, which the deposit hash commits
            to. Absent for EVM and Tron.
          example: 5
        deposit_request_hash_version:
          type: integer
          minimum: 1
          description: >-
            The depositRequestHash version to sign for a deposit from this chain: 1 is
            keccak256 of the request_id, 2 is the hash of the payment terms, computed over the
            request body exactly as it is then posted. Absent means 1. Kept for clients that
            predate `deposit_request_hash_versions`, which a client should read instead: a deposit
            signed with version 1 is still accepted unless that list omits 1. It stays 2 once
            version 1 is no longer accepted, so a client that reads only this member keeps signing
            version 2.
          example: 2
        deposit_request_hash_versions:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: integer
            minimum: 1
          description: >-
            The depositRequestHash versions a deposit from this chain may be signed with,
            ascending: `[1]` before version 2, `[1, 2]` once the gateway publishes 2 in
            `deposit_request_hash_version`, and `[2]` once it no longer accepts version 1. A
            merchant lists exactly these in an x402 or MPP challenge. Absent means `[1, 2]` when
            `deposit_request_hash_version` is 2 and `[1]` otherwise, which is what a gateway that
            predates this member implies. Ignore a version you do not know.
          example: [1, 2]

    GetDefaultsResult:
      description: >-
        Either one chain's defaults or every chain keyed by CAIP-2 chain id, depending on
        whether `chain_id` was supplied. A top-level `chain_id` identifies the first.
      oneOf:
        - $ref: '#/components/schemas/ChainDefaults'
        - $ref: '#/components/schemas/ChainDefaultsByChain'

    ChainDefaultsByChain:
      type: object
      description: >-
        Defaults for every chain the gateway serves, keyed by CAIP-2 chain id. Each key
        repeats the `chain_id` of the value it maps to.
      additionalProperties:
        $ref: '#/components/schemas/ChainDefaults'
      example:
        eip155:84532:
          chain_id: "eip155:84532"
          quote_selector: "0xd0f080E23F95571D26eEb1FAD24a5F3d66835195"
          escrow_contract: "0xa61a0C025943Aa79B73D8D07E3aDbEe1873738b4"
          fulfillment_proxy: "0x09A5a0d6955E5394A661Cd9E7007076fa63B4158"
          fulfillment_verifier:
            account: "0x27050EE47befC43F4dF7807a7AA8073039e5fa89"
            endpoint: "https://veri-fill.example.com"
