AiFinPay Settlement API

openapi: 3.2.0
info:
  title: AiFinPay Settlement API
  version: 5.3.0
  description: HTTP 402 payment gate where autonomous AI agents authenticate with Ed25519 signatures and pay on Polygon and Solana. This document is generated from backend/routes/*.js — do not hand-edit. Regenerate with `node backend/scripts/build-openapi.mjs`.
servers:
- url: https://api.aifinpay.io
  description: Production (api)
- url: https://bridge.aifinpay.io
  description: Production (bridge)
tags:
- name: Settlement
  description: settlement router — see backend/routes/settlement.js
paths:
  /v1/settlement/routes:
    get:
      tags:
      - Settlement
      summary: List configured v1.3 settlement routes
      operationId: get_v1_settlement_routes
      responses:
        '200':
          description: Configured routes; no settlement is enabled by this request.
          content:
            application/json:
              schema:
                type: object
                required:
                - routes
                properties:
                  routes:
                    type: array
                    items:
                      type: object
                      required:
                      - route_class
                      - profile
                      - network
                      - chain_id
                      - testnet
                      - name
                      - native_asset
                      - stable_assets
                      - explorer
                      - live
                      - splitter
                      - splitter_version
                      - runtime_code_hash
                      properties:
                        route_class:
                          type: string
                          enum:
                          - AIFP-1
                          - AIFP-2
                        profile:
                          type: object
                          required:
                          - route_class
                          - settlement_semantics
                          - treasury_bps
                          - creator_bps
                          - fee_on_top
                          - required_splitter_version
                          properties:
                            route_class:
                              type: string
                              enum:
                              - AIFP-1
                              - AIFP-2
                            settlement_semantics:
                              type: string
                              const: gross-inclusive
                            treasury_bps:
                              type: integer
                              minimum: 0
                              maximum: 10000
                            creator_bps:
                              type: integer
                              minimum: 0
                              maximum: 10000
                            fee_on_top:
                              type: boolean
                              const: false
                            required_splitter_version:
                              type: string
                              const: '1.3'
                        network:
                          type: string
                        chain_id:
                          type: integer
                        testnet:
                          type: boolean
                          description: True only for a canonical test network. Testnet settlement additionally requires explicit server dev mode.
                        name:
                          type: string
                        native_asset:
                          type: string
                        stable_assets:
                          type: object
                          additionalProperties:
                            type: object
                            required:
                            - address
                            - decimals
                            - issuer
                            properties:
                              address:
                                type: string
                                pattern: ^0x[0-9a-fA-F]{40}$
                              decimals:
                                type: integer
                                const: 6
                              issuer:
                                type: string
                        explorer:
                          type: string
                          format: uri
                        live:
                          type: boolean
                          description: Configured availability, including the registry flag, supersession and validity window. Not an RPC health or deployment attestation.
                        splitter:
                          type: string
                          pattern: ^0x[0-9a-fA-F]{40}$
                        splitter_version:
                          type: string
                          const: '1.3'
                        runtime_code_hash:
                          type: string
                          pattern: ^0x[0-9a-fA-F]{64}$
                        disabled_reason:
                          type: string
                          description: Present when live is false.
        '400':
          $ref: '#/components/responses/AifpError'
        '401':
          $ref: '#/components/responses/AifpError'
        '403':
          $ref: '#/components/responses/AifpError'
        '404':
          $ref: '#/components/responses/AifpError'
        '429':
          $ref: '#/components/responses/AifpError'
        5XX:
          $ref: '#/components/responses/AifpError'
      security: []
      description: Read-only registry discovery. Disabled routes remain visible with live=false and disabled_reason. Callers must independently verify the route before signing.
      parameters:
      - name: route_class
        in: query
        required: false
        schema:
          type: string
          enum:
          - AIFP-1
          - AIFP-2
  /v1/settlement/invoice:
    post:
      tags:
      - Settlement
      summary: Build a gross-inclusive v1.3 settlement instruction
      operationId: post_v1_settlement_invoice
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                additionalProperties: true
        '400':
          $ref: '#/components/responses/AifpError'
        '401':
          $ref: '#/components/responses/AifpError'
        '403':
          $ref: '#/components/responses/AifpError'
        '404':
          $ref: '#/components/responses/AifpError'
        '409':
          description: Route is disabled, superseded, outside its validity window, unknown or not v1.3.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AifpError'
        '429':
          $ref: '#/components/responses/AifpError'
        5XX:
          $ref: '#/components/responses/AifpError'
      security: []
      description: Requires a currently enabled canonical route. Rejects unknown assets, zero payout addresses, oversized orders and invalid expiry before returning calldata. The caller signs and submits from its own wallet.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - route_class
              - chain
              - asset
              - gross_amount
              - order_id
              anyOf:
              - required:
                - merchant_wallet
              - required:
                - provider_wallet
              properties:
                route_class:
                  type: string
                  enum:
                  - AIFP-1
                  - AIFP-2
                chain:
                  type: string
                  description: network returned by GET /v1/settlement/routes
                asset:
                  type: string
                  description: The route's native_asset or one of its stable_assets keys; case insensitive.
                gross_amount:
                  type: string
                  pattern: ^[1-9][0-9]{0,77}$
                  description: Positive decimal uint256 in atomic units, at most 2^256-1. Includes the protocol fee.
                merchant_wallet:
                  type: string
                  pattern: ^0x(?!0{40}$)[0-9a-fA-F]{40}$
                provider_wallet:
                  type: string
                  pattern: ^0x(?!0{40}$)[0-9a-fA-F]{40}$
                order_id:
                  type: string
                  minLength: 1
                  maxLength: 256
                  description: Nonblank, at most 256 UTF-8 bytes. Bytes are validated separately from character length.
                valid_until:
                  type: integer
                  description: Unix seconds, greater than the server's current time and no more than 1200 seconds ahead. Omit for 900 seconds; null is invalid.
components:
  responses:
    AifpError:
      description: AIFP-* error envelope. See backend/server.js safe error handler.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AifpError'
  schemas:
    AifpError:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: AIFP-{status} code, or domain-specific string (e.g. csrf_origin_denied)
        detail:
          type: string
        request_id:
          type: string
          description: AIFP-Request-Id for log correlation
  securitySchemes:
    reportingCapability:
      type: apiKey
      in: header
      name: AIFP-Reporting-Token
      description: Observation/identity-removal capability only; no spending, access or ownership authority.
    reportingOwnerSession:
      type: apiKey
      in: cookie
      name: __aifinpay_user_session
      description: Existing owner session, current tenant/site and session-epoch validation. Browser writes also require CSRF Origin checks.
    agentEd25519:
      type: apiKey
      in: header
      name: x-agent-pubkey
      description: 'Ed25519-signed native-auth v2 request. Companion headers: x-nonce, x-signature, x-aifinpay-auth-version. The proof binds canonical origin, method, resource, body hash, and expiry. GET /nonce provides migration diagnostics only; start with an unauthenticated request to receive a v2 challenge.'
    x402Payment:
      type: apiKey
      in: header
      name: X-PAYMENT-RESPONSE
      description: x402 payment proof, base64 JSON envelope. Issued by the paying agent's wallet after broadcasting the on-chain tx. See /.well-known/x402.json.
    userSession:
      type: apiKey
      in: cookie
      name: aifinpay_session
      description: Browser session cookie for /api/me/* — sameSite=Lax, CSRF-guarded.
    agentClaim:
      type: apiKey
      in: cookie
      name: __aifinpay_agent_claim
      description: Set by redeeming a one-time claim link (POST /api/me/claim-url). Valid 10 minutes, accepted only by /api/me/agents/challenge and /api/me/agents/claim.
    adminSession:
      type: apiKey
      in: cookie
      name: aifinpay_admin_session
      description: Admin session cookie. ADMIN_ALLOWED_IPS allowlist in effect.
    partnerSession:
      type: apiKey
      in: cookie
      name: aifinpay_partner_session
      description: Partner session cookie for /api/partners/me/*.
    merchantSecret:
      type: apiKey
      in: header
      name: AIFP-Merchant-Secret
      description: Per-merchant API key for /v1/merchants/* writes.
    ingestHmac:
      type: apiKey
      in: header
      name: x-ingest-signature
      description: HMAC signature for /api/internal/* and /api/telemetry.