openapi: 3.1.0
info:
  title: RAEN x402 Paid API Fleet
  version: 1.0.0
  description: |
    Twelve pay-per-call APIs on Base mainnet, billed with the x402 payment protocol
    (USDC on Base, `eip155:8453`). Every endpoint below returns **HTTP 402 Payment Required**
    with a signed payment challenge when called without a valid `X-PAYMENT` header.
    Pay the challenge (or let your x402 client library do it) and retry with the header
    to receive your result. Free first call on royal-ruby (charge-and-rebate, net $0):
    https://bshelby88.github.io/raen-first-call-free/

    Operator: Royal Agentic Enterprises (RAEN) — contact ops@royalruby.io
  x-logo:
    url: https://raen.royalruby.io/favicon.ico
servers:
  - url: https://royal-ruby-x402.fly.dev
    name: royal-ruby (law lookup)
  - url: https://vault-pro-x402.fly.dev
    name: vault-pro (Obsidian scaffolds)
  - url: https://escrow-x402.fly.dev
    name: escrow (agent-to-agent escrow)
  - url: https://nanobanana-x402.fly.dev
    name: nanobanana (AI images)
  - url: https://tradingagents-x402.fly.dev
    name: tradingagents (market consensus)
  - url: https://dispute-forge-x402.fly.dev
    name: dispute-forge (dispute letters)
  - url: https://nft-alpha-x402.fly.dev
    name: nft-alpha (NFT signals)
  - url: https://dispatch-x402.fly.dev
    name: dispatch (intent router)
  - url: https://contract-eye-x402.fly.dev
    name: contract-eye (contract risk)
  - url: https://briefsnap-x402.fly.dev
    name: briefsnap (document AI)
  - url: https://sentry-forge-x402.fly.dev
    name: sentry-forge (collection-notice defense)
  - url: https://settlement-collector.fly.dev
    name: settlement-collector (free telemetry)
tags:
  - name: legal
  - name: documents
  - name: images
  - name: trading
  - name: infra
  - name: free
components:
  headers:
    XPayerAddress:
      description: Your 0x wallet address. Required for the FREE FIRST CALL rebate on royal-ruby.
      schema: { type: string, pattern: "^0x[a-fA-F0-9]{40}$" }
    XPayment:
      description: Base64-encoded x402 payment proof from a settled challenge.
      schema: { type: string }
  responses:
    PaymentRequired:
      description: x402 challenge. Decode the base64 `payment-required` header to get `accepts[].payTo`, `maxAmountRequired`, and the facilitator URL.
      headers:
        payment-required:
          schema: { type: string }
    Ok200:
      description: Service result (JSON per endpoint).

paths:
  /api/law-lookup:
    post:
      tags: [legal]
      summary: US consumer-rights law citation lookup (FREE FIRST CALL)
      description: FCRA/FDCPA/TILA/state-UDAP citations with plain-English summaries, timelines, statute of limitations. Information only, not legal advice.
      parameters:
        - name: x-payer-address
          in: header
          schema: { $ref: "#/components/headers/XPayerAddress" }
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [topic]
              properties:
                topic: { type: string, minLength: 5, example: "credit report errors" }
                state: { type: string, example: "TX" }
      responses:
        "200": { $ref: "#/components/responses/Ok200" }
        "402": { $ref: "#/components/responses/PaymentRequired" }
  /api/scaffold-project:
    post:
      tags: [documents]
      summary: Obsidian project scaffold
      requestBody:
        content:
          application/json:
            schema: { type: object, required: [goal], properties: { goal: { type: string, minLength: 8 } } }
      responses:
        "200": { $ref: "#/components/responses/Ok200" }
        "402": { $ref: "#/components/responses/PaymentRequired" }
  /api/scaffold-agent:
    post:
      tags: [documents]
      summary: Obsidian agent definition scaffold
      requestBody:
        content:
          application/json:
            schema: { type: object, required: [role], properties: { role: { type: string, minLength: 5 }, goal: { type: string } } }
      responses:
        "200": { $ref: "#/components/responses/Ok200" }
        "402": { $ref: "#/components/responses/PaymentRequired" }
  /api/escrow/create:
    post:
      tags: [infra]
      summary: Create agent-to-agent USDC escrow on Base mainnet
      requestBody:
        content:
          application/json:
            schema: { type: object, required: [agentB, amountUsdc, task], properties: { agentB: { type: string }, amountUsdc: { type: number }, task: { type: string }, timeoutHours: { type: integer } } }
      responses:
        "200": { $ref: "#/components/responses/Ok200" }
        "402": { $ref: "#/components/responses/PaymentRequired" }
  /api/generate-image:
    post:
      tags: [images]
      summary: Generate an AI image from a text prompt
      requestBody:
        content:
          application/json:
            schema: { type: object, required: [prompt], properties: { prompt: { type: string, minLength: 3 }, aspectRatio: { type: string } } }
      responses:
        "200": { $ref: "#/components/responses/Ok200" }
        "402": { $ref: "#/components/responses/PaymentRequired" }
  /api/edit-image:
    post:
      tags: [images]
      summary: Edit an existing image with a natural-language prompt
      requestBody:
        content:
          application/json:
            schema: { type: object, required: [prompt, image_b64], properties: { prompt: { type: string, minLength: 3 }, image_b64: { type: string }, mime_type: { type: string }, aspectRatio: { type: string } } }
      responses:
        "200": { $ref: "#/components/responses/Ok200" }
        "402": { $ref: "#/components/responses/PaymentRequired" }
  /api/analyze-arbitrage:
    post:
      tags: [trading]
      summary: Synthetic BlockRun arbitrage-consensus demo for a ticker
      requestBody:
        content:
          application/json:
            schema: { type: object, required: [ticker], properties: { ticker: { type: string } } }
      responses:
        "200": { $ref: "#/components/responses/Ok200" }
        "402": { $ref: "#/components/responses/PaymentRequired" }
  /api/analyze-ticker:
    post:
      tags: [trading]
      summary: Synthetic ticker market-consensus demo
      requestBody:
        content:
          application/json:
            schema: { type: object, required: [ticker], properties: { ticker: { type: string, minLength: 1 }, date: { type: string }, analysts: { type: array, items: { type: string } } } }
      responses:
        "200": { $ref: "#/components/responses/Ok200" }
        "402": { $ref: "#/components/responses/PaymentRequired" }
  /api/dispute-pack:
    post:
      tags: [legal]
      summary: FCRA-compliant dispute letter + on-chain certificate
      requestBody:
        content:
          application/json:
            schema: { type: object, required: [creditor, reason], properties: { creditor: { type: string }, reason: { type: string } } }
      responses:
        "200": { $ref: "#/components/responses/Ok200" }
        "402": { $ref: "#/components/responses/PaymentRequired" }
  /api/nft-signal:
    post:
      tags: [trading]
      summary: Live OpenSea market signals for Base NFT collections
      requestBody:
        content:
          application/json:
            schema: { type: object, properties: { collection: { type: string, minLength: 1 }, collections: { type: array, items: { type: string } }, window_minutes: { type: integer } } }
      responses:
        "200": { $ref: "#/components/responses/Ok200" }
        "402": { $ref: "#/components/responses/PaymentRequired" }
  /dispatch:
    post:
      tags: [infra]
      summary: Route a natural-language agent intent to the right paid fleet service
      requestBody:
        content:
          application/json:
            schema: { type: object, required: [intent], properties: { intent: { type: string, minLength: 2 } } }
      responses:
        "200": { $ref: "#/components/responses/Ok200" }
        "402": { $ref: "#/components/responses/PaymentRequired" }
  /api/analyze-contract:
    post:
      tags: [legal]
      summary: Analyze contract text for risky or one-sided clauses
      requestBody:
        content:
          application/json:
            schema: { type: object, required: [text], properties: { text: { type: string, minLength: 50, maxLength: 50000 }, focus: { type: string } } }
      responses:
        "200": { $ref: "#/components/responses/Ok200" }
        "402": { $ref: "#/components/responses/PaymentRequired" }
  /api/summarize:
    post:
      tags: [documents]
      summary: Summarize a document (bullets, paragraph, or executive)
      requestBody:
        content:
          application/json:
            schema: { type: object, required: [text], properties: { text: { type: string }, format: { type: string } } }
      responses:
        "200": { $ref: "#/components/responses/Ok200" }
        "402": { $ref: "#/components/responses/PaymentRequired" }
  /api/extract-actions:
    post:
      tags: [documents]
      summary: Extract action items, decisions, and deadlines
      requestBody:
        content:
          application/json:
            schema: { type: object, required: [text], properties: { text: { type: string } } }
      responses:
        "200": { $ref: "#/components/responses/Ok200" }
        "402": { $ref: "#/components/responses/PaymentRequired" }
  /api/eli5:
    post:
      tags: [documents]
      summary: Plain-English explanation of complex text
      requestBody:
        content:
          application/json:
            schema: { type: object, required: [text], properties: { text: { type: string } } }
      responses:
        "200": { $ref: "#/components/responses/Ok200" }
        "402": { $ref: "#/components/responses/PaymentRequired" }
  /api/compare-docs:
    post:
      tags: [documents]
      summary: Compare two documents side by side
      requestBody:
        content:
          application/json:
            schema: { type: object, required: [doc_a, doc_b], properties: { doc_a: { type: string }, doc_b: { type: string } } }
      responses:
        "200": { $ref: "#/components/responses/Ok200" }
        "402": { $ref: "#/components/responses/PaymentRequired" }
  /sentry-forge/api/dispute-pack:
    post:
      tags: [legal]
      servers:
        - url: https://sentry-forge-x402.fly.dev
      summary: Turn a debt-collection notice into an 8-file validation pack
      description: Host sentry-forge-x402.fly.dev — actual path is /api/dispute-pack (kept under a unique spec key because dispute-forge uses the same path).
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [customer_name, state, contract_type, default_date, alleged_balance, narrative, collector_letter]
              properties:
                customer_name: { type: string }
                state: { type: string, pattern: "^[A-Za-z]{2}$" }
                contract_type: { type: string }
                default_date: { type: string, format: date }
                alleged_balance: { type: number, minimum: 0 }
                narrative: { type: string }
                collector_letter: { type: string }
                original_contract: { type: string }
                itemization: { type: string }
      responses:
        "200": { $ref: "#/components/responses/Ok200" }
        "402": { $ref: "#/components/responses/PaymentRequired" }
  /health:
    get:
      tags: [free]
      summary: Fleet health probe (free, no payment)
      responses:
        "200": { description: Service health JSON }
  /stats:
    get:
      tags: [free]
      summary: Live challenge/settlement telemetry (free, no payment)
      responses:
        "200": { description: Telemetry JSON }
  /proof:
    get:
      tags: [free]
      summary: Proof-of-commerce page (free)
      responses:
        "200": { description: HTML }