AINumbers.co X402 API

openapi: 3.2.0
info:
  title: AINumbers.co Fintech Intelligence Suite X402 API
  version: 1.0.0
  description: '**1255 fintech intelligence tools** covering ISO 20022, A2A payments, CFPB §1033, EU AI Act, DORA, MiCA, AML/KYC, BaaS, DLT/tokenization, ESG/climate finance, agentic payments (AP2, ACP, x402, Visa TAP, Mastercard Agent Pay), PQC migration, sanctions screening, and OpenChainGraph v0.4 computation chains.


    ## Transport


    > **The live transport is MCP JSON-RPC 2.0 at `https://mcp.ainumbers.co/mcp` — not REST.**

    >

    > This OpenAPI file is a **descriptive data-room artifact** — a machine-readable index of all tools and their input/output schemas. The REST paths (`POST /v1/tools/{name}`) described here are a projection; they become functional only if the optional REST shim (Area 2 Path B) is deployed.

    >

    > To call tools today, connect via the official MCP client SDKs. TypeScript: `@modelcontextprotocol/sdk`. Python: `mcp`.


    ## Architecture


    All tools run **entirely client-side** (browser JavaScript). Zero PII. Zero server calls after page load. Deterministic, reproducible outputs. Licensed CC BY 4.0.


    OpenChainGraph v0.4 compute-binding nodes additionally run **server-side on the MCP Worker** and emit verifiable artifacts with `execution_hash` (WebCrypto SHA-256 over RFC 8785 canonical JSON).'
  contact:
    name: Post Oak Labs
    url: https://postoaklabs.com
    email: tim@postoaklabs.com
  license:
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/
servers:
- url: https://ainumbers.co
  description: Static browser-based tool host (DreamHost). Tools run client-side — no REST gateway is active on this origin. See x-mcp for the live MCP endpoint.
tags:
- name: X402
paths:
  /v1/tools/decode_x402_payment:
    post:
      operationId: decode_x402_payment
      summary: x402 Header Decoder, Payload Linter & 402 Flow Simulator
      description: 'Decodes x402 PAYMENT-REQUIRED / PAYMENT-SIGNATURE / PAYMENT-RESPONSE headers, lints an exact-scheme PaymentPayload, walks the HTTP-402 request/verify/settle flow, and shows the scheme x network support matrix. exact-scheme authorization sub-fields are illustrative (EIP-3009 style) — verify against the x402 spec.


        **Tool URL:** https://ainumbers.co/tools/277-x402-payload-decoder-flow-simulator.html

        **AP2/Policy Mandate export:** yes'
      tags:
      - X402
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                header_or_payload:
                  type: string
                  description: A base64 x402 header value or a PaymentPayload JSON.
              required:
              - header_or_payload
      responses:
        '200':
          description: Successful tool execution result
          content:
            application/json:
              schema:
                type: object
                properties:
                  decoded:
                    type: object
                  findings:
                    type: array
      x-mcp-tool-name: decode_x402_payment
      x-tool-url: https://ainumbers.co/tools/277-x402-payload-decoder-flow-simulator.html
      x-source: manifest
      x-ap2-export: true
  /v1/tools/x402_micropayment_pricing_modeler:
    post:
      operationId: x402_micropayment_pricing_modeler
      summary: x402 Micropayment Pricing Modeler
      description: 'Model API and content pricing under HTTP 402 (x402) flows: per-call price, settlement asset, network fee drag, and breakeven vs subscription. Agent economics analysis. Client-side, zero PII.


        **Tool URL:** https://ainumbers.co/tools/497-x402-micropayment-pricing-modeler.html

        **AP2/Policy Mandate export:** yes'
      tags:
      - X402
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                per_call_price_usd:
                  type: number
                  description: Per-call price in USD
                settlement_asset:
                  type: string
                  description: 'Settlement asset: usdc, usdt, eth, sol'
                monthly_calls:
                  type: number
                  description: Expected monthly call volume
                subscription_price_usd:
                  type: number
                  description: Alternative subscription price per month for breakeven comparison
      responses:
        '200':
          description: Successful tool execution result
          content:
            application/json:
              schema:
                type: object
                description: Tool execution result payload
      x-mcp-tool-name: x402_micropayment_pricing_modeler
      x-tool-url: https://ainumbers.co/tools/497-x402-micropayment-pricing-modeler.html
      x-source: manifest
      x-ap2-export: true
  /v1/tools/verify_x402_payment_envelope:
    post:
      operationId: verify_x402_payment_envelope
      summary: x402 Payment Envelope Verifier
      description: 'Offline verifier for x402 PaymentPayload envelopes (the exact-scheme EIP-3009-style payload shape). Checks header well-formedness (x402Version, scheme, network), the authorization sub-object''s required fields, and the signature''s structural shape, and -- when a PaymentRequirements body is also pasted -- checks amount/asset/recipient consistency between the two documents. Never recovers a signer address or claims a signature cryptographically verifies; that recovery is art-591-x402-signer-recovery-verifier''s job, cited not duplicated. Never originates, funds, or settles a payment. Zero network calls.


        **Tool URL:** https://ainumbers.co/tools/628-x402-payment-envelope-verifier.html

        **AP2/Policy Mandate export:** yes'
      tags:
      - X402
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                payment_payload:
                  type: object
                payment_requirements:
                  type: object
      responses:
        '200':
          description: Successful tool execution result
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                properties:
                  verification_report:
                    type: object
                    description: verdict, per-check pass/fail list, and whether a PaymentRequirements was paired for cross-consistency checks
      x-mcp-tool-name: verify_x402_payment_envelope
      x-tool-url: https://ainumbers.co/tools/628-x402-payment-envelope-verifier.html
      x-source: manifest
      x-ap2-export: true
  /v1/tools/verify_vpsf_claim_composite:
    post:
      operationId: verify_vpsf_claim_composite
      summary: VPSF Claim Algebra Verifier
      description: 'Verifies x402 VPSF Payment Claim composites (conjunction, implication, aggregation, selective disclosure, revocation) over the four canonical Payment Claim types (PaymentIntent, SettlementReceipt, RefundClaim, DelegationGrant), entirely client-side. Recomputes every JCS Preimage Hash via RFC 8785 canonicalisation and SHA-256, resolves component claims against a user-supplied manifest, and applies each operator''s algebraic rules: vacuous-truth rejection for Implication, non-idempotent non-nestable Revocation, sorted-operand homogeneous-currency Aggregation with recomputed totals, and commitment recomputation for Selective Disclosure.


        **Tool URL:** https://ainumbers.co/tools/629-vpsf-claim-verifier.html'
      tags:
      - X402
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - claims
              - composite
              properties:
                claims:
                  type: array
                  description: x402 Payment Claim objects
                composite:
                  type: object
                  description: VPSF operator composite over the claims
      responses:
        '200':
          description: Successful tool execution result
          content:
            application/json:
              schema:
                type: object
                properties:
                  ALL_PASS:
                    type: boolean
                  operator:
                    type: string
                  hash:
                    type:
                    - string
                    - 'null'
                  errors:
                    type: array
                    items:
                      type: string
                  children:
                    type: array
                    items:
                      type: object
      x-mcp-tool-name: verify_vpsf_claim_composite
      x-tool-url: https://ainumbers.co/tools/629-vpsf-claim-verifier.html
      x-source: manifest
  /v1/tools/emit_x402_spendevidence_vpsf_claims:
    post:
      operationId: emit_x402_spendevidence_vpsf_claims
      summary: x402 Spend-Evidence VPSF Bridge
      description: 'Renders the x402-spend-evidence chain''s assembled x402_spend_evidence pack (EIP-712 digest recompute, ECDSA signer recovery, domain/nonce/window check) as a VPSF SettlementReceipt + DelegationGrant Payment Claim pair, JCS-hashed via RFC 8785 canonicalisation and SHA-256, joined by a Conjunction composite. Verifiable offline by any VPSF-conformant verifier, including this suite''s own VPSF Claim Algebra Verifier. Structural evidence only: never a settlement-finality claim.


        **Tool URL:** https://ainumbers.co/tools/630-x402-spendevidence-vpsf-bridge.html'
      tags:
      - X402
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - spend_evidence_pack
              - execution_hash_of_origin
              properties:
                spend_evidence_pack:
                  type: object
                  description: x402_spend_evidence pack
                execution_hash_of_origin:
                  type: string
                  description: origin chain-step execution_hash
      responses:
        '200':
          description: Successful tool execution result
          content:
            application/json:
              schema:
                type: object
                properties:
                  delegation_grant:
                    type: object
                  settlement_receipt:
                    type: object
                  composite:
                    type: object
      x-mcp-tool-name: emit_x402_spendevidence_vpsf_claims
      x-tool-url: https://ainumbers.co/tools/630-x402-spendevidence-vpsf-bridge.html
      x-source: manifest
  /v1/tools/recompute_x402_permit2_digest:
    post:
      operationId: recompute_x402_permit2_digest
      summary: X402 Permit2 Evidence Recomputer
      description: 'Recomputes the Permit2 typed-data digest a payer''s wallet signs for an x402 payment, for the three single-item message shapes the exact and upto schemes use: a witness transfer that binds the destination, an unwitnessed signature transfer, and an allowance permit. From caller-supplied domain and message fields it derives the domain separator, the struct hash and the digest, deriving each type hash at run time from the type string rather than carrying a transcribed constant, and it reports binding facts against a caller-supplied payment requirement: whether the spender is the pinned x402 proxy, whether the destination bound into the witness matches payTo, whether the token matches the asset, whether the chain matches the network, and whether the amount holds under the scheme rule, which is equality under exact and a ceiling under upto. It reports nonce facts in the right space, keeping the unordered bitmap decomposition of the transfer shapes apart from the sequential counter of the allowance shape, and it reports that an allowance expiration of zero lasts only the current block rather than never expiring. Signature bytes are classified without recovery: length class, whether s sits above half the curve order, the recovery byte form including the raw parity case an on-chain call cannot use, and the counterfactual wrapper marker. Signer recovery itself is handed off to art-591 in that node''s exact input shape, and a sponsored approval leg is handed off to art-612 in its. Scope limits: it reads no chain, so nonce spend state, stored allowance, contract code and the current time are caller-declared inputs echoed back, and any absent input reports NOT_EVALUATED rather than a pass. It never originates, relays or submits a payment.


        **Tool URL:** https://ainumbers.co/chaingraph/art-699-x402-permit2-evidence-recomputer.html

        **AP2/Policy Mandate export:** yes'
      tags:
      - X402
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - chainId
              - deadline
              - details
              - domain
              - eip2612GasSponsoring
              - from
              - nonce
              - nonce_already_used
              - now_unix
              - permitted
              - requirement
              - sigDeadline
              - signature
              - spender
              - variant
              - verifyingContract
              - version
              - witness
              properties:
                chainId:
                  description: type not evidenced by kernel source
                deadline:
                  description: type not evidenced by kernel source
                details:
                  description: type not evidenced by kernel source
                domain:
                  description: type not evidenced by kernel source
                eip2612GasSponsoring:
                  description: type not evidenced by kernel source
                from:
                  description: type not evidenced by kernel source
                nonce:
                  description: type not evidenced by kernel source
                nonce_already_used:
                  description: type not evidenced by kernel source
                now_unix:
                  description: type not evidenced by kernel source
                permitted:
                  description: type not evidenced by kernel source
                requirement:
                  description: type not evidenced by kernel source
                sigDeadline:
                  description: type not evidenced by kernel source
                signature:
                  description: type not evidenced by kernel source
                spender:
                  description: type not evidenced by kernel source
                variant:
                  description: type not evidenced by kernel source
                verifyingContract:
                  description: type not evidenced by kernel source
                version:
                  description: type not evidenced by kernel source
                witness:
                  description: type not evidenced by kernel source
      responses:
        '200':
          description: Successful tool execution result
          content:
            application/json:
              schema:
                type: object
                properties:
                  allowance_expiry:
                    type:
                    - 'null'
                    - object
                  digest:
                    type:
                    - string
                    - 'null'
                  domain:
                    type: object
                    properties:
                      chain_id:
                        type: string
                      field_count:
                        type: number
                      name:
                        type: string
                      verifying_contract:
                        type: string
                      verifying_contract_is_canonical_permit2:
                        type: boolean
                    required:
                    - chain_id
                    - field_count
                    - name
                    - verifying_contract
                    - verifying_contract_is_canonical_permit2
                    additionalProperties: false
                  domain_separator:
                    type:
                    - string
                    - 'null'
                  domain_typehash:
                    type: string
                  errors:
                    type: array
                    items:
                      type: string
                  handoff_591:
                    type:
                    - object
                    - 'null'
                  handoff_612:
                    type:
                    - 'null'
                    - object
                  message:
                    type:
                    - object
                    - 'null'
                  nonce_facts:
                    type:
                    - object
                    - 'null'
                  reasons:
                    type: array
                    items:
                      type: string
                  scope_note:
                    type: string
                  signature_form:
                    type: object
                    properties:
                      ecdsa_recovery_applicable:
                        type:
                        - boolean
                        - 'null'
                      erc6492_wrapped:
                        type: boolean
                        enum:
                        - false
                        - true
                      notes:
                        type: array
                        items:
                          type: string
                      present:
                        type: boolean
                        enum:
                        - false
                        - true
                      r:
                        type:
                        - string
                        - 'null'
                      s:
                        type:
                        - string
                        - 'null'
                      s_above_half_order:
                        type:
                        - boolean
                        - 'null'
                      signature_byte_length:
                        type:
                        - number
                        - 'null'
                      signature_length_class:
                        type:
                        - string
                        - 'null'
                      v_form:
                        type:
                        - string
                        - 'null'
                        enum:
                        - compact_packed_y_parity
                        - legacy_27_28
                        - null
                      v_onchain_compatible:
                        type:
                        - boolean
                        - 'null'
                      y_parity:
                        type:
                        - number
                        - 'null'
                    required:
                    - ecdsa_recovery_applicable
                    - erc6492_wrapped
                    - notes
                    - present
                    - r
                    - s
                    - s_above_half_order
                    - signature_byte_length
                    - signature_length_class
                    - v_form
                    - v_onchain_compatible
                    - y_parity
                    additionalProperties: false
                  sponsored_approval:
                    type:
                    - 'null'
                    - object
                  struct_hash:
                    type:
                    - string
                    - 'null'
                  type_string:
                    type:
                    - string
                    - 'null'
                  typehash:
                    type:
                    - string
                    - 'null'
                  variant:
                    type:
                    - string
                    - 'null'
                    enum:
                    - permit_batch_transfer_from
                    - permit_single
                    - permit_transfer_from
                    - permit_witness_batch_v9
                    - x402_witness_transfer
                    - null
                  verdict:
                    type: string
                    enum:
                    - DIGEST_RECOMPUTED
                    - INDETERMINATE
                  warnings:
                    type: array
                    items:
                      type: string
                  window:
                    type:
                    - object
                    - 'null'
                  x402_binding:
                    type:
                    - object
                    - 'null'
                required:
                - allowance_expiry
                - digest
                - domain
                - domain_separator
                - domain_typehash
                - errors
                - handoff_591
                - handoff_612
                - message
                - nonce_facts
                - reasons
                - scope_note
                - signature_form
                - sponsored_approval
                - struct_hash
                - type_string
                - typehash
                - variant
                - verdict
                - warnings
                - window
                - x402_binding
                additionalProperties: false
      x-mcp-tool-name: recompute_x402_permit2_digest
      x-tool-url: https://ainumbers.co/chaingraph/art-699-x402-permit2-evidence-recomputer.html
      x-source: manifest
      x-ap2-export: true
x-mcp:
  transport: MCP JSON-RPC 2.0 (streamable HTTP)
  endpoint: https://mcp.ainumbers.co/mcp
  protocol_version: '2025-11-25'
  authentication: none
  registry: co.ainumbers/tools (official MCP registry)
  note: Connect any MCP-compatible client (Claude, ChatGPT, custom agent) directly to this endpoint. The REST paths in this file are descriptive only — they do not exist on the live server unless the REST shim is deployed.