openapi: 3.1.0
info:
  title: AlgoVoi Gateway
  description: Public-facing x402 payment gateway.
  version: 1.0.0-phase1c
  x-guidance: To access payment-gated resources, send the required payment proof header. Use GET /mpp/{resource_id} for MPP or GET /protected/{resource_id} for x402.
paths:
  /health:
    get:
      tags:
      - health
      summary: Health
      operationId: health_health_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      x-payment-info:
        authMode: none
  /auth/token:
    post:
      tags:
      - agent-auth
      summary: Exchange Atb Cert
      description: 'Exchange an ATB ZKP certificate for an agent session token.


        Requires normal API key auth (X-Tenant-Id + Authorization: Bearer <api_key>)

        for this request only. The returned token is used for all subsequent calls

        within the session.'
      operationId: exchange_atb_cert_auth_token_post
      parameters:
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /auth/token/status:
    get:
      tags:
      - agent-auth
      summary: Session Status
      description: 'Return spend vs cap for a live agent session token.


        Pass the session token as `Authorization: Bearer <token>`.

        This endpoint does NOT require X-Tenant-Id — the tenant_id is read from

        the token claims. Returns 401 if the token is invalid or expired.'
      operationId: session_status_auth_token_status_get
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /v1/verify:
    post:
      tags:
      - v1
      summary: MPP payment verification
      description: 'Verify an on-chain payment transaction for the MPP adapter.


        The adapter submits the tx_id and network from the payer''s credential;

        the gateway looks up the resource definition to get the expected amount

        and receiver, then delegates to the facilitator for on-chain confirmation.


        Returns a receipt JWT on success.'
      operationId: mpp_verify_v1_verify_post
      parameters:
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MppVerifyRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MppVerifyResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /v1/ap2/verify:
    post:
      tags:
      - v1
      summary: AP2 mandate verification
      description: 'Verify an AP2 mandate credential submitted by a payer.


        The mandate dict must contain a ``signature`` field holding the JWT

        access token issued by POST /ap2/confirm.  The gateway verifies the

        JWT signature, checks that the tenant_id claim matches the authenticated

        tenant, and confirms the token has not expired.


        Returns ``{"verified": true}`` on success.'
      operationId: ap2_verify_v1_ap2_verify_post
      parameters:
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Ap2VerifyRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ap2VerifyResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /v1/payouts:
    post:
      tags:
      - v1
      summary: Initiate on-chain payout
      description: 'Initiate an on-chain transfer from the tenant''s custodial balance.


        Idempotent on ``reference``: submitting the same reference twice returns

        the original payout_id + tx_id without re-broadcasting to the chain.


        Supported networks (MVP): algorand_mainnet, voi_mainnet (USDC / aUSDC).

        currency must be USD (USDC peg assumed 1:1).'
      operationId: create_payout_v1_payouts_post
      parameters:
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayoutCreate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutCreateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /mpp/challenge:
    post:
      tags:
      - mpp
      summary: Mpp Challenge
      description: 'Explicit challenge pre-fetch for MPP agents that want to obtain a

        challenge token before building their payment transaction.


        Returns the same challenge object that GET /mpp/{resource_id} returns

        in its 401 body, allowing agents to pipeline challenge fetch → pay →

        proof submission without the round-trip to the resource endpoint.'
      operationId: mpp_challenge_mpp_challenge_post
      parameters:
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MppChallengeRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MppChallengeResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /mpp/probe:
    get:
      tags:
      - mpp
      - mpp
      summary: Mpp Probe
      description: 'Discovery probe + operator-level paid resource.


        No Authorization header → 402 + WWW-Authenticate: Payment challenge.

        Authorization: Payment <proof> → verify on-chain → 200 receipt.


        Payment goes to the AlgoVoi operator address (not a tenant). No DB

        session needed — facilitator verifies on-chain; receipt is logged.'
      operationId: mpp_probe_mpp_probe_delete
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              description: Optional payment proof or invocation parameters
              example: {}
        required: false
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '402':
          description: 'Payment Required — WWW-Authenticate: Payment'
      minPrice: 10000
      maxPrice: 10000
      inputSchema:
        type: object
        additionalProperties: true
      outputSchema:
        type: object
        properties:
          receipt:
            type: string
          resource_id:
            type: string
          tx_id:
            type: string
      x-payment-info:
        authMode: payment
        protocols:
        - x402
        - mpp
        price:
          mode: fixed
          amount: '10000'
          currency: '0x20c000000000000000000000b9537d11c60e8b50'
      x-discovery:
        resources:
        - url: https://api.algovoi.co.uk/mpp/probe
          description: MPP probe — canonical Tempo USDCe payment challenge
          network: tempo
          amount: '10000'
          asset: '0x20c000000000000000000000b9537d11c60e8b50'
    put:
      tags:
      - mpp
      - mpp
      summary: Mpp Probe
      description: 'Discovery probe + operator-level paid resource.


        No Authorization header → 402 + WWW-Authenticate: Payment challenge.

        Authorization: Payment <proof> → verify on-chain → 200 receipt.


        Payment goes to the AlgoVoi operator address (not a tenant). No DB

        session needed — facilitator verifies on-chain; receipt is logged.'
      operationId: mpp_probe_mpp_probe_delete
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              description: Optional payment proof or invocation parameters
              example: {}
        required: false
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '402':
          description: 'Payment Required — WWW-Authenticate: Payment'
      minPrice: 10000
      maxPrice: 10000
      inputSchema:
        type: object
        additionalProperties: true
      outputSchema:
        type: object
        properties:
          receipt:
            type: string
          resource_id:
            type: string
          tx_id:
            type: string
      x-payment-info:
        authMode: payment
        protocols:
        - x402
        - mpp
        price:
          mode: fixed
          amount: '10000'
          currency: '0x20c000000000000000000000b9537d11c60e8b50'
      x-discovery:
        resources:
        - url: https://api.algovoi.co.uk/mpp/probe
          description: MPP probe — canonical Tempo USDCe payment challenge
          network: tempo
          amount: '10000'
          asset: '0x20c000000000000000000000b9537d11c60e8b50'
    post:
      tags:
      - mpp
      - mpp
      summary: Mpp Probe
      description: 'Discovery probe + operator-level paid resource.


        No Authorization header → 402 + WWW-Authenticate: Payment challenge.

        Authorization: Payment <proof> → verify on-chain → 200 receipt.


        Payment goes to the AlgoVoi operator address (not a tenant). No DB

        session needed — facilitator verifies on-chain; receipt is logged.'
      operationId: mpp_probe_mpp_probe_delete
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              description: Optional payment proof or invocation parameters
              example: {}
        required: false
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '402':
          description: 'Payment Required — WWW-Authenticate: Payment'
      minPrice: 10000
      maxPrice: 10000
      inputSchema:
        type: object
        additionalProperties: true
      outputSchema:
        type: object
        properties:
          receipt:
            type: string
          resource_id:
            type: string
          tx_id:
            type: string
      x-payment-info:
        authMode: payment
        protocols:
        - x402
        - mpp
        price:
          mode: fixed
          amount: '10000'
          currency: '0x20c000000000000000000000b9537d11c60e8b50'
      x-discovery:
        resources:
        - url: https://api.algovoi.co.uk/mpp/probe
          description: MPP probe — canonical Tempo USDCe payment challenge
          network: tempo
          amount: '10000'
          asset: '0x20c000000000000000000000b9537d11c60e8b50'
    delete:
      tags:
      - mpp
      - mpp
      summary: Mpp Probe
      description: 'Discovery probe + operator-level paid resource.


        No Authorization header → 402 + WWW-Authenticate: Payment challenge.

        Authorization: Payment <proof> → verify on-chain → 200 receipt.


        Payment goes to the AlgoVoi operator address (not a tenant). No DB

        session needed — facilitator verifies on-chain; receipt is logged.'
      operationId: mpp_probe_mpp_probe_delete
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              description: Optional payment proof or invocation parameters
              example: {}
        required: false
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '402':
          description: 'Payment Required — WWW-Authenticate: Payment'
      minPrice: 10000
      maxPrice: 10000
      inputSchema:
        type: object
        additionalProperties: true
      outputSchema:
        type: object
        properties:
          receipt:
            type: string
          resource_id:
            type: string
          tx_id:
            type: string
      x-payment-info:
        authMode: payment
        protocols:
        - x402
        - mpp
        price:
          mode: fixed
          amount: '10000'
          currency: '0x20c000000000000000000000b9537d11c60e8b50'
      x-discovery:
        resources:
        - url: https://api.algovoi.co.uk/mpp/probe
          description: MPP probe — canonical Tempo USDCe payment challenge
          network: tempo
          amount: '10000'
          asset: '0x20c000000000000000000000b9537d11c60e8b50'
    options:
      tags:
      - mpp
      - mpp
      summary: Mpp Probe
      description: 'Discovery probe + operator-level paid resource.


        No Authorization header → 402 + WWW-Authenticate: Payment challenge.

        Authorization: Payment <proof> → verify on-chain → 200 receipt.


        Payment goes to the AlgoVoi operator address (not a tenant). No DB

        session needed — facilitator verifies on-chain; receipt is logged.'
      operationId: mpp_probe_mpp_probe_delete
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              description: Optional payment proof or invocation parameters
              example: {}
        required: false
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '402':
          description: 'Payment Required — WWW-Authenticate: Payment'
      minPrice: 10000
      maxPrice: 10000
      inputSchema:
        type: object
        additionalProperties: true
      outputSchema:
        type: object
        properties:
          receipt:
            type: string
          resource_id:
            type: string
          tx_id:
            type: string
      x-payment-info:
        authMode: payment
        protocols:
        - x402
        - mpp
        price:
          mode: fixed
          amount: '10000'
          currency: '0x20c000000000000000000000b9537d11c60e8b50'
      x-discovery:
        resources:
        - url: https://api.algovoi.co.uk/mpp/probe
          description: MPP probe — canonical Tempo USDCe payment challenge
          network: tempo
          amount: '10000'
          asset: '0x20c000000000000000000000b9537d11c60e8b50'
    head:
      tags:
      - mpp
      - mpp
      summary: Mpp Probe
      description: 'Discovery probe + operator-level paid resource.


        No Authorization header → 402 + WWW-Authenticate: Payment challenge.

        Authorization: Payment <proof> → verify on-chain → 200 receipt.


        Payment goes to the AlgoVoi operator address (not a tenant). No DB

        session needed — facilitator verifies on-chain; receipt is logged.'
      operationId: mpp_probe_mpp_probe_delete
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              description: Optional payment proof or invocation parameters
              example: {}
        required: false
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '402':
          description: 'Payment Required — WWW-Authenticate: Payment'
      minPrice: 10000
      maxPrice: 10000
      inputSchema:
        type: object
        additionalProperties: true
      outputSchema:
        type: object
        properties:
          receipt:
            type: string
          resource_id:
            type: string
          tx_id:
            type: string
      x-payment-info:
        authMode: payment
        protocols:
        - x402
        - mpp
        price:
          mode: fixed
          amount: '10000'
          currency: '0x20c000000000000000000000b9537d11c60e8b50'
      x-discovery:
        resources:
        - url: https://api.algovoi.co.uk/mpp/probe
          description: MPP probe — canonical Tempo USDCe payment challenge
          network: tempo
          amount: '10000'
          asset: '0x20c000000000000000000000b9537d11c60e8b50'
    patch:
      tags:
      - mpp
      - mpp
      summary: Mpp Probe
      description: 'Discovery probe + operator-level paid resource.


        No Authorization header → 402 + WWW-Authenticate: Payment challenge.

        Authorization: Payment <proof> → verify on-chain → 200 receipt.


        Payment goes to the AlgoVoi operator address (not a tenant). No DB

        session needed — facilitator verifies on-chain; receipt is logged.'
      operationId: mpp_probe_mpp_probe_delete
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              description: Optional payment proof or invocation parameters
              example: {}
        required: false
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '402':
          description: 'Payment Required — WWW-Authenticate: Payment'
      minPrice: 10000
      maxPrice: 10000
      inputSchema:
        type: object
        additionalProperties: true
      outputSchema:
        type: object
        properties:
          receipt:
            type: string
          resource_id:
            type: string
          tx_id:
            type: string
      x-payment-info:
        authMode: payment
        protocols:
        - x402
        - mpp
        price:
          mode: fixed
          amount: '10000'
          currency: '0x20c000000000000000000000b9537d11c60e8b50'
      x-discovery:
        resources:
        - url: https://api.algovoi.co.uk/mpp/probe
          description: MPP probe — canonical Tempo USDCe payment challenge
          network: tempo
          amount: '10000'
          asset: '0x20c000000000000000000000b9537d11c60e8b50'
  /mpp/{resource_id}:
    get:
      tags:
      - mpp
      summary: Mpp Resource
      description: 'IETF draft-httpauth-payment resource gate.


        No Authorization header → HTTP 401 + WWW-Authenticate: Payment challenge.

        Authorization: Payment <b64> → validate challenge echo → verify on-chain → HTTP 200.


        The x402 /protected/{resource_id} endpoint is completely unchanged.'
      operationId: mpp_resource_mpp__resource_id__get
      parameters:
      - name: resource_id
        in: path
        required: true
        schema:
          type: string
          title: Resource Id
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '402':
          description: Payment Required
      minPrice: 10000
      maxPrice: 10000
      x-payment-info:
        authMode: payment
        protocols:
        - mpp
        - x402
        price:
          mode: fixed
          amount: '10000'
          currency: '0x20c000000000000000000000b9537d11c60e8b50'
  /mpp/sub/{resource_id}:
    post:
      tags:
      - mpp
      - mpp
      summary: Mpp Subscription Resource
      description: 'MPP subscription gate (API key auth).


        No proof → 402 + intent="subscription" challenge with periodCount/periodUnit.

        Credential present → verify authority tx → create MppSubscription → return subscriptionId.'
      operationId: mpp_subscription_resource_mpp_sub__resource_id__post
      parameters:
      - name: resource_id
        in: path
        required: true
        schema:
          type: string
          title: Resource Id
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Idempotency-Key
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '402':
          description: Payment Required — subscription challenge
      x-payment-info:
        authMode: payment
        protocols:
        - mpp
        intent: subscription
    get:
      tags:
      - mpp
      - mpp
      summary: Mpp Subscription Resource
      description: 'MPP subscription gate (API key auth).


        No proof → 402 + intent="subscription" challenge with periodCount/periodUnit.

        Credential present → verify authority tx → create MppSubscription → return subscriptionId.'
      operationId: mpp_subscription_resource_mpp_sub__resource_id__post
      parameters:
      - name: resource_id
        in: path
        required: true
        schema:
          type: string
          title: Resource Id
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Idempotency-Key
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '402':
          description: Payment Required — subscription challenge
      x-payment-info:
        authMode: payment
        protocols:
        - mpp
        intent: subscription
  /ap2/intent:
    post:
      tags:
      - ap2
      summary: Submit an IntentMandate to open an AP2 shopping session
      description: 'Receive an IntentMandate. If user_authorization is present (SD-JWT-VC),

        verification is deferred to /pay where it binds to specific cart and

        payment hashes — at /intent stage we have nothing concrete to bind to.


        Per spec: if intent is not user-signed, user_cart_confirmation_required

        MUST be True (otherwise the agent could shop unilaterally without consent).'
      operationId: submit_intent_ap2_intent_post
      parameters:
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AP2IntentRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AP2IntentResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /ap2/cart:
    post:
      tags:
      - ap2
      summary: Submit a merchant-signed CartMandate, verified against an accepted IntentMandate
      operationId: submit_cart_ap2_cart_post
      parameters:
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AP2CartRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AP2CartResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /ap2/pay:
    post:
      tags:
      - ap2
      summary: Submit PaymentMandate; verify user_authorization and return crypto challenge
      operationId: initiate_payment_ap2_pay_post
      parameters:
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AP2PayRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AP2PayResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /ap2/confirm:
    post:
      tags:
      - ap2
      summary: Confirm on-chain transaction; gateway verifies via facilitator and issues JWT
      operationId: confirm_payment_ap2_confirm_post
      parameters:
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AP2ConfirmRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AP2ConfirmResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /ap2/status/{cart_id}:
    get:
      tags:
      - ap2
      summary: Inspect AP2 mandate chain state by cart_id
      operationId: get_status_ap2_status__cart_id__get
      parameters:
      - name: cart_id
        in: path
        required: true
        schema:
          type: string
          title: Cart Id
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AP2StatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /ap2/extensions:
    get:
      tags:
      - ap2
      summary: List AP2 extensions supported by this gateway
      description: 'Returns the AP2 extensions this gateway supports. Used by AP2 agents to

        discover available payment methods (e.g. AlgoVoi crypto rails) before

        constructing a CartMandate.'
      operationId: list_extensions_ap2_extensions_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AP2ExtensionsResponse'
      x-payment-info:
        authMode: api_key
  /ext/scoped-authorization-receipts/v1:
    get:
      tags:
      - a2a
      - a2a
      summary: ' Scoped Auth Receipts Profile'
      operationId: _scoped_auth_receipts_profile_ext_scoped_authorization_receipts_v1_head
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      x-payment-info:
        authMode: api_key
    head:
      tags:
      - a2a
      - a2a
      summary: ' Scoped Auth Receipts Profile'
      operationId: _scoped_auth_receipts_profile_ext_scoped_authorization_receipts_v1_head
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      x-payment-info:
        authMode: api_key
  /extendedAgentCard:
    get:
      tags:
      - a2a
      - a2a
      summary: Extended Agent Card
      description: 'Authenticated extended agent card.

        Returns the base card enriched with tenant-specific endpoint info.'
      operationId: extended_agent_card_extendedAgentCard_get
      parameters:
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: none
  /message:send:
    post:
      tags:
      - a2a
      - a2a
      summary: Send Message
      description: 'Send a message to the AlgoVoi payment agent (A2A HTTP+JSON binding).


        Returns the completed Task as the bare resource, serialized to the

        negotiated A2A version (0.3 or 1.0). The AlgoVoi payment skills

        (verify-payment, create-checkout, check-status, post-twitter-checkout) are

        invoked via a `skill` marker in a DataPart; a skill-less message is

        acknowledged with a completed task.'
      operationId: send_message_message_send_post
      parameters:
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/_SendMessageRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /message:stream:
    post:
      tags:
      - a2a
      - a2a
      summary: Message Stream
      description: 'Streaming is not supported (capabilities.streaming=false) — return a

        typed UnsupportedOperation error (400) rather than a bare 404/405.'
      operationId: message_stream_message_stream_post
      parameters:
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /tasks/{task_id}/pushNotificationConfigs/{config_id}:
    get:
      tags:
      - a2a
      - a2a
      summary: Push Notification Config
      description: Push notifications are not supported (capabilities.pushNotifications=false).
      operationId: push_notification_config_tasks__task_id__pushNotificationConfigs__config_id__get
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
          title: Task Id
      - name: config_id
        in: path
        required: true
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Config Id
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
    delete:
      tags:
      - a2a
      - a2a
      summary: Push Notification Config
      description: Push notifications are not supported (capabilities.pushNotifications=false).
      operationId: push_notification_config_tasks__task_id__pushNotificationConfigs__config_id__get
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
          title: Task Id
      - name: config_id
        in: path
        required: true
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Config Id
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /tasks/{task_id}/pushNotificationConfigs:
    post:
      tags:
      - a2a
      - a2a
      summary: Push Notification Config
      description: Push notifications are not supported (capabilities.pushNotifications=false).
      operationId: push_notification_config_tasks__task_id__pushNotificationConfigs_post
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
          title: Task Id
      - name: config_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Config Id
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
    get:
      tags:
      - a2a
      - a2a
      summary: Push Notification Config
      description: Push notifications are not supported (capabilities.pushNotifications=false).
      operationId: push_notification_config_tasks__task_id__pushNotificationConfigs_post
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
          title: Task Id
      - name: config_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Config Id
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /tasks/{task_id}:
    get:
      tags:
      - a2a
      - a2a
      summary: Get Task
      description: Get the current state of a task by ID (serialized to the negotiated version).
      operationId: get_task_tasks__task_id__get
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
          title: Task Id
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /tasks/{task_id}:cancel:
    post:
      tags:
      - a2a
      - a2a
      summary: Cancel Task
      description: 'Cancel a task. Since AlgoVoi tasks complete synchronously, only

        tasks in ''submitted'' or ''working'' state can be cancelled.

        Completed/failed tasks return TaskNotCancelable.'
      operationId: cancel_task_tasks__task_id__cancel_post
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
          title: Task Id
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /tasks:
    get:
      tags:
      - a2a
      - a2a
      summary: List Tasks
      description: 'List recent tasks for this session. Returns tasks from the in-process store

        (TTL 10 minutes), serialized to the negotiated A2A version.'
      operationId: list_tasks_tasks_get
      parameters:
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /a2a/jsonrpc:
    post:
      tags:
      - a2a
      - a2a
      summary: A2A Jsonrpc
      description: A2A JSON-RPC 2.0 endpoint (advertised as the JSONRPC interface).
      operationId: a2a_jsonrpc_a2a_jsonrpc_post
      parameters:
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /a2a/gibberlink:
    post:
      tags:
      - a2a
      summary: A2A Gibberlink
      operationId: a2a_gibberlink_a2a_gibberlink_post
      parameters:
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /v1/payment-links:
    post:
      tags:
      - v1
      summary: Create a dynamic payment link
      description: Create a hosted checkout link for a specific fiat amount. The amount is converted to stablecoin (USDC / aUSDC) or native crypto using the tenant's configured network and the live FX rate. The returned `checkout_url` can be sent directly to the buyer.
      operationId: create_dynamic_payment_link_v1_payment_links_post
      parameters:
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DynamicPaymentLinkCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DynamicPaymentLinkResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /v1/customers:
    post:
      tags:
      - v1
      summary: Create Customer Endpoint
      operationId: create_customer_endpoint_v1_customers_post
      parameters:
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
    get:
      tags:
      - v1
      summary: List Customers Endpoint
      operationId: list_customers_endpoint_v1_customers_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CustomerResponse'
                title: Response List Customers Endpoint V1 Customers Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /v1/subscriptions:
    post:
      tags:
      - v1
      summary: Create Subscription Endpoint
      operationId: create_subscription_endpoint_v1_subscriptions_post
      parameters:
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
    get:
      tags:
      - v1
      summary: List Subscriptions Endpoint
      operationId: list_subscriptions_endpoint_v1_subscriptions_get
      parameters:
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by status
          title: Status
        description: Filter by status
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SubscriptionResponse'
                title: Response List Subscriptions Endpoint V1 Subscriptions Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /v1/subscriptions/{subscription_id}:
    get:
      tags:
      - v1
      summary: Get Subscription Endpoint
      operationId: get_subscription_endpoint_v1_subscriptions__subscription_id__get
      parameters:
      - name: subscription_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Subscription Id
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
    patch:
      tags:
      - v1
      summary: Update Subscription Endpoint
      operationId: update_subscription_endpoint_v1_subscriptions__subscription_id__patch
      parameters:
      - name: subscription_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Subscription Id
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /v1/subscriptions/{subscription_id}/cancel:
    post:
      tags:
      - v1
      summary: Cancel Subscription Endpoint
      operationId: cancel_subscription_endpoint_v1_subscriptions__subscription_id__cancel_post
      parameters:
      - name: subscription_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Subscription Id
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/CancelSubscriptionBody'
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /v1/subscriptions/{subscription_id}/pause:
    post:
      tags:
      - v1
      summary: Pause Subscription Endpoint
      operationId: pause_subscription_endpoint_v1_subscriptions__subscription_id__pause_post
      parameters:
      - name: subscription_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Subscription Id
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /v1/subscriptions/{subscription_id}/resume:
    post:
      tags:
      - v1
      summary: Resume Subscription Endpoint
      operationId: resume_subscription_endpoint_v1_subscriptions__subscription_id__resume_post
      parameters:
      - name: subscription_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Subscription Id
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /v1/subscriptions/{subscription_id}/invoices:
    get:
      tags:
      - v1
      summary: List Subscription Invoices Endpoint
      operationId: list_subscription_invoices_endpoint_v1_subscriptions__subscription_id__invoices_get
      parameters:
      - name: subscription_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Subscription Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SubscriptionInvoiceResponse'
                title: Response List Subscription Invoices Endpoint V1 Subscriptions  Subscription Id  Invoices Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /subscription/{cancel_secret}/cancel:
    get:
      tags:
      - public
      summary: Public Cancel Page
      description: 'Public page — single-use cancel link given to customer at signup.

        GET shows a confirmation page; POST commits the cancellation.'
      operationId: public_cancel_page_subscription__cancel_secret__cancel_get
      parameters:
      - name: cancel_secret
        in: path
        required: true
        schema:
          type: string
          title: Cancel Secret
      responses:
        '200':
          description: Successful Response
          content:
            text/html:
              schema:
                type: string
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: none
    post:
      tags:
      - public
      summary: Public Cancel Commit
      operationId: public_cancel_commit_subscription__cancel_secret__cancel_post
      parameters:
      - name: cancel_secret
        in: path
        required: true
        schema:
          type: string
          title: Cancel Secret
      responses:
        '200':
          description: Successful Response
          content:
            text/html:
              schema:
                type: string
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: none
  /v1/recurr/auth/challenge:
    post:
      tags:
      - recurr
      summary: Challenge Endpoint
      operationId: challenge_endpoint_v1_recurr_auth_challenge_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/shared__schemas__recurr__ChallengeRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shared__schemas__recurr__ChallengeResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /v1/recurr/auth/verify:
    post:
      tags:
      - recurr
      summary: Verify Endpoint
      operationId: verify_endpoint_v1_recurr_auth_verify_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/shared__schemas__recurr__VerifyRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shared__schemas__recurr__VerifyResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /v1/recurr/me/subscriptions:
    get:
      tags:
      - recurr
      summary: My Subscriptions
      description: 'Cross-tenant. Returns every subscription where the wallet matches a

        customer row, regardless of which tenant owns that subscription.'
      operationId: my_subscriptions_v1_recurr_me_subscriptions_get
      parameters:
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SubscriptionResponse'
                title: Response My Subscriptions V1 Recurr Me Subscriptions Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /v1/recurr/me/subscriptions/{subscription_id}:
    get:
      tags:
      - recurr
      summary: My Subscription Detail
      operationId: my_subscription_detail_v1_recurr_me_subscriptions__subscription_id__get
      parameters:
      - name: subscription_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Subscription Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /v1/recurr/me/subscriptions/{subscription_id}/cancel:
    post:
      tags:
      - recurr
      summary: My Subscription Cancel
      operationId: my_subscription_cancel_v1_recurr_me_subscriptions__subscription_id__cancel_post
      parameters:
      - name: subscription_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Subscription Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /v1/recurr/me/invoices:
    get:
      tags:
      - recurr
      summary: My Invoices
      operationId: my_invoices_v1_recurr_me_invoices_get
      parameters:
      - name: subscription_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Subscription Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SubscriptionInvoiceResponse'
                title: Response My Invoices V1 Recurr Me Invoices Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /recurr/portal:
    get:
      tags:
      - recurr-public
      summary: Portal Page
      description: "Tenant-agnostic customer portal — connect wallet, see all subscriptions\nacross every merchant who has billed that wallet.\n\nEmbeds zero JS framework. Wallets:\n  - EVM (Base, Tempo, ...): MetaMask injected provider + EIP-191 personal_sign\n  - Solana: window.solana (Phantom)\n  - Algorand / VOI: Pera, Defly, Lute (signData with \"MX\" prefix)\n  - Stellar: Stellar Wallets Kit (Freighter, Albedo, xBull, Lobstr, Hana, Rabet)\n  - Hedera: Hedera Wallet Connect (HashPack, Blade, Kabila) via Reown\n\nSecurity: pre-sale Comet third-pass review (2026-05-07, Task A) caught\nthat the previous `replace('\"', \"\")` sanitisation of the `chain` query\nparameter was insufficient — single quotes and semicolons fell through\ninto a JS string literal under the legacy 'unsafe-inline' CSP applied\nto /recurr/portal, enabling reflected XSS via `?chain='; alert(1);//`.\nReplaced with a strict allowlist. The `wc_pid` reflection is also\ntightened to a 32-char-hex regex even though it sources\
        \ from settings."
      operationId: portal_page_recurr_portal_get
      parameters:
      - name: chain
        in: query
        required: false
        schema:
          type: string
          description: Default chain for wallet-connect
          default: base_mainnet
          title: Chain
        description: Default chain for wallet-connect
      responses:
        '200':
          description: Successful Response
          content:
            text/html:
              schema:
                type: string
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: none
  /recurr/cancel/{cancel_secret}:
    get:
      tags:
      - recurr-public
      summary: Public Cancel Page
      operationId: public_cancel_page_recurr_cancel__cancel_secret__get
      parameters:
      - name: cancel_secret
        in: path
        required: true
        schema:
          type: string
          title: Cancel Secret
      responses:
        '200':
          description: Successful Response
          content:
            text/html:
              schema:
                type: string
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: none
    post:
      tags:
      - recurr-public
      summary: Public Cancel Commit
      operationId: public_cancel_commit_recurr_cancel__cancel_secret__post
      parameters:
      - name: cancel_secret
        in: path
        required: true
        schema:
          type: string
          title: Cancel Secret
      responses:
        '200':
          description: Successful Response
          content:
            text/html:
              schema:
                type: string
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: none
  /v1/recurring/authorities:
    post:
      tags:
      - recurring
      summary: Create Authority Endpoint
      description: 'Create a Tier 2 standing authority for an existing subscription.


        Returns the server-recorded authority (status=''pending'') plus the

        chain-specific payload the customer''s wallet signs to land the

        on-chain authorisation. The AlgoVoi widget consumes the payload;

        the customer signs the 6-action atomic group; AlgoVoi confirms the

        landing and a separate POST /confirm transitions to ''active''.'
      operationId: create_authority_endpoint_v1_recurring_authorities_post
      parameters:
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthorityCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorityCreateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
    get:
      tags:
      - recurring
      summary: List Authorities Endpoint
      operationId: list_authorities_endpoint_v1_recurring_authorities_get
      parameters:
      - name: subscription_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Subscription Id
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by status
          title: Status
        description: Filter by status
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AuthorityResponse'
                title: Response List Authorities Endpoint V1 Recurring Authorities Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /v1/recurring/authorities/{authority_id}:
    get:
      tags:
      - recurring
      summary: Get Authority Endpoint
      operationId: get_authority_endpoint_v1_recurring_authorities__authority_id__get
      parameters:
      - name: authority_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Authority Id
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorityResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /v1/recurring/authorities/{authority_id}/confirm:
    post:
      tags:
      - recurring
      summary: Confirm Authority Endpoint
      description: 'Mark an authority active after on-chain landing.


        The tenant calls this once they (or the AlgoVoi widget) has confirmed

        the customer''s signed transaction group landed on-chain. ``on_chain_address``

        carries the chain-specific identifier (e.g. ``app:<application_id>``).'
      operationId: confirm_authority_endpoint_v1_recurring_authorities__authority_id__confirm_post
      parameters:
      - name: authority_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Authority Id
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthorityConfirmRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorityResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /v1/recurring/authorities/{authority_id}/revoke:
    post:
      tags:
      - recurring
      summary: Revoke Authority Endpoint
      operationId: revoke_authority_endpoint_v1_recurring_authorities__authority_id__revoke_post
      parameters:
      - name: authority_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Authority Id
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorityResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /v1/recurring/authorities/{authority_id}/pause:
    post:
      tags:
      - recurring
      summary: Pause Authority Endpoint
      operationId: pause_authority_endpoint_v1_recurring_authorities__authority_id__pause_post
      parameters:
      - name: authority_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Authority Id
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorityResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /v1/recurring/authorities/{authority_id}/resume:
    post:
      tags:
      - recurring
      summary: Resume Authority Endpoint
      operationId: resume_authority_endpoint_v1_recurring_authorities__authority_id__resume_post
      parameters:
      - name: authority_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Authority Id
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthorityResumeRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorityResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /v1/recurring/pulls:
    post:
      tags:
      - recurring
      summary: Manual Pull Endpoint
      description: 'Manually request a pull cycle. Returns the (unchanged) authority record.


        The actual chain-side pull submission is performed by the Sprint 1.5c

        cycle reaper (which this endpoint signals via setting

        ``next_cycle_due_at = now``). For 1.5b this endpoint validates the

        request shape and updates next_cycle_due_at; the reaper picks up

        on its next sweep.


        202 Accepted — the pull will execute on the reaper''s next tick, not

        synchronously.'
      operationId: manual_pull_endpoint_v1_recurring_pulls_post
      parameters:
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PullCreate'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorityResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /v1/recurring/auth/{token}:
    get:
      tags:
      - recurring-hosted-auth
      summary: Resolve hosted-auth signing token
      description: Public endpoint consumed by recurr.algovoi.co.uk to render the Authority Summary Card. Returns 410 Gone in constant time for any not-found / expired / consumed token to prevent enumeration.
      operationId: resolve_token_v1_recurring_auth__token__get
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HostedAuthResolveResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /v1/recurring/auth/{token}/confirm:
    post:
      tags:
      - recurring-hosted-auth
      summary: Confirm hosted-auth signing token + activate authority
      description: 'Called by recurr.algovoi.co.uk after the customer''s wallet has signed and the on-chain transaction has landed. Fires a sanctions screen on the wallet address (pre-activation gate) and writes authority_signed + authority_confirmed audit-chain events. Idempotent: re-confirms with the same on_chain_address return 200 with the existing row; mismatched address returns 409.'
      operationId: confirm_token_v1_recurring_auth__token__confirm_post
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Idempotency-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HostedAuthConfirmRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HostedAuthConfirmResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /v1/recurring/contracts/algorand/spending_cap_vault_v1:
    get:
      tags:
      - recurring-contracts
      summary: Compiled TEAL bytecode for the Algorand SpendingCapVault v1 contract
      description: 'Return the compiled approval + clear TEAL programs for the hosted-auth

        page to construct and sign the vault-deploy ApplicationCreate transaction.'
      operationId: get_algorand_spending_cap_vault_v1_v1_recurring_contracts_algorand_spending_cap_vault_v1_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Get Algorand Spending Cap Vault V1 V1 Recurring Contracts Algorand Spending Cap Vault V1 Get
      x-payment-info:
        authMode: api_key
  /protected/{resource_id}:
    get:
      tags:
      - x402-protected
      summary: Get Protected Resource
      description: 'x402-compliant protected resource endpoint.


        Accepts payment proof via either header (compatible with both specs):

        - X-PAYMENT (gateway spec)

        - PAYMENT-SIGNATURE (coinbase/x402 spec, used by AlgoVoi extension)


        - No payment header  →  HTTP 402 + PAYMENT-REQUIRED header

        - Payment header     →  verify on-chain → HTTP 200 + body'
      operationId: get_protected_resource_protected__resource_id__get
      parameters:
      - name: resource_id
        in: path
        required: true
        schema:
          type: string
          title: Resource Id
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-payment
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Payment
      - name: PAYMENT-SIGNATURE
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Payment-Signature
      - name: X-ATB-Credential
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Atb-Credential
      - name: X-ATB-ZK-Credential
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Atb-Zk-Credential
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '402':
          description: Payment Required
      minPrice: 10000
      maxPrice: 10000
      x-payment-info:
        authMode: payment
        protocols:
        - mpp
        - x402
        price:
          mode: fixed
          amount: '10000'
          currency: '31566704'
  /resources/{resource_id}:
    get:
      tags:
      - resources
      summary: Get Resource
      operationId: get_resource_resources__resource_id__get
      parameters:
      - name: resource_id
        in: path
        required: true
        schema:
          type: string
          title: Resource Id
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /x402/challenge:
    post:
      tags:
      - x402
      summary: Challenge
      description: Return payment instructions using per-resource price/network and per-tenant payout address.
      operationId: challenge_x402_challenge_post
      parameters:
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/gateway__app__routers__verify__ChallengeRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/gateway__app__routers__verify__ChallengeResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /x402/verify:
    post:
      tags:
      - x402
      summary: Verify
      description: Submit tx_id for verification using per-tenant payout address as expected receiver.
      operationId: verify_x402_verify_post
      parameters:
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/gateway__app__routers__verify__VerifyRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/gateway__app__routers__verify__VerifyResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /checkout/{token}/verify:
    post:
      tags:
      - checkout
      summary: Verify Checkout
      description: 'Verify the payer''s on-chain transaction and mark the payment link paid.


        The payer must have sent exactly the required amount to the receiver address

        on the correct chain. The facilitator performs the on-chain verification.


        Returns the redirect_url on success so the browser JS can redirect.

        Returns 422 if the transaction is invalid or cannot be verified.

        Returns 409 if the link is already paid.

        Returns 410 if the link is expired or cancelled.'
      operationId: verify_checkout_checkout__token__verify_post
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutVerifyRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutVerifyResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /checkout/{token}/qr:
    get:
      tags:
      - checkout
      summary: Checkout Qr
      description: 'Generate a QR code PNG for any short string (used for WalletConnect pairing URIs).

        Returns image/png so the browser can use it as <img src=...> without any JS QR library.'
      operationId: checkout_qr_checkout__token__qr_get
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      - name: data
        in: query
        required: true
        schema:
          type: string
          title: Data
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /checkout/{token}/build-txn:
    get:
      tags:
      - checkout
      summary: Checkout Build Txn
      description: 'Build an unsigned Algorand/VOI transaction for WalletConnect signing.

        Caller supplies ?sender=<address>.  Returns {unsigned_txn: <base64>} ready

        to pass straight to algo_signTxn — no algosdk needed in the browser.'
      operationId: checkout_build_txn_checkout__token__build_txn_get
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      - name: sender
        in: query
        required: true
        schema:
          type: string
          title: Sender
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /checkout/{token}/submit-txn:
    post:
      tags:
      - checkout
      summary: Checkout Submit Txn
      description: 'Accept a base64-encoded signed Algorand/VOI transaction, submit it to algod,

        and return the tx_id for verification via the existing /verify endpoint.'
      operationId: checkout_submit_txn_checkout__token__submit_txn_post
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /checkout/{token}/detect:
    get:
      tags:
      - checkout
      summary: Detect Payment
      description: "Auto-detect inbound payment by polling the chain's indexer/mirror node.\n\nSupports all chains:\n  - Algorand/VOI: queries indexer /v2/transactions?address=...&note-prefix=...\n  - Hedera: queries Mirror Node /api/v1/transactions?account.id=...\n\nReturns {\"found\": true, \"tx_id\": \"...\"} when detected, or {\"found\": false}."
      operationId: detect_payment_checkout__token__detect_get
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /checkout/{token}/submit-sponsored:
    post:
      tags:
      - checkout
      summary: Submit Sponsored
      description: 'Accept a customer''s signed 0-fee transaction and submit it via the

        tenant''s sponsor wallet (atomic group fee pooling).


        Body: { "signed_tx": base64, "chain": "algorand-mainnet" | "voi-mainnet" }


        If the tenant has no sponsor wallet configured, returns

        {"error": "not_sponsored", "fallback": true} so the client can fall back

        to normal payment flow.'
      operationId: submit_sponsored_checkout__token__submit_sponsored_post
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /checkout/{token}/abandon:
    post:
      tags:
      - checkout
      summary: Abandon Checkout
      description: "Customer-initiated checkout abandonment.\n\nNo `cancel_secret` required: anyone who has the checkout URL can already\nwalk away from their own checkout. This endpoint just makes the\nabandonment EXPLICIT to the platform — without it, the merchant order\nstays in `Pending` indefinitely, and OpenCart's `algovoi.callback`\npolling our `/status` would still see `active`, leading to confusing\nUX where a cancelled checkout returns to the merchant's checkout page\ninstead of the merchant's \"order cancelled\" page.\n\nOnly `active` links can be abandoned:\n  * `paid`     → 409 Conflict (let the JS show \"Payment confirmed\" instead)\n  * `cancelled`→ 200 (idempotent — already cancelled)\n  * `expired`  → 410 Gone\n\nOn success: marks `link.status = 'cancelled'` AND notifies the merchant\nplatform (OpenCart etc.) to mark the order as Cancelled on their side.\nAlways returns the redirect_url so the JS can wire the \"Return to store\"\nlink target."
      operationId: abandon_checkout_checkout__token__abandon_post
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /checkout/{token}/cancel:
    post:
      tags:
      - checkout
      summary: Cancel Checkout
      description: 'Cancel an active checkout link. Sets status to ''cancelled''.


        F5 security fix: requires cancel_secret in the request body. The secret

        is generated at link-creation time and returned to the merchant only —

        it is never embedded in the public checkout page. This prevents an

        attacker who merely knows the checkout URL from cancelling the link.


        Only active links can be cancelled. Paid/expired/already-cancelled links

        return 409/410.  Returns redirect_url so callers can redirect customers.'
      operationId: cancel_checkout_checkout__token__cancel_post
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelCheckoutRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /checkout/{token}/xchain/bridge-info:
    get:
      tags:
      - checkout
      summary: Xchain Bridge Info
      description: 'Return all EVM chains Allbridge supports as bridge SOURCES for the

        tenant''s configured destination chain (Algorand USDCa or Solana USDC),

        pre-computed with the exact send amount (checkout amount + bridge fee).


        Also returns the destination metadata so the frontend can render the

        right "USDC on <chain>" label without a second round-trip.'
      operationId: xchain_bridge_info_checkout__token__xchain_bridge_info_get
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /checkout/{token}/xchain/bridge-send:
    post:
      tags:
      - checkout
      summary: Xchain Bridge Send
      description: "Build the swapAndBridge calldata server-side and return it for MetaMask to sign.\n\nBody schema:\n  Required:  evm_address, chain_id, usdc_address, bridge_amount\n  One of:    algo_address  (legacy field name, used for Algorand destination)\n             recipient_address  (preferred — works for any destination)\n\nReturns: { to, data, value } — pass directly to eth_sendTransaction.\n\nThe destination chain is taken from the tenant's xchain_destination_chain\nsetting; the frontend doesn't pass it (and shouldn't be allowed to,\nbecause that would let a hostile shopper redirect bridge inflow to a\ndifferent chain)."
      operationId: xchain_bridge_send_checkout__token__xchain_bridge_send_post
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /checkout/{token}/xchain/source-tx-recorded:
    post:
      tags:
      - checkout
      summary: Xchain Source Tx Recorded
      description: 'Called by the frontend immediately after MetaMask returns a tx hash for

        the swapAndBridge call. Records the source_tx_hash on the bridge-attempt

        row, advancing its state from `pending_signature` to `pending_bridge`.


        Body: { attempt_id: int, source_tx_hash: str }


        Idempotent: re-POSTing with the same source_tx_hash for the same

        attempt is a no-op. Mismatched source_tx_hash on a row that already has

        one is rejected with 400 — exactly one source tx per attempt.


        Per Comet review 2026-05-04 — without this, AlgoVoi can''t reconcile

        Allbridge''s destination tx back to the shopper''s checkout.'
      operationId: xchain_source_tx_recorded_checkout__token__xchain_source_tx_recorded_post
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /checkout/{token}/xchain/bridge-status/{tx_hash}:
    get:
      tags:
      - checkout
      summary: Xchain Bridge Status
      description: 'Poll Allbridge for cross-chain transfer completion + advance the

        bridge-attempt lifecycle.


        Reads `tx_hash` as the SOURCE-chain tx (the one MetaMask returned).

        Looks up the persisted attempt by source_tx_hash, polls Allbridge,

        and on completion records the destination tx hash on the attempt

        row so the verifier can run against the SPECIFIC dest tx (not "any

        matching tx in window").


        Idempotent — repeated polls only update DB state on transitions.'
      operationId: xchain_bridge_status_checkout__token__xchain_bridge_status__tx_hash__get
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      - name: tx_hash
        in: path
        required: true
        schema:
          type: string
          title: Tx Hash
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /checkout/{token}/xchain/prepare:
    post:
      tags:
      - checkout
      summary: Xchain Prepare
      description: 'Derive the Algorand LogicSig address for an EVM wallet and check funding.

        If sufficiently funded, builds the unsigned payment tx ready for EIP-712 signing.

        Body: { "evm_address": "0x..." }'
      operationId: xchain_prepare_checkout__token__xchain_prepare_post
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /checkout/{token}/xchain/prepare-optin:
    post:
      tags:
      - checkout
      summary: Xchain Prepare Optin
      description: 'Fund the LogicSig address from the platform sponsor wallet and build an

        unsigned USDCa opt-in transaction for EIP-712 signing.

        Body: { "evm_address": "0x..." }

        Returns: { "eip712_message": {...} }'
      operationId: xchain_prepare_optin_checkout__token__xchain_prepare_optin_post
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /checkout/{token}/xchain/optin-submit:
    post:
      tags:
      - checkout
      summary: Xchain Optin Submit
      description: 'Sign and submit the pending USDCa opt-in transaction.

        Body: { "evm_address": "0x...", "signature": "0x..." }

        Returns: { "optin_tx_id": "..." }'
      operationId: xchain_optin_submit_checkout__token__xchain_optin_submit_post
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /checkout/{token}/xchain/submit:
    post:
      tags:
      - checkout
      summary: Xchain Submit
      description: 'Sign and submit the pending xChain transaction using the EVM wallet''s EIP-712 signature.

        Body: { "evm_address": "0x...", "signature": "0x..." }

        Returns { "tx_id": "..." }'
      operationId: xchain_submit_checkout__token__xchain_submit_post
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /checkout/{token}/status:
    get:
      tags:
      - checkout
      summary: Checkout Status
      description: 'Polling endpoint — returns whether the link has been paid.


        Safe to call repeatedly; does not mutate state.

        Returns { "status": "active"|"paid"|"expired"|"cancelled", "redirect_url": str|null }'
      operationId: checkout_status_checkout__token__status_get
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /suite-store/checkout:
    post:
      tags:
      - suite-store
      summary: Suite Store Checkout
      description: Create a hosted-checkout payment link + a pending order keyed by the link token.
      operationId: suite_store_checkout_suite_store_checkout_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /suite-store/settled:
    post:
      tags:
      - suite-store
      summary: Suite Store Settled
      description: 'Inbound settlement webhook. Verify HMAC → fulfil → cache + email. Idempotent.


        Returns 200 once fulfilled (or already fulfilled / not-a-suite-order); 5xx on fulfilment failure

        so the outbound dispatcher redelivers with backoff.'
      operationId: suite_store_settled_suite_store_settled_post
      parameters:
      - name: x-algovoi-signature
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: X-Algovoi-Signature
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /suite-store/order/{token}/activate:
    post:
      tags:
      - suite-store
      summary: Suite Store Activate
      description: 'Bind a paid Agent Mesh entitlement to its holder''s agent DIDs and mint the licence.


        The mesh settles only for a PARTY to a transaction, so the licence must name its holder. We

        cannot know that at checkout, hence this step.


        Binding is near-permanent by design. Same DIDs => idempotent (re-fetch your licence). Different

        DIDs => a rebind, allowed only once every REBIND_COOLDOWN (see the constant): rare enough that no

        one can rebind per-counterparty to run a rail, frequent enough to rescue a lost key. A rebind

        re-mints the licence bound to the new DIDs under a fresh fulfilment ref and supersedes the old

        one in our records. The old licence is offline-verifiable, so this cannot claw back a *stolen*

        key already in another party''s hands — it restores control after a genuine loss.


        The read-then-write runs under SELECT … FOR UPDATE. Without that row lock two concurrent

        activations could both observe "not yet bound" and both mint, quietly defeating the whole

        control (a TOCTOU race). The lock is load-bearing security, not an optimisation.'
      operationId: suite_store_activate_suite_store_order__token__activate_post
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivateBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /suite-store/order/{token}/status:
    get:
      tags:
      - suite-store
      summary: Suite Store Order Status
      operationId: suite_store_order_status_suite_store_order__token__status_get
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /suite-store/mesh-fed/provision:
    post:
      tags:
      - mesh-federation
      summary: Provision
      description: 'Return ``{cert_b64, kid, expires_at, namespace, wheelhouse_hint}`` for a valid customer licence.


        403 if the licence is missing/expired/revoked/not entitled; 502 if fulfilment is unreachable.

        Rate-limited by the gateway''s global per-IP limiter; the licence check is the real control.'
      operationId: provision_suite_store_mesh_fed_provision_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProvisionRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Provision Suite Store Mesh Fed Provision Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /suite-store/mesh-fed/info:
    get:
      tags:
      - mesh-federation
      summary: Info
      description: Unauthenticated liveness probe the installer hits before provisioning.
      operationId: info_suite_store_mesh_fed_info_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Info Suite Store Mesh Fed Info Get
      x-payment-info:
        authMode: api_key
  /compliance/attestation:
    get:
      tags:
      - compliance
      summary: Attestation
      description: 'Return the gateway''s full compliance posture as a verifiable

        transparency surface. Free, no rate limit (cached server-side).'
      operationId: attestation_compliance_attestation_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      x-payment-info:
        authMode: none
  /compliance/screen:
    post:
      tags:
      - compliance
      summary: Screen
      description: Pre-payment recipient screen. Returns a SAMLA-compliant verdict.
      operationId: screen_compliance_screen_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScreenRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScreenResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: none
  /compliance/trust-query:
    post:
      tags:
      - compliance
      summary: Trust Query
      description: 'Composite trust verdict over a chain of substrate receipts.


        Submit decoded compliance receipts, settlement attestations, refund receipts,

        and/or cancellation receipts. Returns TRUSTED/PROVISIONAL/INSUFFICIENT_EVIDENCE/

        UNTRUSTED plus a content-addressed composite_hash and a signed CtqResponse.'
      operationId: trust_query_compliance_trust_query_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrustQueryRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrustQueryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /atb/license/activate:
    post:
      tags:
      - atb-license
      summary: Activate
      description: 'Issue a Falcon-signed activation token for an atb-zkp-service operator.


        The returned token must be verified by the container against the AlgoVoi

        license public key before the service will start. Tokens are bound to the

        operator''s DID and nonce — replay of a stolen token fails nonce validation

        on the container side.'
      operationId: activate_atb_license_activate_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivateRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /v1/receipt/verify:
    post:
      tags:
      - compliance
      summary: Verify a JWS compliance receipt
      description: Cryptographically verifies a compact JWS compliance receipt or settlement attestation. Checks signature, algorithm whitelist, canon_version registry, JCS re-canonicalisation, required fields, and optionally payment_hash binding.
      operationId: verify_receipt_v1_receipt_verify_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReceiptVerifyRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceiptVerifyResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /v1/receipt/settlement-evidence/{settled_payment_ref}:
    get:
      tags:
      - compliance
      summary: Fetch chain-evidence capture status (and bundle, when captured)
      description: Returns the settlement-evidence capture status for one of the calling tenant's settled payments, keyed on its content-addressed settled_payment_ref. When status is 'captured', includes chain_binding = {scheme, bundle_sha256, bundle} — an offline-verifiable avm-proofpack state-proof bundle. Only the owning tenant may fetch its evidence.
      operationId: get_settlement_evidence_v1_receipt_settlement_evidence__settled_payment_ref__get
      parameters:
      - name: settled_payment_ref
        in: path
        required: true
        schema:
          type: string
          title: Settled Payment Ref
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      - name: x-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Tenant-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementEvidenceResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /verify/action-ref:
    get:
      tags:
      - verify
      summary: action_ref verifier — schema and spec reference
      description: Return the input schema and spec reference for the action_ref verifier.
      operationId: action_ref_info_verify_action_ref_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      x-payment-info:
        authMode: api_key
    post:
      tags:
      - verify
      summary: Compute and verify an action_ref canonical hash
      description: 'Compute the canonical action_ref for the supplied payload.


        The canonical form is RFC 8785 JCS (keys sorted, no whitespace).

        The action_ref is SHA-256(canonical_bytes), lowercase hex.


        This is the same computation the AlgoVoi production stack applies

        before issuing a compliance receipt — any implementation that

        produces a different hash for the same input is non-conformant.'
      operationId: verify_action_ref_verify_action_ref_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionRefRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionRefResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /verify/rfc9421:
    get:
      tags:
      - verify
      summary: RFC 9421 verifier — schema and spec reference
      description: Return the input schema and spec reference for the RFC 9421 verifier.
      operationId: rfc9421_info_verify_rfc9421_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      x-payment-info:
        authMode: api_key
    post:
      tags:
      - verify
      summary: Verify an RFC 9421 HTTP Message Signature
      description: 'Verify an RFC 9421-signed HTTP request against an Ed25519 public key.


        Checks the Ed25519 signature over the reconstructed signing base and

        (optionally) verifies the Content-Digest header against the request body.'
      operationId: verify_rfc9421_verify_rfc9421_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Rfc9421VerifyRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rfc9421VerifyResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /discovery/resources:
    get:
      tags:
      - bazaar
      summary: Discovery Resources
      description: 'Return the Bazaar-shaped list of x402-payable resources on this

        facilitator. See module docstring for schema + scope.


        The Agent Trust Bench has its own Bazaar surface at

        https://agent-trust-bench.algovoi.co.uk/discovery/resources since

        the bench was extracted to its own service on VM4 (2026-05-09).

        This gateway''s catalog is now scoped to tenant resources only;

        bench resources are advertised by the bench''s own discovery

        endpoint as the canonical source. A `related_facilitators` hint

        points Bazaar crawlers at the bench so cross-facilitator

        discovery still works.'
      operationId: discovery_resources_discovery_resources_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      x-payment-info:
        authMode: none
  /r/{tenant_short_id}/{resource_id}:
    get:
      tags:
      - public-resource
      summary: Public Resource
      description: Public, tenant-scoped x402 resource endpoint. See module docstring.
      operationId: public_resource_r__tenant_short_id___resource_id__get
      parameters:
      - name: tenant_short_id
        in: path
        required: true
        schema:
          type: string
          title: Tenant Short Id
      - name: resource_id
        in: path
        required: true
        schema:
          type: string
          title: Resource Id
      - name: X-PAYMENT
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Payment
      - name: PAYMENT-SIGNATURE
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Payment-Signature
      - name: X-ATB-Credential
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Atb-Credential
      - name: X-ATB-ZK-Credential
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Atb-Zk-Credential
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '402':
          description: Payment Required
        '404':
          description: Resource not found
      minPrice: 10000
      maxPrice: 10000
      x-payment-info:
        authMode: payment
        protocols:
        - x402
        price:
          mode: fixed
          amount: '10000'
          currency: '0x20c000000000000000000000b9537d11c60e8b50'
  /signup/create:
    post:
      tags:
      - signup
      summary: Signup Proxy
      description: 'Proxy wallet signup request to control plane.


        Rate limited at 5/hour per real client IP (via X-Real-IP / X-Forwarded-For).

        This limit is the real enforcement point — the control_plane''s limiter sees

        only the gateway container IP so it''s a shared bucket.'
      operationId: signup_proxy_signup_create_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Body
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: none
  /cloud-signup/create:
    post:
      tags:
      - signup
      summary: Cloud Signup Proxy
      description: 'Proxy email/cloud signup request to control plane.


        Rate limited at 5/hour per real client IP — same enforcement as wallet signup.'
      operationId: cloud_signup_proxy_cloud_signup_create_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Body
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: none
  /mandate/pay:
    post:
      tags:
      - mandate
      summary: Mandate Pay
      description: 'Pay for a resource using a mandate JWT.


        The mandate JWT is passed as a standard HTTP Bearer token.

        No X-Tenant-Id header is required — mandate tokens are cross-tenant.


        On success, the mandate''s balance_minor is debited and an on-chain transfer

        from AlgoVoi''s hot wallet to the merchant is executed. The response contains

        a signed access_token granting access to the resource.'
      operationId: mandate_pay_mandate_pay_post
      parameters:
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MandatePayRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MandatePayResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /mandate/portal/{mandate_id}:
    get:
      tags:
      - mandate-portal
      summary: Get Mandate Portal
      description: 'Load public portal view for a mandate.


        Returns balance, status, JWT token (if active), and last 10 charges.

        The mandate_id is the user''s credential — treat it like an account number.'
      operationId: get_mandate_portal_mandate_portal__mandate_id__get
      parameters:
      - name: mandate_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Mandate Id
      - name: include_token
        in: query
        required: false
        schema:
          type: boolean
          description: Include JWT token in response
          default: true
          title: Include Token
        description: Include JWT token in response
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MandatePortalResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /mandate/portal/{mandate_id}/topup/initiate:
    post:
      tags:
      - mandate-portal
      summary: Portal Topup Initiate
      description: 'Initiate a PayPal top-up for a mandate.


        Returns an approval_url — redirect the user''s browser there.

        After approval, PayPal redirects to return_url with ?token=<paypal_order_id>.

        Then call POST /topup/capture with that token.'
      operationId: portal_topup_initiate_mandate_portal__mandate_id__topup_initiate_post
      parameters:
      - name: mandate_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Mandate Id
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TopupInitiateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopupInitiateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
  /mandate/portal/{mandate_id}/topup/capture:
    post:
      tags:
      - mandate-portal
      summary: Portal Topup Capture
      description: 'Capture a PayPal payment after buyer approval.


        Idempotent — safe to call again if the first attempt timed out.'
      operationId: portal_topup_capture_mandate_portal__mandate_id__topup_capture_post
      parameters:
      - name: mandate_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Mandate Id
      - name: token
        in: query
        required: true
        schema:
          type: string
          description: PayPal order token
          title: Token
        description: PayPal order token
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Tenant Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopupCaptureResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        authMode: api_key
components:
  schemas:
    AP2CartRequest:
      properties:
        intent_id:
          type: string
          format: uuid
          title: Intent Id
        mandate:
          $ref: '#/components/schemas/CartMandate'
      additionalProperties: false
      type: object
      required:
      - intent_id
      - mandate
      title: AP2CartRequest
      description: POST /ap2/cart — agent submits a merchant-signed CartMandate.
    AP2CartResponse:
      properties:
        cart_id:
          type: string
          title: Cart Id
        status:
          type: string
          enum:
          - locked
          - pending_user_confirmation
          title: Status
        expires_at:
          type: string
          title: Expires At
      additionalProperties: false
      type: object
      required:
      - cart_id
      - status
      - expires_at
      title: AP2CartResponse
    AP2ConfirmRequest:
      properties:
        payment_id:
          type: string
          format: uuid
          title: Payment Id
        tx_id:
          type: string
          maxLength: 128
          minLength: 1
          title: Tx Id
        network:
          type: string
          title: Network
      additionalProperties: false
      type: object
      required:
      - payment_id
      - tx_id
      - network
      title: AP2ConfirmRequest
      description: POST /ap2/confirm — agent confirms on-chain tx_id.
    AP2ConfirmResponse:
      properties:
        verified:
          type: boolean
          title: Verified
        access_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Access Token
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        settlement_attestation:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Settlement Attestation
        settlement_attestation_jws:
          anyOf:
          - type: string
          - type: 'null'
          title: Settlement Attestation Jws
      additionalProperties: false
      type: object
      required:
      - verified
      title: AP2ConfirmResponse
    AP2ExtensionInfo:
      properties:
        uri:
          type: string
          title: Uri
        name:
          type: string
          title: Name
        version:
          type: string
          title: Version
        description:
          type: string
          title: Description
      additionalProperties: false
      type: object
      required:
      - uri
      - name
      - version
      - description
      title: AP2ExtensionInfo
      description: Single extension entry for GET /ap2/extensions discovery response.
    AP2ExtensionsResponse:
      properties:
        ap2_version:
          type: string
          title: Ap2 Version
          default: '0.1'
        extensions:
          items:
            $ref: '#/components/schemas/AP2ExtensionInfo'
          type: array
          title: Extensions
      additionalProperties: false
      type: object
      required:
      - extensions
      title: AP2ExtensionsResponse
      description: GET /ap2/extensions — list of extensions this gateway supports.
    AP2IntentRequest:
      properties:
        mandate:
          $ref: '#/components/schemas/IntentMandate'
        user_authorization:
          anyOf:
          - type: string
          - type: 'null'
          title: User Authorization
          description: Optional base64url SD-JWT-VC authorizing the intent.
      additionalProperties: false
      type: object
      required:
      - mandate
      title: AP2IntentRequest
      description: POST /ap2/intent — agent submits a signed IntentMandate.
    AP2IntentResponse:
      properties:
        intent_id:
          type: string
          format: uuid
          title: Intent Id
        status:
          type: string
          const: accepted
          title: Status
          default: accepted
        expires_at:
          type: string
          title: Expires At
      additionalProperties: false
      type: object
      required:
      - expires_at
      title: AP2IntentResponse
    AP2PayRequest:
      properties:
        cart_id:
          type: string
          title: Cart Id
        mandate:
          $ref: '#/components/schemas/PaymentMandate'
      additionalProperties: false
      type: object
      required:
      - cart_id
      - mandate
      title: AP2PayRequest
      description: POST /ap2/pay — agent submits a PaymentMandate with user_authorization.
    AP2PayResponse:
      properties:
        payment_id:
          type: string
          format: uuid
          title: Payment Id
        network:
          type: string
          title: Network
        receiver:
          type: string
          title: Receiver
        amount_microunits:
          type: integer
          title: Amount Microunits
        price_token:
          type: string
          title: Price Token
        payment_reference:
          type: string
          title: Payment Reference
        cart_mandate_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: Cart Mandate Hash
      additionalProperties: false
      type: object
      required:
      - network
      - receiver
      - amount_microunits
      - price_token
      - payment_reference
      title: AP2PayResponse
      description: 'x402-style payment challenge returned to the agent.


        For AlgoVoi crypto payments, this echoes the crypto extension data

        (network, receiver, amount_microunits) so the agent can submit an

        on-chain transaction. The cart_mandate_hash is the RFC 8785 JCS hash

        of CartContents — the agent MUST include this in the tx note field

        for on-chain anchoring (enforced by the facilitator verify step).'
    AP2StatusResponse:
      properties:
        cart_id:
          type: string
          title: Cart Id
        intent_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Intent Id
        mandate_chain_status:
          type: string
          enum:
          - intent_accepted
          - cart_locked
          - pending_user_confirmation
          - payment_initiated
          - confirmed
          - expired
          - failed
          title: Mandate Chain Status
        network:
          anyOf:
          - type: string
          - type: 'null'
          title: Network
        tx_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Tx Id
        expires_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Expires At
      additionalProperties: false
      type: object
      required:
      - cart_id
      - mandate_chain_status
      title: AP2StatusResponse
      description: GET /ap2/status/{cart_id}
    ActionRefRequest:
      properties:
        agent_id:
          type: string
          title: Agent Id
          description: DID or URL identifying the agent (e.g. did:web:api.example.com)
        action_type:
          type: string
          title: Action Type
          description: Dot-namespaced action class (e.g. payment.authorize)
        scope:
          type: string
          title: Scope
          description: Chain-scoped target (e.g. base:0xabc...)
        timestamp_ms:
          type: integer
          title: Timestamp Ms
          description: Unix timestamp in integer milliseconds — NOT float
      type: object
      required:
      - agent_id
      - action_type
      - scope
      - timestamp_ms
      title: ActionRefRequest
    ActionRefResponse:
      properties:
        action_ref:
          type: string
          title: Action Ref
        canonical_json:
          type: string
          title: Canonical Json
        sha256_hex:
          type: string
          title: Sha256 Hex
        spec_ref:
          type: string
          title: Spec Ref
        canonicalization:
          type: string
          title: Canonicalization
        implementations_attested:
          type: integer
          title: Implementations Attested
        attestation_ref:
          type: string
          title: Attestation Ref
      type: object
      required:
      - action_ref
      - canonical_json
      - sha256_hex
      - spec_ref
      - canonicalization
      - implementations_attested
      - attestation_ref
      title: ActionRefResponse
    ActivateBody:
      properties:
        agent_dids:
          items:
            type: string
          type: array
          title: Agent Dids
      type: object
      required:
      - agent_dids
      title: ActivateBody
    ActivateRequest:
      properties:
        operator_did:
          type: string
          title: Operator Did
        nonce:
          type: string
          title: Nonce
      type: object
      required:
      - operator_did
      - nonce
      title: ActivateRequest
    ActivateResponse:
      properties:
        token:
          type: string
          title: Token
        expires_at:
          type: string
          title: Expires At
        license_kid:
          type: string
          title: License Kid
      type: object
      required:
      - token
      - expires_at
      - license_kid
      title: ActivateResponse
    Ap2VerifyRequest:
      properties:
        mandate:
          additionalProperties: true
          type: object
          title: Mandate
        merchant_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Merchant Id
        tenant_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Tenant Id
      type: object
      required:
      - mandate
      title: Ap2VerifyRequest
    Ap2VerifyResponse:
      properties:
        verified:
          type: boolean
          title: Verified
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
      type: object
      required:
      - verified
      title: Ap2VerifyResponse
    AuthorityConfirmRequest:
      properties:
        on_chain_address:
          type: string
          maxLength: 128
          minLength: 1
          title: On Chain Address
        first_cycle_due_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: First Cycle Due At
      additionalProperties: false
      type: object
      required:
      - on_chain_address
      title: AuthorityConfirmRequest
      description: 'POST /v1/recurring/authorities/{id}/confirm request body.


        Submitted after the customer signs the on-chain authorisation. Carries

        the on-chain identifier (e.g. ``app:12345`` for Algorand).'
    AuthorityCreate:
      properties:
        subscription_id:
          type: string
          format: uuid
          title: Subscription Id
        chain:
          type: string
          title: Chain
        customer_wallet_address:
          type: string
          maxLength: 128
          minLength: 1
          title: Customer Wallet Address
        cap_amount_minor:
          type: integer
          exclusiveMinimum: 0.0
          title: Cap Amount Minor
        cap_period_seconds:
          type: integer
          minimum: 86400.0
          title: Cap Period Seconds
        per_cycle_amount_minor:
          type: integer
          exclusiveMinimum: 0.0
          title: Per Cycle Amount Minor
        asset:
          type: string
          maxLength: 16
          minLength: 1
          title: Asset
          default: USDC
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
      additionalProperties: false
      type: object
      required:
      - subscription_id
      - chain
      - customer_wallet_address
      - cap_amount_minor
      - cap_period_seconds
      - per_cycle_amount_minor
      title: AuthorityCreate
      description: POST /v1/recurring/authorities request body.
    AuthorityCreateResponse:
      properties:
        authority:
          $ref: '#/components/schemas/AuthorityResponse'
        customer_signing_payload:
          additionalProperties: true
          type: object
          title: Customer Signing Payload
        authorisation_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorisation Url
      additionalProperties: true
      type: object
      required:
      - authority
      - customer_signing_payload
      title: AuthorityCreateResponse
      description: 'POST /v1/recurring/authorities response.


        Wraps the server-recorded authority + the chain-specific payload the

        customer''s wallet signs to land the authorisation on-chain.'
    AuthorityResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        tenant_id:
          type: string
          format: uuid
          title: Tenant Id
        subscription_id:
          type: string
          format: uuid
          title: Subscription Id
        chain:
          type: string
          title: Chain
        customer_wallet_address:
          type: string
          title: Customer Wallet Address
        on_chain_address:
          anyOf:
          - type: string
          - type: 'null'
          title: On Chain Address
        cap_amount_minor:
          type: integer
          title: Cap Amount Minor
        cap_period_seconds:
          type: integer
          title: Cap Period Seconds
        per_cycle_amount_minor:
          type: integer
          title: Per Cycle Amount Minor
        asset:
          type: string
          title: Asset
        facilitator_address:
          type: string
          title: Facilitator Address
        merchant_payout_address:
          type: string
          title: Merchant Payout Address
        status:
          type: string
          enum:
          - pending
          - active
          - depleted
          - revoked
          - paused
          - errored
          title: Status
        cap_remaining_minor:
          type: integer
          title: Cap Remaining Minor
        cycles_pulled:
          type: integer
          title: Cycles Pulled
        cycles_failed:
          type: integer
          title: Cycles Failed
        next_cycle_due_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Next Cycle Due At
        last_pull_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Pull At
        last_error:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Error
        created_at:
          type: string
          format: date-time
          title: Created At
        activated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Activated At
        revoked_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Revoked At
        expires_at:
          type: string
          format: date-time
          title: Expires At
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
      additionalProperties: true
      type: object
      required:
      - id
      - tenant_id
      - subscription_id
      - chain
      - customer_wallet_address
      - on_chain_address
      - cap_amount_minor
      - cap_period_seconds
      - per_cycle_amount_minor
      - asset
      - facilitator_address
      - merchant_payout_address
      - status
      - cap_remaining_minor
      - cycles_pulled
      - cycles_failed
      - next_cycle_due_at
      - last_pull_at
      - last_error
      - created_at
      - activated_at
      - revoked_at
      - expires_at
      - metadata
      title: AuthorityResponse
      description: Standard authority response. Returned by GET / POST creates.
    AuthorityResumeRequest:
      properties:
        next_cycle_due_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Next Cycle Due At
      additionalProperties: false
      type: object
      title: AuthorityResumeRequest
      description: POST /v1/recurring/authorities/{id}/resume request body.
    CancelCheckoutRequest:
      properties:
        cancel_secret:
          type: string
          maxLength: 128
          minLength: 1
          title: Cancel Secret
      type: object
      required:
      - cancel_secret
      title: CancelCheckoutRequest
      description: 'Body for POST /checkout/{token}/cancel (gateway-side).


        F5 security fix: the cancel endpoint now requires cancel_secret so that

        only the merchant (who received cancel_secret at link-creation time) can

        cancel a link programmatically. Customers use the in-browser ''abandon''

        flow which navigates them away without touching the backend.'
    CancelSubscriptionBody:
      properties:
        at_period_end:
          type: boolean
          title: At Period End
          default: false
      type: object
      title: CancelSubscriptionBody
    CartContents:
      properties:
        id:
          type: string
          title: Id
          description: A unique identifier for this cart.
        user_cart_confirmation_required:
          type: boolean
          title: User Cart Confirmation Required
          description: If true, the merchant requires the user to confirm the cart before the purchase can be completed.
        payment_request:
          $ref: '#/components/schemas/PaymentRequest'
          description: The W3C PaymentRequest object to initiate payment. This contains the items being purchased, prices, and the set of payment methods accepted by the merchant for this cart.
        cart_expiry:
          type: string
          title: Cart Expiry
          description: When this cart expires, in ISO 8601 format.
        merchant_name:
          type: string
          title: Merchant Name
          description: The name of the merchant.
      type: object
      required:
      - id
      - user_cart_confirmation_required
      - payment_request
      - cart_expiry
      - merchant_name
      title: CartContents
      description: 'The detailed contents of a cart.


        This object is signed by the merchant to create a CartMandate (the

        signature travels in CartMandate.merchant_authorization as a base64url JWT).


        Spec source: ap2/types/mandate.py'
    CartMandate:
      properties:
        contents:
          $ref: '#/components/schemas/CartContents'
          description: The contents of the cart.
        merchant_authorization:
          anyOf:
          - type: string
          - type: 'null'
          title: Merchant Authorization
          description: 'A base64url-encoded JSON Web Token (JWT) that digitally signs the cart contents. Header: alg + kid. Payload: iss, sub, aud, iat, exp, jti, cart_hash (RFC 8785 JCS hash of CartContents).'
      type: object
      required:
      - contents
      title: CartMandate
      description: 'A cart whose contents have been digitally signed by the merchant.


        merchant_authorization is a base64url-encoded JWT (typically RS256) with

        claims: iss, sub, aud, iat, exp (5-15 min), jti, cart_hash. The cart_hash

        is computed via RFC 8785 JCS over CartContents.


        Spec source: ap2/types/mandate.py'
    ChainBinding:
      properties:
        scheme:
          type: string
          title: Scheme
          default: avm-proofpack/1
        bundle_sha256:
          type: string
          title: Bundle Sha256
          description: sha256 hex of the canonical bundle file bytes
        bundle:
          additionalProperties: true
          type: object
          title: Bundle
          description: The avm-proofpack state-proof evidence bundle
      type: object
      required:
      - bundle_sha256
      - bundle
      title: ChainBinding
      description: Offline-verifiable chain evidence for a settled payment.
    ChargeItemPublic:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        amount_minor:
          type: integer
          title: Amount Minor
        currency:
          type: string
          title: Currency
        chain:
          anyOf:
          - type: string
          - type: 'null'
          title: Chain
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        status:
          type: string
          title: Status
        charged_at:
          type: string
          format: date-time
          title: Charged At
      type: object
      required:
      - id
      - amount_minor
      - currency
      - chain
      - description
      - status
      - charged_at
      title: ChargeItemPublic
    CheckoutBody:
      properties:
        package:
          type: string
          title: Package
        email:
          type: string
          title: Email
        accepted_terms:
          type: boolean
          title: Accepted Terms
          default: false
        network:
          type: string
          title: Network
          default: ''
        term:
          type: string
          title: Term
          default: perpetual
      type: object
      required:
      - package
      - email
      title: CheckoutBody
    CheckoutVerifyRequest:
      properties:
        tx_id:
          type: string
          maxLength: 100
          minLength: 10
          title: Tx Id
        chain:
          anyOf:
          - type: string
          - type: 'null'
          title: Chain
      type: object
      required:
      - tx_id
      title: CheckoutVerifyRequest
      description: Body for POST /checkout/{token}/verify (gateway-side, unauthenticated).
    CheckoutVerifyResponse:
      properties:
        payment_ledger_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Payment Ledger Id
        status:
          type: string
          title: Status
        redirect_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Redirect Url
        settlement_attestation:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Settlement Attestation
        settlement_attestation_jws:
          anyOf:
          - type: string
          - type: 'null'
          title: Settlement Attestation Jws
      type: object
      required:
      - status
      title: CheckoutVerifyResponse
      description: Successful verification response.
    ContactAddress:
      properties:
        country:
          anyOf:
          - type: string
          - type: 'null'
          title: Country
        address_line:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Address Line
        region:
          anyOf:
          - type: string
          - type: 'null'
          title: Region
        city:
          anyOf:
          - type: string
          - type: 'null'
          title: City
        dependent_locality:
          anyOf:
          - type: string
          - type: 'null'
          title: Dependent Locality
        postal_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Postal Code
        sorting_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Sorting Code
        organization:
          anyOf:
          - type: string
          - type: 'null'
          title: Organization
        recipient:
          anyOf:
          - type: string
          - type: 'null'
          title: Recipient
        phone:
          anyOf:
          - type: string
          - type: 'null'
          title: Phone
      type: object
      title: ContactAddress
      description: 'Subset of W3C ContactAddress used by AP2 for shipping + payer info.


        Spec: https://www.w3.org/TR/contact-picker/#contactaddress'
    CustomerCreate:
      properties:
        email:
          anyOf:
          - type: string
            format: email
          - type: 'null'
          title: Email
        wallet_address:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: Wallet Address
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
      additionalProperties: false
      type: object
      title: CustomerCreate
    CustomerRef:
      properties:
        email:
          anyOf:
          - type: string
            format: email
          - type: 'null'
          title: Email
        wallet_address:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: Wallet Address
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
      additionalProperties: false
      type: object
      title: CustomerRef
      description: 'Embedded customer ref accepted by subscription create. Either email or

        wallet_address is required; both is fine.'
    CustomerResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        tenant_id:
          type: string
          format: uuid
          title: Tenant Id
        email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
        wallet_address:
          anyOf:
          - type: string
          - type: 'null'
          title: Wallet Address
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
        created_at:
          type: string
          format: date-time
          title: Created At
        deleted_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Deleted At
      type: object
      required:
      - id
      - tenant_id
      - email
      - wallet_address
      - metadata
      - created_at
      - deleted_at
      title: CustomerResponse
    DynamicPaymentLinkCreate:
      properties:
        amount:
          type: number
          exclusiveMinimum: 0.0
          title: Amount
          description: Amount in major currency units, e.g. 49.99 for £49.99
        currency:
          type: string
          maxLength: 3
          minLength: 3
          title: Currency
          description: ISO 4217 currency code, e.g. GBP
        label:
          type: string
          maxLength: 255
          minLength: 1
          title: Label
          description: Item / order description shown on the checkout page
        preferred_network:
          anyOf:
          - type: string
          - type: 'null'
          title: Preferred Network
          description: Force a specific network, e.g. 'algorand_mainnet'. Defaults to the tenant's first configured network.
        redirect_url:
          anyOf:
          - type: string
            maxLength: 2048
          - type: 'null'
          title: Redirect Url
          description: URL to redirect the buyer to after payment is confirmed
        expires_in_seconds:
          type: integer
          maximum: 86400.0
          minimum: 60.0
          title: Expires In Seconds
          description: 'Link lifetime in seconds (60–86400). Default: 86400 (24 h).'
          default: 86400
      type: object
      required:
      - amount
      - currency
      - label
      title: DynamicPaymentLinkCreate
    DynamicPaymentLinkResponse:
      properties:
        id:
          type: string
          title: Id
        token:
          type: string
          title: Token
        checkout_url:
          type: string
          title: Checkout Url
        amount_microunits:
          type: integer
          title: Amount Microunits
        asset_id:
          type: string
          title: Asset Id
        chain:
          type: string
          title: Chain
        label:
          anyOf:
          - type: string
          - type: 'null'
          title: Label
        expires_at:
          type: string
          format: date-time
          title: Expires At
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - token
      - checkout_url
      - amount_microunits
      - asset_id
      - chain
      - label
      - expires_at
      - created_at
      title: DynamicPaymentLinkResponse
    FailedPaymentPolicy:
      properties:
        max_retries:
          type: integer
          maximum: 20.0
          minimum: 0.0
          title: Max Retries
          default: 3
        intervals_hours:
          items:
            type: integer
          type: array
          title: Intervals Hours
        on_fail:
          type: string
          enum:
          - cancel
          - past_due
          title: On Fail
          default: cancel
      additionalProperties: false
      type: object
      title: FailedPaymentPolicy
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    HostedAuthConfirmRequest:
      properties:
        on_chain_address:
          type: string
          maxLength: 200
          minLength: 1
          title: On Chain Address
        on_chain_tx_id:
          anyOf:
          - type: string
            maxLength: 1000
          - type: 'null'
          title: On Chain Tx Id
        first_cycle_due_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: First Cycle Due At
      type: object
      required:
      - on_chain_address
      title: HostedAuthConfirmRequest
    HostedAuthConfirmResponse:
      properties:
        authority_id:
          type: string
          format: uuid
          title: Authority Id
        status:
          type: string
          title: Status
        on_chain_address:
          type: string
          title: On Chain Address
        activated_at:
          type: string
          format: date-time
          title: Activated At
        redirect_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Redirect Url
      type: object
      required:
      - authority_id
      - status
      - on_chain_address
      - activated_at
      title: HostedAuthConfirmResponse
    HostedAuthMerchant:
      properties:
        name:
          type: string
          title: Name
          description: Merchant display name
        logo_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Logo Url
          description: Merchant logo, if uploaded
        brand_primary_color:
          anyOf:
          - type: string
          - type: 'null'
          title: Brand Primary Color
          description: 'Hex colour, e.g. #3b82f6'
        contact_email:
          anyOf:
          - type: string
          - type: 'null'
          title: Contact Email
          description: Customer support contact
      type: object
      required:
      - name
      title: HostedAuthMerchant
      description: Subset of merchant info safe to expose on a public endpoint.
    HostedAuthResolveResponse:
      properties:
        authority_id:
          type: string
          format: uuid
          title: Authority Id
        chain:
          type: string
          title: Chain
        cap_amount_minor:
          type: integer
          title: Cap Amount Minor
        cap_period_seconds:
          type: integer
          title: Cap Period Seconds
        per_cycle_amount_minor:
          type: integer
          title: Per Cycle Amount Minor
        asset:
          type: string
          title: Asset
        customer_wallet_address:
          type: string
          title: Customer Wallet Address
        facilitator_address:
          type: string
          title: Facilitator Address
        merchant_payout_address:
          type: string
          title: Merchant Payout Address
        expires_at:
          type: string
          format: date-time
          title: Expires At
        customer_signing_payload:
          additionalProperties: true
          type: object
          title: Customer Signing Payload
        merchant:
          $ref: '#/components/schemas/HostedAuthMerchant'
        redirect_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Redirect Url
      type: object
      required:
      - authority_id
      - chain
      - cap_amount_minor
      - cap_period_seconds
      - per_cycle_amount_minor
      - asset
      - customer_wallet_address
      - facilitator_address
      - merchant_payout_address
      - expires_at
      - customer_signing_payload
      - merchant
      title: HostedAuthResolveResponse
    IntentMandate:
      properties:
        user_cart_confirmation_required:
          type: boolean
          title: User Cart Confirmation Required
          description: If false, the agent can make purchases on the user's behalf once all purchase conditions have been satisfied. This must be true if the intent mandate is not signed by the user.
          default: true
        natural_language_description:
          type: string
          title: Natural Language Description
          description: The natural language description of the user's intent. This is generated by the shopping agent, and confirmed by the user. The goal is to have informed consent by the user.
        merchants:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Merchants
          description: Merchants allowed to fulfill the intent. If not set, the shopping agent is able to work with any suitable merchant.
        skus:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Skus
          description: A list of specific product SKUs. If not set, any SKU is allowed.
        requires_refundability:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Requires Refundability
          description: If true, items must be refundable.
          default: false
        intent_expiry:
          type: string
          title: Intent Expiry
          description: When the intent mandate expires, in ISO 8601 format.
      type: object
      required:
      - natural_language_description
      - intent_expiry
      title: IntentMandate
      description: 'Represents the user''s purchase intent.


        For human-present flows this contains the core shopping bounds. For

        human-not-present flows additional fields will be added in future spec

        versions.


        Spec source: ap2/types/mandate.py'
    MandatePayRequest:
      properties:
        tenant_id:
          type: string
          format: uuid
          title: Tenant Id
          description: UUID of the merchant tenant
        resource_id:
          type: string
          format: uuid
          title: Resource Id
          description: UUID of the resource to pay for
        max_amount_minor:
          type: integer
          minimum: 0.0
          title: Max Amount Minor
          description: Agent-supplied spending ceiling in GBP pence (self-guard). 0 = no agent cap (mandate's own balance/period cap still applies).
          default: 0
        description:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: Description
          description: Optional human-readable label for the charge ledger
      type: object
      required:
      - tenant_id
      - resource_id
      title: MandatePayRequest
    MandatePayResponse:
      properties:
        charge_id:
          type: string
          title: Charge Id
        amount_minor:
          type: integer
          title: Amount Minor
        currency:
          type: string
          title: Currency
        tx_id:
          type: string
          title: Tx Id
        chain:
          type: string
          title: Chain
        remaining_balance_minor:
          type: integer
          title: Remaining Balance Minor
        access_token:
          type: string
          title: Access Token
      type: object
      required:
      - charge_id
      - amount_minor
      - currency
      - tx_id
      - chain
      - remaining_balance_minor
      - access_token
      title: MandatePayResponse
    MandatePortalResponse:
      properties:
        mandate_id:
          type: string
          format: uuid
          title: Mandate Id
        display_name:
          type: string
          title: Display Name
        balance_minor:
          type: integer
          title: Balance Minor
        currency:
          type: string
          title: Currency
        period:
          type: string
          title: Period
        period_cap_minor:
          type: integer
          title: Period Cap Minor
        period_spent_minor:
          type: integer
          title: Period Spent Minor
        status:
          type: string
          title: Status
        token:
          anyOf:
          - type: string
          - type: 'null'
          title: Token
        created_at:
          type: string
          format: date-time
          title: Created At
        expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Expires At
        recent_charges:
          items:
            $ref: '#/components/schemas/ChargeItemPublic'
          type: array
          title: Recent Charges
      type: object
      required:
      - mandate_id
      - display_name
      - balance_minor
      - currency
      - period
      - period_cap_minor
      - period_spent_minor
      - status
      - created_at
      - expires_at
      - recent_charges
      title: MandatePortalResponse
    MppChallengeRequest:
      properties:
        resource_id:
          type: string
          title: Resource Id
        network:
          anyOf:
          - type: string
          - type: 'null'
          title: Network
      type: object
      required:
      - resource_id
      title: MppChallengeRequest
    MppChallengeResponse:
      properties:
        challenge:
          additionalProperties: true
          type: object
          title: Challenge
        accepts:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Accepts
      type: object
      required:
      - challenge
      - accepts
      title: MppChallengeResponse
    MppVerifyRequest:
      properties:
        tx_id:
          type: string
          title: Tx Id
        network:
          type: string
          title: Network
        resource_id:
          type: string
          title: Resource Id
        tenant_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Tenant Id
      type: object
      required:
      - tx_id
      - network
      - resource_id
      title: MppVerifyRequest
    MppVerifyResponse:
      properties:
        verified:
          type: boolean
          title: Verified
        payer:
          type: string
          title: Payer
          default: ''
        amount:
          type: integer
          title: Amount
          default: 0
        receipt:
          type: string
          title: Receipt
          default: ''
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
      type: object
      required:
      - verified
      title: MppVerifyResponse
    PaymentCurrencyAmount:
      properties:
        currency:
          type: string
          title: Currency
          description: Three-letter ISO 4217 currency code.
        value:
          type: number
          title: Value
          description: The monetary value.
      type: object
      required:
      - currency
      - value
      title: PaymentCurrencyAmount
      description: 'W3C PaymentCurrencyAmount — monetary value with ISO 4217 currency code.


        Spec: https://www.w3.org/TR/payment-request/#dom-paymentcurrencyamount'
    PaymentDetailsInit:
      properties:
        id:
          type: string
          title: Id
          description: Unique identifier for the payment request.
        display_items:
          items:
            $ref: '#/components/schemas/PaymentItem'
          type: array
          title: Display Items
          description: Items displayed to the user.
        shipping_options:
          anyOf:
          - items:
              $ref: '#/components/schemas/PaymentShippingOption'
            type: array
          - type: 'null'
          title: Shipping Options
        modifiers:
          anyOf:
          - items:
              $ref: '#/components/schemas/PaymentDetailsModifier'
            type: array
          - type: 'null'
          title: Modifiers
        total:
          $ref: '#/components/schemas/PaymentItem'
          description: The total payment amount.
      type: object
      required:
      - id
      - display_items
      - total
      title: PaymentDetailsInit
      description: 'W3C PaymentDetailsInit — the details of the payment being requested.


        Spec: https://www.w3.org/TR/payment-request/#dom-paymentdetailsinit'
    PaymentDetailsModifier:
      properties:
        supported_methods:
          type: string
          title: Supported Methods
          description: The payment method ID that this modifier applies to.
        total:
          anyOf:
          - $ref: '#/components/schemas/PaymentItem'
          - type: 'null'
          description: Overrides the original item total.
        additional_display_items:
          anyOf:
          - items:
              $ref: '#/components/schemas/PaymentItem'
            type: array
          - type: 'null'
          title: Additional Display Items
        data:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Data
      type: object
      required:
      - supported_methods
      title: PaymentDetailsModifier
      description: 'W3C PaymentDetailsModifier — method-specific price adjustments.


        Spec: https://www.w3.org/TR/payment-request/#dom-paymentdetailsmodifier'
    PaymentItem:
      properties:
        label:
          type: string
          title: Label
          description: Human-readable description of the item.
        amount:
          $ref: '#/components/schemas/PaymentCurrencyAmount'
          description: The monetary amount of the item.
        pending:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Pending
          description: If true, the amount is not final.
        refund_period:
          type: integer
          title: Refund Period
          description: The refund duration for this item, in days.
          default: 30
      type: object
      required:
      - label
      - amount
      title: PaymentItem
      description: 'W3C PaymentItem — an item for purchase and its price.


        Spec: https://www.w3.org/TR/payment-request/#dom-paymentitem'
    PaymentMandate:
      properties:
        payment_mandate_contents:
          $ref: '#/components/schemas/PaymentMandateContents'
          description: The data contents of the payment mandate.
        user_authorization:
          anyOf:
          - type: string
          - type: 'null'
          title: User Authorization
          description: Base64url-encoded SD-JWT-VC verifiable presentation binding the user's consent to the CartMandate + PaymentMandateContents hashes via a key-binding JWT's transaction_data claim.
      type: object
      required:
      - payment_mandate_contents
      title: PaymentMandate
      description: 'User''s instructions and authorization for payment.


        user_authorization is a base64url-encoded SD-JWT-VC (Selective Disclosure

        Verifiable Credential) containing an issuer-signed JWT authorizing a ''cnf''

        claim and a key-binding JWT with transaction_data including the hashes of

        CartMandate and PaymentMandateContents (RFC 8785 JCS).


        Spec source: ap2/types/mandate.py'
    PaymentMandateContents:
      properties:
        payment_mandate_id:
          type: string
          title: Payment Mandate Id
          description: Unique identifier for this payment mandate.
        payment_details_id:
          type: string
          title: Payment Details Id
          description: Unique identifier for the payment request.
        payment_details_total:
          $ref: '#/components/schemas/PaymentItem'
          description: The total payment amount.
        payment_response:
          $ref: '#/components/schemas/PaymentResponse'
          description: The payment response containing details of the chosen payment method.
        merchant_agent:
          type: string
          title: Merchant Agent
          description: Identifier for the merchant.
        timestamp:
          type: string
          title: Timestamp
          description: Creation time of the mandate, in ISO 8601 format.
      type: object
      required:
      - payment_mandate_id
      - payment_details_id
      - payment_details_total
      - payment_response
      - merchant_agent
      title: PaymentMandateContents
      description: 'The data contents of a PaymentMandate.


        Spec source: ap2/types/mandate.py'
    PaymentMethodData:
      properties:
        supported_methods:
          type: string
          title: Supported Methods
          description: A string identifying the payment method.
        data:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Data
          description: Payment method specific details.
      type: object
      required:
      - supported_methods
      title: PaymentMethodData
      description: 'W3C PaymentMethodData — identifies a payment method and method-specific data.


        For AlgoVoi crypto payments, `supported_methods` is set to the AlgoVoi

        crypto extension URI (https://api.algovoi.co.uk/ap2/extensions/crypto-algo/v1)

        and `data` contains the CryptoPaymentDetails struct (see ap2_ext_crypto.py).


        Spec: https://www.w3.org/TR/payment-request/#dom-paymentmethoddata'
    PaymentOptions:
      properties:
        request_payer_name:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Request Payer Name
          default: false
        request_payer_email:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Request Payer Email
          default: false
        request_payer_phone:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Request Payer Phone
          default: false
        request_shipping:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Request Shipping
          default: true
        shipping_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Shipping Type
          description: '`shipping`, `delivery`, or `pickup`.'
      type: object
      title: PaymentOptions
      description: 'W3C PaymentOptions — which payer details to collect.


        Spec: https://www.w3.org/TR/payment-request/#dom-paymentoptions'
    PaymentRequest:
      properties:
        method_data:
          items:
            $ref: '#/components/schemas/PaymentMethodData'
          type: array
          title: Method Data
          description: Supported payment methods.
        details:
          $ref: '#/components/schemas/PaymentDetailsInit'
          description: Financial details of the transaction.
        options:
          anyOf:
          - $ref: '#/components/schemas/PaymentOptions'
          - type: 'null'
        shipping_address:
          anyOf:
          - $ref: '#/components/schemas/ContactAddress'
          - type: 'null'
      type: object
      required:
      - method_data
      - details
      title: PaymentRequest
      description: 'W3C PaymentRequest — the top-level request for payment.


        Spec: https://www.w3.org/TR/payment-request/#paymentrequest-interface'
    PaymentResponse:
      properties:
        request_id:
          type: string
          title: Request Id
          description: Unique ID from the original PaymentRequest.
        method_name:
          type: string
          title: Method Name
          description: The payment method chosen by the user.
        details:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Details
          description: Payment-method-specific transaction data.
        shipping_address:
          anyOf:
          - $ref: '#/components/schemas/ContactAddress'
          - type: 'null'
        shipping_option:
          anyOf:
          - $ref: '#/components/schemas/PaymentShippingOption'
          - type: 'null'
        payer_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Payer Name
        payer_email:
          anyOf:
          - type: string
          - type: 'null'
          title: Payer Email
        payer_phone:
          anyOf:
          - type: string
          - type: 'null'
          title: Payer Phone
      type: object
      required:
      - request_id
      - method_name
      title: PaymentResponse
      description: 'W3C PaymentResponse — user''s chosen payment method + approval.


        For AlgoVoi crypto payments, `details` contains a CryptoPaymentResponse

        struct (see ap2_ext_crypto.py) with tx_id, network, and note field.


        Spec: https://www.w3.org/TR/payment-request/#paymentresponse-interface'
    PaymentShippingOption:
      properties:
        id:
          type: string
          title: Id
          description: Unique identifier for the shipping option.
        label:
          type: string
          title: Label
          description: Human-readable description.
        amount:
          $ref: '#/components/schemas/PaymentCurrencyAmount'
          description: Cost of this shipping option.
        selected:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Selected
          description: If true, the default option.
          default: false
      type: object
      required:
      - id
      - label
      - amount
      title: PaymentShippingOption
      description: 'W3C PaymentShippingOption.


        Spec: https://www.w3.org/TR/payment-request/#dom-paymentshippingoption'
    PayoutCreate:
      properties:
        to_address:
          type: string
          maxLength: 128
          minLength: 1
          title: To Address
          description: Destination wallet address
        amount:
          type: number
          exclusiveMinimum: 0.0
          title: Amount
          description: Amount in major currency units, e.g. 9.90
        currency:
          type: string
          maxLength: 3
          minLength: 3
          title: Currency
          description: ISO 4217 — must be USD for now
        network:
          type: string
          title: Network
          description: Target chain, e.g. algorand_mainnet
        reference:
          type: string
          maxLength: 256
          minLength: 1
          title: Reference
          description: Caller idempotency key
      type: object
      required:
      - to_address
      - amount
      - currency
      - network
      - reference
      title: PayoutCreate
    PayoutCreateResponse:
      properties:
        payout_id:
          type: string
          title: Payout Id
        tx_id:
          type: string
          title: Tx Id
        network:
          type: string
          title: Network
        amount_usd_cents:
          type: integer
          title: Amount Usd Cents
        status:
          type: string
          title: Status
      type: object
      required:
      - payout_id
      - tx_id
      - network
      - amount_usd_cents
      - status
      title: PayoutCreateResponse
    ProvisionRequest:
      properties:
        license_key:
          type: string
          title: License Key
        fed_pub_b64:
          type: string
          title: Fed Pub B64
        namespace:
          type: string
          title: Namespace
        federation_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Federation Id
        ttl_secs:
          type: integer
          title: Ttl Secs
          default: 157680000
      type: object
      required:
      - license_key
      - fed_pub_b64
      - namespace
      title: ProvisionRequest
    PullCreate:
      properties:
        authority_id:
          type: string
          format: uuid
          title: Authority Id
        amount_minor:
          type: integer
          exclusiveMinimum: 0.0
          title: Amount Minor
        note:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Note
      additionalProperties: false
      type: object
      required:
      - authority_id
      - amount_minor
      title: PullCreate
      description: POST /v1/recurring/pulls request body — manual pull trigger.
    ReceiptVerifyRequest:
      properties:
        jws:
          type: string
          title: Jws
          description: Compact JWS string (header.payload.signature) as returned by /compliance/screen (compliance_receipt_jws field) or /verify (settlement_attestation_jws field).
        expected_payment_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: Expected Payment Hash
          description: 'If supplied, the receipt''s payment_hash field must equal this value. Use to bind a receipt to a specific transaction. Format: ''sha256:<hex>''.'
        receipt_required:
          type: boolean
          title: Receipt Required
          description: If True, treat a missing JWS as a MISSING_ENVELOPE error rather than a format error.
          default: false
        jwks:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Jwks
          description: 'Optional external JWKS dict ({''keys'': [...]}) for verifying receipts signed by a third-party provider. If omitted, AlgoVoi''s own platform key is used.'
      type: object
      required:
      - jws
      title: ReceiptVerifyRequest
      description: Request body for POST /v1/receipt/verify.
    ReceiptVerifyResponse:
      properties:
        verified:
          type: boolean
          title: Verified
        error_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Code
        error_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Message
        error_field:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Field
        screen_result:
          anyOf:
          - type: string
          - type: 'null'
          title: Screen Result
        settlement_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Settlement Status
        canon_version:
          anyOf:
          - type: string
          - type: 'null'
          title: Canon Version
        alg:
          anyOf:
          - type: string
          - type: 'null'
          title: Alg
        kid:
          anyOf:
          - type: string
          - type: 'null'
          title: Kid
        screen_provider_did:
          anyOf:
          - type: string
          - type: 'null'
          title: Screen Provider Did
        payer_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Payer Ref
        payment_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: Payment Hash
      type: object
      required:
      - verified
      title: ReceiptVerifyResponse
      description: Verification result.
    ResourceResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        resource_id:
          type: string
          title: Resource Id
        networks:
          items:
            type: string
          type: array
          title: Networks
        amount_microunits:
          type: integer
          title: Amount Microunits
        asset_id:
          anyOf:
          - type: integer
          - type: string
          - type: 'null'
          title: Asset Id
        access_ttl_secs:
          type: integer
          title: Access Ttl Secs
        requirement_ttl_secs:
          type: integer
          title: Requirement Ttl Secs
        note_binding_required:
          type: boolean
          title: Note Binding Required
        is_active:
          type: boolean
          title: Is Active
        price_microalgos:
          type: integer
          title: Price Microalgos
          default: 1000000
        payment_network:
          type: string
          title: Payment Network
          default: algorand_mainnet
        price_fiat_cents:
          anyOf:
          - type: integer
          - type: 'null'
          title: Price Fiat Cents
        price_fiat_currency:
          anyOf:
          - type: string
          - type: 'null'
          title: Price Fiat Currency
      type: object
      required:
      - id
      - resource_id
      - networks
      - amount_microunits
      - access_ttl_secs
      - requirement_ttl_secs
      - note_binding_required
      - is_active
      title: ResourceResponse
    Rfc9421VerifyRequest:
      properties:
        method:
          type: string
          title: Method
          description: HTTP method (e.g. POST)
        authority:
          type: string
          title: Authority
          description: HTTP authority (host[:port])
        path:
          type: string
          title: Path
          description: Request path + query (e.g. /checkout?token=abc)
        scheme:
          type: string
          title: Scheme
          description: URI scheme
          default: https
        headers:
          additionalProperties:
            type: string
          type: object
          title: Headers
          description: All HTTP headers as a flat dict (lowercase keys). Must include 'signature-input' and 'signature'. Include 'content-digest' when require_content_digest=true.
        body_b64:
          type: string
          title: Body B64
          description: Request body, base64-encoded. Empty string for requests with no body.
          default: ''
        public_key_hex:
          type: string
          title: Public Key Hex
          description: Ed25519 public key as 64-char hex (32 bytes). Must match the keyid used when signing.
        require_content_digest:
          type: boolean
          title: Require Content Digest
          description: If true, verify Content-Digest header against the body. Set false for GET/HEAD requests.
          default: true
        mode:
          type: string
          title: Mode
          description: '''rfc9421'' (default) for RFC 9421 §2.5 compliant signing base. ''algovoi-v0'' for legacy format used in rfc9421_proxy_chain_v0 conformance vectors.'
          default: rfc9421
      type: object
      required:
      - method
      - authority
      - path
      - headers
      - public_key_hex
      title: Rfc9421VerifyRequest
    Rfc9421VerifyResponse:
      properties:
        valid:
          type: boolean
          title: Valid
        signature_valid:
          type: boolean
          title: Signature Valid
        content_digest_valid:
          type: boolean
          title: Content Digest Valid
        signing_base:
          type: string
          title: Signing Base
        covered_components:
          items:
            type: string
          type: array
          title: Covered Components
        parameters:
          additionalProperties: true
          type: object
          title: Parameters
        label:
          type: string
          title: Label
        errors:
          items:
            type: string
          type: array
          title: Errors
        spec_ref:
          type: string
          title: Spec Ref
        digest_spec_ref:
          type: string
          title: Digest Spec Ref
      type: object
      required:
      - valid
      - signature_valid
      - content_digest_valid
      - signing_base
      - covered_components
      - parameters
      - label
      - errors
      - spec_ref
      - digest_spec_ref
      title: Rfc9421VerifyResponse
    ScreenRequest:
      properties:
        recipient_address:
          type: string
          maxLength: 128
          minLength: 4
          title: Recipient Address
        network:
          type: string
          maxLength: 64
          minLength: 4
          title: Network
        amount_microunits:
          anyOf:
          - type: integer
            minimum: 0.0
          - type: 'null'
          title: Amount Microunits
        asset:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Asset
      type: object
      required:
      - recipient_address
      - network
      title: ScreenRequest
    ScreenResponse:
      properties:
        verdict:
          type: string
          enum:
          - allow
          - block
          - flag
          title: Verdict
        sanctions_clear:
          type: boolean
          title: Sanctions Clear
        recipient_kyb_status:
          type: string
          enum:
          - unknown
          - trial
          - approved
          - rejected
          title: Recipient Kyb Status
        risk_tier:
          type: string
          enum:
          - low
          - medium
          - high
          - restricted
          - unknown
          title: Risk Tier
        reasons:
          items:
            type: string
          type: array
          title: Reasons
        screened_at:
          type: string
          title: Screened At
        verdict_id:
          type: string
          title: Verdict Id
        network_normalised:
          type: string
          title: Network Normalised
        tipping_off_notice:
          type: string
          title: Tipping Off Notice
          default: Reasons are intentionally generic. We do not disclose which sanctions list (if any) matched — SAMLA 2018 s.20.
        action_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Action Ref
        compliance_receipt:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Compliance Receipt
        compliance_receipt_jws:
          anyOf:
          - type: string
          - type: 'null'
          title: Compliance Receipt Jws
        compliance_receipt_pef:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Compliance Receipt Pef
        compliance_basis_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Compliance Basis Ref
        compliance_basis_binding_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Compliance Basis Binding Ref
        compliance_basis_evidence:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Compliance Basis Evidence
        request_signature_verified:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Request Signature Verified
        request_signature_keyid:
          anyOf:
          - type: string
          - type: 'null'
          title: Request Signature Keyid
        request_signer_identity_anchored:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Request Signer Identity Anchored
      type: object
      required:
      - verdict
      - sanctions_clear
      - recipient_kyb_status
      - risk_tier
      - reasons
      - screened_at
      - verdict_id
      - network_normalised
      title: ScreenResponse
    SessionStatusResponse:
      properties:
        jti:
          type: string
          title: Jti
        spend_cap_usd:
          type: number
          title: Spend Cap Usd
        spent_usd:
          type: number
          title: Spent Usd
        remaining_usd:
          type: number
          title: Remaining Usd
        active:
          type: boolean
          title: Active
      type: object
      required:
      - jti
      - spend_cap_usd
      - spent_usd
      - remaining_usd
      - active
      title: SessionStatusResponse
    SettlementEvidenceResponse:
      properties:
        settled_payment_ref:
          type: string
          title: Settled Payment Ref
        status:
          type: string
          title: Status
        network:
          anyOf:
          - type: string
          - type: 'null'
          title: Network
        round:
          anyOf:
          - type: integer
          - type: 'null'
          title: Round
        captured_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Captured At
        last_error:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Error
        chain_binding:
          anyOf:
          - $ref: '#/components/schemas/ChainBinding'
          - type: 'null'
      type: object
      required:
      - settled_payment_ref
      - status
      title: SettlementEvidenceResponse
      description: Status of chain-evidence capture for a settled payment.
    SubscriptionCreate:
      properties:
        customer_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Customer Id
        customer:
          anyOf:
          - $ref: '#/components/schemas/CustomerRef'
          - type: 'null'
        amount:
          type: number
          exclusiveMinimum: 0.0
          title: Amount
          description: Major-units fiat (e.g. 49.99 GBP) or USDC.
        currency:
          type: string
          maxLength: 4
          minLength: 3
          title: Currency
          description: ISO 4217 (3-letter) or 'USDC'.
        chain:
          anyOf:
          - type: string
          - type: 'null'
          title: Chain
          description: Override tenant's default network for this sub.
        cadence:
          type: string
          enum:
          - weekly
          - monthly
          - quarterly
          - annual
          - custom
          title: Cadence
        custom_interval_days:
          anyOf:
          - type: integer
            maximum: 366.0
            minimum: 1.0
          - type: 'null'
          title: Custom Interval Days
        billing_anchor_day:
          anyOf:
          - type: integer
            maximum: 31.0
            minimum: 1.0
          - type: 'null'
          title: Billing Anchor Day
        billing_timezone:
          type: string
          title: Billing Timezone
          default: UTC
        cycle_anchor:
          type: string
          enum:
          - anniversary
          - calendar
          title: Cycle Anchor
          default: anniversary
        starts_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Starts At
          description: First due date. Defaults to NOW() + cadence.
        notify_channels:
          items:
            type: string
          type: array
          title: Notify Channels
        notify_lead_hours:
          type: integer
          maximum: 720.0
          minimum: 1.0
          title: Notify Lead Hours
          default: 72
        failed_payment_policy:
          anyOf:
          - $ref: '#/components/schemas/FailedPaymentPolicy'
          - type: 'null'
        fx_lock_policy:
          type: string
          enum:
          - send
          - payment
          title: Fx Lock Policy
          default: send
        cancel_at_period_end:
          type: boolean
          title: Cancel At Period End
          default: false
        consent_terms_version:
          anyOf:
          - type: string
          - type: 'null'
          title: Consent Terms Version
        consent_scope:
          additionalProperties: true
          type: object
          title: Consent Scope
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
      additionalProperties: false
      type: object
      required:
      - amount
      - currency
      - cadence
      title: SubscriptionCreate
      description: Request body for POST /v1/subscriptions.
    SubscriptionInvoiceResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        subscription_id:
          type: string
          format: uuid
          title: Subscription Id
        amount_minor_at_send:
          type: integer
          title: Amount Minor At Send
        currency_at_send:
          type: string
          title: Currency At Send
        fx_rate_at_send:
          anyOf:
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          - type: 'null'
          title: Fx Rate At Send
        crypto_amount_microunits_expected:
          type: integer
          title: Crypto Amount Microunits Expected
        due_at:
          type: string
          format: date-time
          title: Due At
        payment_link_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Payment Link Token
        link_sent_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Link Sent At
        paid_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Paid At
        paid_amount_microunits:
          anyOf:
          - type: integer
          - type: 'null'
          title: Paid Amount Microunits
        paid_tx_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Paid Tx Id
        status:
          type: string
          enum:
          - pending
          - paid
          - missed
          - retrying
          title: Status
        attempts:
          type: integer
          title: Attempts
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - subscription_id
      - amount_minor_at_send
      - currency_at_send
      - fx_rate_at_send
      - crypto_amount_microunits_expected
      - due_at
      - payment_link_token
      - link_sent_at
      - paid_at
      - paid_amount_microunits
      - paid_tx_id
      - status
      - attempts
      - created_at
      title: SubscriptionInvoiceResponse
    SubscriptionResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        tenant_id:
          type: string
          format: uuid
          title: Tenant Id
        customer_id:
          type: string
          format: uuid
          title: Customer Id
        amount_minor:
          type: integer
          title: Amount Minor
        currency:
          type: string
          title: Currency
        chain:
          type: string
          title: Chain
        receiver_address:
          type: string
          title: Receiver Address
        cadence:
          type: string
          enum:
          - weekly
          - monthly
          - quarterly
          - annual
          - custom
          title: Cadence
        custom_interval_days:
          anyOf:
          - type: integer
          - type: 'null'
          title: Custom Interval Days
        billing_anchor_day:
          anyOf:
          - type: integer
          - type: 'null'
          title: Billing Anchor Day
        billing_timezone:
          type: string
          title: Billing Timezone
        next_due_at:
          type: string
          format: date-time
          title: Next Due At
        cycle_anchor:
          type: string
          enum:
          - anniversary
          - calendar
          title: Cycle Anchor
        status:
          type: string
          enum:
          - active
          - past_due
          - paused
          - cancelled
          title: Status
        paused_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Paused At
        cancelled_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Cancelled At
        cancel_at_period_end:
          type: boolean
          title: Cancel At Period End
        notify_channels:
          items:
            type: string
          type: array
          title: Notify Channels
        notify_lead_hours:
          type: integer
          title: Notify Lead Hours
        failed_payment_policy:
          additionalProperties: true
          type: object
          title: Failed Payment Policy
        fx_lock_policy:
          type: string
          enum:
          - send
          - payment
          title: Fx Lock Policy
        cancel_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Cancel Url
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - tenant_id
      - customer_id
      - amount_minor
      - currency
      - chain
      - receiver_address
      - cadence
      - custom_interval_days
      - billing_anchor_day
      - billing_timezone
      - next_due_at
      - cycle_anchor
      - status
      - paused_at
      - cancelled_at
      - cancel_at_period_end
      - notify_channels
      - notify_lead_hours
      - failed_payment_policy
      - fx_lock_policy
      - metadata
      - created_at
      title: SubscriptionResponse
    SubscriptionUpdate:
      properties:
        notify_channels:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Notify Channels
        notify_lead_hours:
          anyOf:
          - type: integer
            maximum: 720.0
            minimum: 1.0
          - type: 'null'
          title: Notify Lead Hours
        failed_payment_policy:
          anyOf:
          - $ref: '#/components/schemas/FailedPaymentPolicy'
          - type: 'null'
        cancel_at_period_end:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Cancel At Period End
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
      additionalProperties: false
      type: object
      title: SubscriptionUpdate
      description: 'PATCH-style partial update. Some fields (chain, currency, cadence) are

        deliberately immutable post-creation — change those by cancelling and

        creating a new subscription.'
    TokenRequest:
      properties:
        atb_zk_credential:
          anyOf:
          - type: string
          - type: 'null'
          title: Atb Zk Credential
          description: Base64url ATB ZKP Phase 2 cert. Provide this OR federation_token.
        federation_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Federation Token
          description: Pre-composed federation token from algovoi-federation-validator. Provide this OR atb_zk_credential. Requires FEDERATION_VALIDATOR_ENABLED=true.
        spend_cap_usd:
          anyOf:
          - type: number
            maximum: 10000.0
            minimum: 0.0
          - type: 'null'
          title: Spend Cap Usd
          description: Per-session spend cap in USD. Defaults to 100.0. Set to 0 to allow dry-run session (no payments).
        ttl_secs:
          anyOf:
          - type: integer
            maximum: 86400.0
            minimum: 60.0
          - type: 'null'
          title: Ttl Secs
          description: Session lifetime in seconds. Defaults to 3600. Max 86400 (24 h).
      type: object
      title: TokenRequest
    TokenResponse:
      properties:
        token:
          type: string
          title: Token
        token_type:
          type: string
          title: Token Type
          default: Bearer
        expires_in:
          type: integer
          title: Expires In
        spend_cap_usd:
          type: number
          title: Spend Cap Usd
        jti:
          type: string
          title: Jti
      type: object
      required:
      - token
      - expires_in
      - spend_cap_usd
      - jti
      title: TokenResponse
    TopupCaptureResponse:
      properties:
        mandate_id:
          type: string
          format: uuid
          title: Mandate Id
        new_balance_minor:
          type: integer
          title: New Balance Minor
        added_minor:
          type: integer
          title: Added Minor
        paypal_order_id:
          type: string
          title: Paypal Order Id
      type: object
      required:
      - mandate_id
      - new_balance_minor
      - added_minor
      - paypal_order_id
      title: TopupCaptureResponse
    TopupInitiateRequest:
      properties:
        amount_minor:
          type: integer
          exclusiveMinimum: 0.0
          title: Amount Minor
          description: Top-up amount in GBP pence
        return_url:
          type: string
          title: Return Url
          description: URL to redirect after PayPal approval
        cancel_url:
          type: string
          title: Cancel Url
          description: URL to redirect on cancellation
      type: object
      required:
      - amount_minor
      - return_url
      - cancel_url
      title: TopupInitiateRequest
    TopupInitiateResponse:
      properties:
        mandate_id:
          type: string
          format: uuid
          title: Mandate Id
        paypal_order_id:
          type: string
          title: Paypal Order Id
        approval_url:
          type: string
          title: Approval Url
        amount_minor:
          type: integer
          title: Amount Minor
      type: object
      required:
      - mandate_id
      - paypal_order_id
      - approval_url
      - amount_minor
      title: TopupInitiateResponse
    TrustQueryRequest:
      properties:
        receipts:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Receipts
          default: []
      type: object
      title: TrustQueryRequest
    TrustQueryResponse:
      properties:
        trust_outcome:
          type: string
          title: Trust Outcome
        composite_hash:
          type: string
          title: Composite Hash
        receipt_count:
          type: integer
          title: Receipt Count
        ctq_response:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Ctq Response
        ctq_response_jws:
          anyOf:
          - type: string
          - type: 'null'
          title: Ctq Response Jws
      type: object
      required:
      - trust_outcome
      - composite_hash
      - receipt_count
      title: TrustQueryResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    _Message:
      properties:
        messageId:
          type: string
          title: Messageid
        contextId:
          anyOf:
          - type: string
          - type: 'null'
          title: Contextid
        taskId:
          anyOf:
          - type: string
          - type: 'null'
          title: Taskid
        role:
          type: string
          title: Role
          default: user
        parts:
          items:
            $ref: '#/components/schemas/_Part'
          type: array
          title: Parts
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
      type: object
      title: _Message
    _Part:
      properties:
        kind:
          type: string
          title: Kind
          default: data
        data:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Data
        text:
          anyOf:
          - type: string
          - type: 'null'
          title: Text
        file:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: File
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
        raw:
          anyOf:
          - type: string
          - type: 'null'
          title: Raw
        filename:
          anyOf:
          - type: string
          - type: 'null'
          title: Filename
        mediaType:
          anyOf:
          - type: string
          - type: 'null'
          title: Mediatype
        mimeType:
          anyOf:
          - type: string
          - type: 'null'
          title: Mimetype
      additionalProperties: true
      type: object
      title: _Part
    _SendMessageRequest:
      properties:
        message:
          $ref: '#/components/schemas/_Message'
        configuration:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Configuration
      type: object
      required:
      - message
      title: _SendMessageRequest
    gateway__app__routers__verify__ChallengeRequest:
      properties:
        resource_id:
          type: string
          title: Resource Id
      type: object
      required:
      - resource_id
      title: ChallengeRequest
    gateway__app__routers__verify__ChallengeResponse:
      properties:
        resource_id:
          type: string
          title: Resource Id
        network:
          type: string
          title: Network
        receiver:
          type: string
          title: Receiver
        amount_microalgos:
          type: integer
          title: Amount Microalgos
        payment_reference:
          type: string
          title: Payment Reference
        price_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Price Token
        note_binding_required:
          type: boolean
          title: Note Binding Required
          default: false
        note_prefix:
          anyOf:
          - type: string
          - type: 'null'
          title: Note Prefix
      type: object
      required:
      - resource_id
      - network
      - receiver
      - amount_microalgos
      - payment_reference
      title: ChallengeResponse
    gateway__app__routers__verify__VerifyRequest:
      properties:
        resource_id:
          type: string
          title: Resource Id
        network:
          type: string
          title: Network
        tx_id:
          type: string
          title: Tx Id
        price_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Price Token
      type: object
      required:
      - resource_id
      - network
      - tx_id
      title: VerifyRequest
    gateway__app__routers__verify__VerifyResponse:
      properties:
        verified:
          type: boolean
          title: Verified
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        access_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Access Token
        settlement_attestation:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Settlement Attestation
        settlement_attestation_jws:
          anyOf:
          - type: string
          - type: 'null'
          title: Settlement Attestation Jws
      type: object
      required:
      - verified
      title: VerifyResponse
    shared__schemas__recurr__ChallengeRequest:
      properties:
        chain:
          type: string
          maxLength: 64
          minLength: 3
          title: Chain
        wallet_address:
          type: string
          maxLength: 128
          minLength: 6
          title: Wallet Address
      additionalProperties: false
      type: object
      required:
      - chain
      - wallet_address
      title: ChallengeRequest
      description: "Tenant-agnostic. Wallet alone is the identity for Recurr customer auth.\n\nPer-chain address shapes:\n  - EVM (Base, Tempo, etc.):  0x + 40 hex chars   (42 total)\n  - Algorand / VOI:           base32 with checksum (58 total)\n  - Solana:                   base58 (32-44 chars)\n  - Stellar:                  G... StrKey (56 total)\n  - Hedera:                   shard.realm.num    (>= 6 chars, e.g. ``0.0.0``)"
    shared__schemas__recurr__ChallengeResponse:
      properties:
        nonce:
          type: string
          title: Nonce
        message:
          type: string
          title: Message
        expires_at:
          type: string
          format: date-time
          title: Expires At
      type: object
      required:
      - nonce
      - message
      - expires_at
      title: ChallengeResponse
    shared__schemas__recurr__VerifyRequest:
      properties:
        nonce:
          type: string
          maxLength: 64
          minLength: 8
          title: Nonce
        signature:
          type: string
          maxLength: 512
          minLength: 8
          title: Signature
      additionalProperties: false
      type: object
      required:
      - nonce
      - signature
      title: VerifyRequest
    shared__schemas__recurr__VerifyResponse:
      properties:
        customer_jwt:
          type: string
          title: Customer Jwt
        expires_at:
          type: string
          format: date-time
          title: Expires At
        wallet_address:
          type: string
          title: Wallet Address
        chain:
          type: string
          title: Chain
        tenant_count:
          type: integer
          title: Tenant Count
          default: 0
      type: object
      required:
      - customer_jwt
      - expires_at
      - wallet_address
      - chain
      title: VerifyResponse
x-discovery:
  ownershipProofs:
  - eb10b2d7fb1e2fcbea7a4c5b031e339daacc7cf37d1fb569c58849287c121633
  resources:
  - https://api.algovoi.co.uk/mpp/probe
  resourcesCatalog: https://api.algovoi.co.uk/discovery/resources