openapi: 3.1.0
info:
  title: x402 Endpoint Risk Corpus
  version: 0.4.0
  description: Hosted x402 endpoint risk, payee reputation, autopay policy, attack-surface checks, and mitigation corpus backed by Cloudflare Cron + D1/R2.
servers:
  - url: https://x402-endpoint-risk-corpus.mtree.workers.dev
paths:
  /healthz:
    get:
      responses:
        '200': { description: Health }
  /dataset/health:
    get:
      responses:
        '200': { description: Dataset freshness and corpus stats }
  /v1/x402/risk_report:
    post:
      summary: Paid risk report for one x402 URL
      x-x402-price-usd: 0.15
      x-payment: { amount: 0.15, asset: USDC, network: base }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: { url: { type: string } }
              required: [url]
      responses:
        '402': { description: x402 payment required }
        '200': { description: Risk report }
  /v1/x402/top_risks:
    post:
      summary: Paid top-risk corpus rows
      x-x402-price-usd: 0.10
      x-payment: { amount: 0.10, asset: USDC, network: base }
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties: { limit: { type: integer, minimum: 1, maximum: 100 } }
      responses:
        '402': { description: x402 payment required }
        '200': { description: Top risky endpoints }
  /v1/x402/payee_reputation:
    post:
      summary: Paid payee/domain reputation and aggregate spend policy
      x-x402-price-usd: 0.15
      x-payment: { amount: 0.15, asset: USDC, network: base }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                pay_to: { type: string }
                domain: { type: string }
                url: { type: string }
              anyOf:
                - required: [pay_to]
                - required: [domain]
                - required: [url]
      responses:
        '402': { description: x402 payment required }
        '200': { description: Reputation score, allow/warn/block policy, spend guidance, and evidence }
  /v1/x402/autopay_policy:
    post:
      summary: Paid autopay policy for a candidate x402 call plan
      x-x402-price-usd: 0.20
      x-payment: { amount: 0.20, asset: USDC, network: base }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                pay_to: { type: string }
                domain: { type: string }
                url: { type: string }
                price_micro: { type: integer, minimum: 0 }
                planned_calls: { type: integer, minimum: 1, maximum: 10000 }
                session_cap_usd: { type: number, minimum: 0 }
                quality_gate: { type: string }
              anyOf:
                - required: [pay_to]
                - required: [domain]
                - required: [url]
      responses:
        '402': { description: x402 payment required }
        '200': { description: Autopay decision, spend limits, quality-gate requirements, warnings, and reputation evidence }
  /v1/x402/attack_surface_check:
    post:
      summary: Paid x402 attack-class checklist for one endpoint
      x-x402-price-usd: 0.25
      x-payment: { amount: 0.25, asset: USDC, network: base }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url: { type: string }
                method: { type: string }
                body_digest: { type: string }
                idempotency_key: { type: string }
                price_micro: { type: integer, minimum: 0 }
                post_settlement_deterministic: { type: boolean }
              required: [url]
      responses:
        '402': { description: x402 payment required }
        '200': { description: Attack-surface score, authorization/replay/paid-but-denied/discovery/price-drain checks, corpus evidence, and mitigations }

x-money-tree-buyer-readiness:
  quote_before_signing: "Read the unpaid 402 quote before signing or before paying; compare payTo, amount, network, asset, and resource."
  rail_readiness:
    network: "eip155:8453"
    asset: "USDC on Base"
  payment_proof_policy:
    require_payment_response: true
    receipt_fields: [transaction, network, asset, amount, payer, payTo]
  funding_handoff: "If the buyer lacks Base USDC or the settlement asset, stop before signing and hand off to funding; retry only with the same request after funding."
  revenue_metric_policy: "External paid calls are settled revenue; self-funded/internal-credit calls are protocol proof only."
  decision_json_shape:
    required_keys: [verdict, recommendation, warnings, confidence, metadata, evidence, action, stop_conditions, fallbacks, attribution]
