openapi: 3.1.0
info:
  title: x402 Facilitator API (atum-escrow)
  version: 1.0.0
  description: |
    The standard x402 v2 facilitator API as served for the atum-escrow scheme. A resource server calls /verify then /settle to validate and settle a payment credential, and /supported to discover which scheme/network/token combinations the facilitator can handle. The atum-escrow request/response shapes are defined by referenced JSON Schemas; this document specifies the endpoints and the atum-escrow-specific behavior. Any facilitator that serves this contract is interchangeable behind it.
servers:
  - url: https://payment-gw.production-mainnet.atum.xyz/x402/v1
    description: Mainnet
  - url: https://payment-gw.production-testnet.atum.xyz/x402/v1
    description: Testnet
paths:
  /verify:
    post:
      operationId: verify
      summary: Validate a payment credential against a requirement.
      description: |
        Checks the credential against the selected requirement: the PaymentRequestEnvelope identity binding (a holder-signed verifiable presentation whose proofPurpose is 'authentication', whose proof.challenge equals the request's request_hash, whose proof.domain is the network-wide verifier id, and whose holder equals source.account), the Permit2 sender authorization, escrow terms, that destination and fulfillment amount equal the requirement's, and that the signed source cap does not exceed the advertised amount. Does not move funds.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FacilitatorRequest"
      responses:
        "200":
          description: Verification result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VerifyResponse"
  /settle:
    post:
      operationId: settle
      summary: Submit a validated payment for settlement.
      description: |
        Submits the request to the Atum network for settlement and resolves synchronously within the requirement's maxTimeoutSeconds: once the payout to the recipient is on chain, or once it is final when the facilitator is configured to wait for that. Returns the settlement transaction and network; extensions.atum.state says whether the payment is finalizing (on chain, not yet final) or completed. Asynchronous settlement beyond the synchronous window is a deferred extension.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FacilitatorRequest"
      responses:
        "200":
          description: The synchronous settlement result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SettleResponse"
  /supported:
    get:
      operationId: supported
      summary: List the scheme/network/token combinations the facilitator handles.
      parameters:
        - name: chain
          in: query
          required: false
          description: Filter to a single CAIP-2 chain.
          schema:
            type: string
        - name: token
          in: query
          required: false
          description: Filter to a token by symbol or CAIP-19 asset id.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
      responses:
        "200":
          description: Supported kinds, settlement signers, and extensions.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SupportedResponse"
components:
  schemas:
    FacilitatorRequest:
      type: object
      description: The shared request body for /verify and /settle.
      required:
        - x402Version
        - paymentPayload
        - paymentRequirements
      properties:
        x402Version:
          type: integer
          const: 2
        paymentPayload:
          description: |
            The payer's signed credential. Its payload.paymentRequest conforms to the canonical PaymentRequest declaration and carries the PaymentRequestEnvelope (PRE) identity binding.
          $ref: "#/components/schemas/AtumEscrowPayload"
        paymentRequirements:
          description: The single requirement the payer selected from the 402.
          $ref: "#/components/schemas/PaymentRequirements"
    PaymentRequirements:
      type: object
      description: |
        One atum-escrow payment requirement (a 402 accepts[] entry). payTo is the source-chain escrow contract, not the payee; the payee is extra.atum.destination.address.
      required:
        - scheme
        - network
        - asset
        - payTo
        - amount
        - maxTimeoutSeconds
        - extra
      properties:
        scheme:
          type: string
          const: atum-escrow
        network:
          type: string
          description: CAIP-2 source chain id.
        asset:
          type: string
          description: Source token contract address.
        payTo:
          type: string
          description: Source-chain escrow contract address.
        amount:
          type: string
          description: Advisory source spend cap in atomic units.
        maxTimeoutSeconds:
          type: integer
          minimum: 1
          description: Relative bound on the synchronous settlement hold.
        extra:
          type: object
          required:
            - atum
          properties:
            atum:
              $ref: "#/components/schemas/AtumEscrowExtra"
    AtumEscrowExtra:
      title: AtumEscrowExtra
      description: "The `extra.atum` object carried inside an atum-escrow x402 PaymentRequirements entry (accepts[]): the merchant's receive-side plus the contract/role addresses and deadline budgets. Scheme-specific data the standard x402 `extra` bag treats as opaque, so it is owned here and shared by all role mechanisms. Addresses are chain-general: an EVM `0x`-hex address (20 bytes) or a base58-encoded address (Solana/Tron), per the field's CAIP-2 chain."
      type: object
      additionalProperties: false
      required:
        - destination
        - fulfillmentAmount
        - escrow
        - fulfillmentProxy
        - reserver
        - releaser
        - fulfillmentVerifierEndpoint
        - quoteDeadlineSeconds
        - fulfillmentDeadlineSeconds
      properties:
        destination:
          type: object
          additionalProperties: false
          description: Where the merchant receives (CAIP-2 chain, token, address).
          required:
            - network
            - asset
            - address
          properties:
            network:
              type: string
              pattern: ^[-a-z0-9]+:.+$
              description: CAIP-2 destination chain id (e.g. eip155:42161).
            asset:
              type: string
              pattern: ^(0x[0-9a-fA-F]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$
              description: Destination token contract address (EVM hex or base58, per the destination chain).
            address:
              type: string
              pattern: ^(0x[0-9a-fA-F]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$
              description: Merchant receive address (EVM hex or base58, per the destination chain).
        fulfillmentAmount:
          type: string
          pattern: ^[0-9]+$
          description: Exact amount the merchant receives, in atomic token units.
        escrow:
          type: string
          pattern: ^(0x[0-9a-fA-F]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$
          description: Source-chain escrow contract (the x402 payTo); EVM hex or base58, per the source chain.
        fulfillmentProxy:
          type: string
          pattern: ^(0x[0-9a-fA-F]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$
          description: Destination-chain fulfillment proxy contract (EVM hex or base58, per the destination chain).
        reserver:
          type: string
          pattern: ^(0x[0-9a-fA-F]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$
          description: Atum reserver role address (escrow deposit witness); EVM hex or base58, per the source chain.
        releaser:
          type: string
          pattern: ^(0x[0-9a-fA-F]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$
          description: Atum releaser role address (escrow deposit witness); EVM hex or base58, per the source chain.
        fulfillmentVerifierEndpoint:
          type: string
          format: uri
          description: Source-chain fulfillment-verifier endpoint the payment request carries. The verifier account and the quote_selector are the releaser and reserver respectively (the network derives the deposit witness roles from them), so only the endpoint is not otherwise present in this object.
        quoteDeadlineSeconds:
          type: integer
          minimum: 1
          description: Recommended quote-deadline budget in seconds, relative to signing time.
        fulfillmentDeadlineSeconds:
          type: integer
          minimum: 1
          description: Recommended fulfillment-deadline budget in seconds, relative to signing time.
        svmSignatureClusterId:
          type: string
          description: "Solana source only: cluster name used to build the 32-byte cluster_id in the V3 escrow signature domain. Optional; the facilitator requires it for a Solana source."
        svmSignatureDomainVersion:
          type: integer
          minimum: 1
          maximum: 255
          description: "Solana source only: escrow signature-domain version (V3 domain separation). Optional; required for a Solana source."
        depositRequestHashVersions:
          type: array
          items:
            type: integer
            minimum: 1
          minItems: 1
          uniqueItems: true
          description: "The depositRequestHash versions the payer may sign for this source: 1 is keccak256 of the request_id, 2 is the hash of the payment terms. Absent means [1]. A client signs 2 when the list contains it and 1 otherwise. A client or facilitator that predates this field refuses a requirement carrying it, even [1], so a resource server publishes it only once its payers and its facilitator run a release that knows it, and lists 2 only once the payment gateway's GET /v1/defaults returns deposit_request_hash_version 2 for the source chain, the network-wide signal that every reader of the deposit reads version 2."
    AtumEscrowPayload:
      title: AtumEscrowPayload
      description: "The PAYMENT-SIGNATURE credential body for the atum-escrow x402 scheme — a v2 PaymentPayload whose `accepted` echoes the selected requirement and whose `payload.paymentRequest` is the signed payment request. The inner paymentRequest conforms to the canonical PaymentRequest declaration (declarations/PaymentRequest/v1); only the scheme-critical fields the facilitator checks are constrained here and the rest is permitted, so a full PaymentRequest validates without being restated. The identity-binding `presentation` (PaymentRequestEnvelope) is REQUIRED for atum-escrow conformance but is optional at the schema level so a request may be validated before the envelope is attached; the facilitator enforces its presence and re-verifies it. Addresses are chain-general: an EVM `0x`-hex address (20 bytes) or a base58-encoded address (Solana/Tron), per the field's CAIP-2 chain."
      type: object
      additionalProperties: true
      required:
        - x402Version
        - accepted
        - payload
      properties:
        x402Version:
          const: 2
          description: x402 protocol version; always 2.
        accepted:
          type: object
          additionalProperties: true
          description: Echo of the selected 402 requirement, checked for equality against the separately-supplied requirement at verify time.
          required:
            - scheme
            - network
            - asset
            - payTo
            - amount
            - maxTimeoutSeconds
            - extra
          properties:
            scheme:
              const: atum-escrow
            network:
              type: string
              pattern: ^[-a-z0-9]+:.+$
            asset:
              type: string
              pattern: ^(0x[0-9a-fA-F]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$
            payTo:
              type: string
              pattern: ^(0x[0-9a-fA-F]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$
            amount:
              type: string
              pattern: ^[0-9]+$
            maxTimeoutSeconds:
              type: integer
              minimum: 1
            extra:
              type: object
              required:
                - atum
              properties:
                atum:
                  type: object
        extensions:
          type: object
          additionalProperties: true
          description: |-
            x402 extension data, echoed from the `extensions` map the resource server advertised in its 402 response with the payer's own values added. Per the x402 specification a client must include at least the information it received and may append to it, but may not remove or overwrite it. Kept open so that extensions unrelated to this scheme pass through untouched.

            The `atum-escrow` scheme uses the standard `payment-identifier` extension as the payment's idempotency key. It is REQUIRED for atum-escrow conformance but optional at the schema level, so that a payload can be validated before its extensions are attached; the facilitator enforces its presence and re-derives `request_id` from it.
          properties:
            payment-identifier:
              type: object
              additionalProperties: true
              description: The payment's idempotency key, as defined by the x402 payment-identifier extension.
              properties:
                info:
                  type: object
                  $comment: additionalProperties is deliberately left IMPLICIT here rather than stated as `true`, even though the surrounding objects state it. Both mean the same thing to a validator, but go-jsonschema emits an UnmarshalJSON for an open object that also carries a constrained property which references an undeclared `raw` variable, so the generated Go package does not compile. It only declares `raw` for an object with required properties, and this one has none. `id`'s length and pattern constraints are worth more than the generated AdditionalProperties convenience field, so the constraints stay and the keyword goes.
                  description: The extension's data. The resource server advertises `required`; the payer adds `id`.
                  properties:
                    required:
                      type: boolean
                      description: Whether the resource server requires payers to supply an identifier. Always true for atum-escrow, which cannot make a payment retry-safe without one.
                    id:
                      type: string
                      minLength: 16
                      maxLength: 128
                      pattern: ^[a-zA-Z0-9_-]+$
                      description: "The payer's identifier for the purchase being paid for: one value per purchase, the same value on every re-attempt of that purchase, and never shared between two purchases. `request_id` is derived from this value together with the source account, and the network de-duplicates on `request_id` — so reusing it on a re-attempt resolves to the original payment instead of taking a second one, while a fresh value starts a new payment."
        payload:
          type: object
          additionalProperties: false
          required:
            - paymentRequest
          properties:
            paymentRequest:
              type: object
              additionalProperties: true
              description: The signed payment request; conforms to the canonical PaymentRequest declaration (declarations/PaymentRequest/v1). Only the scheme-critical fields the facilitator checks are required here, the rest is permitted.
              required:
                - version
                - request_id
                - source
                - destination
                - fulfillment_amount
                - max_source_amount
                - quote_deadline
                - fulfillment_deadline
                - sender_auth
              properties:
                version:
                  type: string
                request_id:
                  type: string
                source:
                  type: object
                  additionalProperties: true
                  required:
                    - asset_identifier
                    - account
                  properties:
                    asset_identifier:
                      type: string
                    account:
                      type: string
                      pattern: ^(0x[0-9a-fA-F]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$
                destination:
                  type: array
                  minItems: 1
                  items:
                    type: object
                    additionalProperties: true
                    required:
                      - asset_identifier
                      - account
                    properties:
                      asset_identifier:
                        type: string
                      account:
                        type: string
                        pattern: ^(0x[0-9a-fA-F]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$
                fulfillment_amount:
                  type: string
                  pattern: ^[0-9]+$
                max_source_amount:
                  type: string
                  pattern: ^[0-9]+$
                quote_deadline:
                  type: string
                  format: date-time
                fulfillment_deadline:
                  type: string
                  format: date-time
                sender_auth:
                  type: object
                  additionalProperties: true
                  required:
                    - message_scheme
                    - signed_messages
                  properties:
                    message_scheme:
                      enum:
                        - EVM_PERMIT2
                        - EVM_PERMIT2_ESCROW
                        - SOLANA
                        - TRON
                      description: Sender-auth signature scheme. Wire-valid values mirror the canonical PaymentRequest SenderAuthMessageScheme; which of them a given facilitator actually verifies is a capability the facilitator enforces, not a schema constraint.
                    signed_messages:
                      type: array
                      minItems: 1
                      items:
                        type: object
                        additionalProperties: true
                        required:
                          - message
                          - signature
                        properties:
                          message:
                            type: string
                          message_prehash: {}
                          signature:
                            type: string
                presentation:
                  type: object
                  additionalProperties: true
                  description: "Identity binding — a holder-signed W3C VerifiablePresentation (PaymentRequestEnvelope; conforms to declarations/PaymentRequestEnvelope/v1) that binds this request to the payer. REQUIRED for atum-escrow conformance; optional at the schema level so a request may be validated before the envelope is attached. Only the binding-critical fields are constrained here; the full envelope validates against the canonical declaration. The facilitator re-verifies it: proofPurpose 'authentication', proof.challenge equals the request's request_hash (content hash of the request), proof.domain the network-wide verifier id, and holder equal to source.account."
                  required:
                    - type
                    - holder
                    - verifiableCredential
                    - proof
                  properties:
                    type:
                      type: array
                      description: MUST contain 'VerifiablePresentation' per W3C VC Data Model v1.1.
                      contains:
                        const: VerifiablePresentation
                      items:
                        type: string
                    holder:
                      type: string
                      pattern: ^did:pkh:[a-z][a-z0-9]*:[a-zA-Z0-9._:%-]+$
                      description: did:pkh of the payer; MUST equal source.account.
                    verifiableCredential:
                      type: array
                      minItems: 1
                      items:
                        type: object
                        additionalProperties: true
                    proof:
                      type: object
                      additionalProperties: true
                      required:
                        - proofPurpose
                        - challenge
                        - domain
                      properties:
                        proofPurpose:
                          const: authentication
                          description: Always 'authentication' for a VerifiablePresentation proof.
                        challenge:
                          type: string
                          minLength: 1
                          description: Equals the request's request_hash (content hash of the request).
                        domain:
                          type: string
                          minLength: 1
                          description: Network-wide verifier identifier, did:web:<env>.atum.xyz.
    VerifyResponse:
      type: object
      required:
        - isValid
      properties:
        isValid:
          type: boolean
        payer:
          type: string
          description: Depositor address recovered from the credential.
        invalidReason:
          type: string
          description: Present when isValid is false.
        extensions:
          type: object
          description: Facilitator-specific members. See AtumExtension for the atum one.
          properties:
            atum:
              $ref: "#/components/schemas/AtumExtension"
    SettleResponse:
      type: object
      description: |
        The synchronous settlement result — the standard x402 SettleResponse fields plus the Atum settlement receipt.
      required:
        - success
        - transaction
        - network
      properties:
        success:
          type: boolean
        transaction:
          type: string
          description: Destination settlement transaction hash.
        network:
          type: string
          description: CAIP-2 destination chain id.
        payer:
          type: string
        errorReason:
          type: string
          description: Present when success is false.
        extensions:
          type: object
          description: Facilitator-specific members. See AtumExtension for the atum one.
          properties:
            atum:
              $ref: "#/components/schemas/AtumExtension"
        fulfillmentConfirmation:
          type: object
          additionalProperties: true
          description: Full settlement receipt, which may be present once the payment is completed; also returned to the payer in PAYMENT-RESPONSE.
    AtumExtension:
      type: object
      description: |
        What this facilitator has to say beyond the standard members. It rides under `extensions.atum` rather than beside `errorReason` because the x402 response shape is fixed by the specification and `extensions` is what it provides for a facilitator with something of its own to add. A client that does not know the member ignores it.
      properties:
        paymentId:
          type: string
          description: |
            The Atum payment this answer is about. Present only once the network has named one, because a merchant correlates its fulfilment against it and an id-shaped blank correlates against nothing.
        state:
          type: string
          description: The payment's state as the network last reported it.
        statusUrl:
          type: string
          description: Where to poll the payment, when a public origin is configured.
        retryClassification:
          $ref: "#/components/schemas/RetryClassification"
    RetryClassification:
      type: string
      description: |
        What the merchant should do about the reason alongside it, drawn from the same closed set Atum's own error responses use. Without it a merchant reading `errorReason` or `invalidReason` has a label and no instruction.

        Present on every answer that is not a success, including the refusals that name no payment. Absent on a success: there is nothing to retry.

        A pattern-constrained string rather than an enum, so a client whose generated model closes the set does not reject the whole response on a value added later.
      pattern: ^[A-Z][A-Z0-9_]*$
      example: NOT_RETRYABLE_FIX_REQUEST
    SupportedResponse:
      type: object
      required:
        - kinds
        - signers
        - extensions
      properties:
        kinds:
          type: array
          items:
            $ref: "#/components/schemas/SupportedKind"
        signers:
          type: object
          description: |
            Map of CAIP-2 chain id to the facilitator's settlement signer addresses. Empty for atum-escrow: the facilitator holds no settlement key, since settlement is executed permissionlessly by settlers.
          additionalProperties:
            type: array
            items:
              type: string
        extensions:
          type: array
          items:
            type: string
    SupportedKind:
      type: object
      required:
        - x402Version
        - scheme
        - network
      properties:
        x402Version:
          type: integer
          const: 2
        scheme:
          type: string
        network:
          type: string
          description: CAIP-2 chain id.
        extra:
          type: object
          description: Per-kind detail; supported tokens for the network are listed here.
          properties:
            tokens:
              type: array
              items:
                type: string
