openapi: 3.1.0
info:
  title: Monarch Shield API
  version: 0.1.0
  description: Sandbox and pre-payment trust checks for x402, processor, card, bank, wallet, stablecoin, paid MCP, paid API, and agent-controlled payments.
servers:
  - url: https://monarch-doctor-run.ghostmonarchalerts.workers.dev
    description: Current telemetry worker for opt-in run reporting and runtime checks
paths:
  /proof/proof.json:
    get:
      servers:
        - url: https://x402ms.ai
          description: First-party public proof and docs surface
      summary: Read static Monarch proof fallback
      description: Returns the first-party static proof fallback used when live aggregate counters are unavailable. The canonical human proof page is /proof/.
      operationId: readStaticProof
      responses:
        "200":
          description: Static proof fallback
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProofResponse"
  /doctor-run:
    post:
      summary: Record an opt-in Monarch Doctor run
      description: Accepts anonymous Doctor run metadata for DAU proof. Never send source code, wallet addresses, endpoint URLs, payment amounts, API keys, file names, or file paths.
      operationId: recordDoctorRun
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DoctorRunRequest"
      responses:
        "202":
          description: Doctor run accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DoctorRunResponse"
  /projects/{projectHash}/proof:
    get:
      summary: Read token-backed project proof
      description: Returns aggregate counters plus the last 100 privacy-preserving Doctor run records for a token-backed projectHash. It does not return package manager info, branch names, commit SHAs, repo names, file names, paths, URLs, wallet addresses, amounts, source code, or raw project tokens.
      operationId: readProjectProof
      parameters:
        - name: projectHash
          in: path
          required: true
          schema:
            type: string
            pattern: "^[a-f0-9]{24}$"
      responses:
        "200":
          description: Project proof summary
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectProofResponse"
  /projects/{projectHash}/badge.svg:
    get:
      summary: Read token-backed project proof badge
      description: Returns an SVG badge reflecting the latest token-backed Doctor report for a projectHash.
      operationId: readProjectBadge
      parameters:
        - name: projectHash
          in: path
          required: true
          schema:
            type: string
            pattern: "^[a-f0-9]{24}$"
      responses:
        "200":
          description: SVG badge
          content:
            image/svg+xml:
              schema:
                type: string
  /discovery-event:
    post:
      summary: Record an anonymous discovery event
      description: Accepts privacy-preserving page-view or CTA-click metadata for A/B testing discovery language. Never send raw URLs, raw search strings, source code, wallet addresses, endpoint URLs, payment amounts, API keys, file names, file paths, emails, tokens, or secrets.
      operationId: recordDiscoveryEvent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DiscoveryEventRequest"
      responses:
        "202":
          description: Discovery event accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DoctorRunResponse"
  /check-payment:
    post:
      summary: Check an agent-controlled payment before money moves
      description: Returns allow, caution, block, or route before an agent pays through x402, processor, card, bank, wallet, stablecoin, paid MCP, paid API, or agent-to-agent payment rails. Use after sandbox/preflight checks pass.
      operationId: checkPayment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CheckPaymentRequest"
      responses:
        "200":
          description: Payment trust decision
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CheckPaymentResponse"
components:
  schemas:
    DoctorRunRequest:
      type: object
      required:
        - event
        - tool
        - version
        - status
        - projectHash
        - timestamp
      properties:
        event:
          type: string
          enum: [doctor_run]
        tool:
          type: string
          enum: [monarch-doctor]
        version:
          type: string
        status:
          type: string
          enum: [passed, failed, no_payment_flow_detected, failed_no_payment_flow]
        ci:
          type: boolean
        strict:
          type: boolean
        applicable:
          type: boolean
        hasPaymentFlow:
          type: boolean
        hasUnprotectedPaymentFiles:
          type: boolean
        findingCount:
          type: integer
          minimum: 0
        sandboxPassed:
          type: boolean
        projectHash:
          type: string
          pattern: "^[a-f0-9]{24}$"
        projectScope:
          type: boolean
          description: True only when MONARCH_PROJECT_TOKEN was set and hashed locally before reporting.
        timestamp:
          type: string
          format: date-time
    DoctorRunResponse:
      type: object
      required:
        - accepted
      properties:
        accepted:
          type: boolean
        stored:
          type: boolean
    DiscoveryEventRequest:
      type: object
      required:
        - event
        - eventName
        - surface
        - variant
        - language
        - timestamp
      properties:
        event:
          type: string
          enum: [discovery_event]
        eventName:
          type: string
          enum: [page_view, cta_click]
        surface:
          type: string
          examples: [homepage, hero-primary, docs-query-map]
        variant:
          type: string
          enum: [a, b]
        language:
          type: string
          examples: [en-US, es-ES, pt-BR]
        languages:
          type: array
          items:
            type: string
        referrerHost:
          type: string
          description: Hostname only, never full referrer URL.
        landing:
          type: string
          description: Site path only, never full URL or query string.
        intent:
          type: string
          description: Sanitized intent bucket from landing path or UTM content.
        utmSource:
          type: string
        utmMedium:
          type: string
        utmCampaign:
          type: string
        timestamp:
          type: string
          format: date-time
    CheckPaymentRequest:
      type: object
      required:
        - resourceUrl
        - payTo
        - amount
        - asset
        - network
        - intent
      properties:
        resourceUrl:
          type: string
          format: uri
        payTo:
          type: string
        amount:
          type: string
        asset:
          type: string
          examples: ["USDC"]
        network:
          type: string
          examples: ["base"]
        intent:
          type: string
        agentId:
          type: string
        userId:
          type: string
        metadata:
          type: object
          additionalProperties: true
    CheckPaymentResponse:
      type: object
      required:
        - decision
        - risk
        - status
        - reason
        - suggestedAction
        - userMessage
        - checks
      properties:
        decision:
          $ref: "#/components/schemas/Decision"
        risk:
          $ref: "#/components/schemas/RiskLevel"
        status:
          type: string
        reason:
          type: string
        suggestedAction:
          type: string
        userMessage:
          type: string
        verifiedAlternative:
          type: string
          format: uri
        checks:
          $ref: "#/components/schemas/TrustChecks"
    Decision:
      type: string
      enum: [allow, caution, block, route]
    RiskLevel:
      type: string
      enum: [low, medium, high, unknown]
    TrustChecks:
      type: object
      properties:
        domainOwnership:
          type: string
        payToWallet:
          type: string
        payToWalletChanged:
          type: boolean
        deliveryReliability:
          type: string
        provenance:
          type: string
        priceSanity:
          type: string
    ProofResponse:
      type: object
      required:
        - name
        - canonical
        - generatedAt
        - counters
        - examples
      properties:
        name:
          type: string
        canonical:
          type: string
          format: uri
        generatedAt:
          type: string
          format: date-time
        classification:
          type: string
          enum: [proof-of-function, proof-of-demand]
        counters:
          type: object
          properties:
            internalDogfoodRuns:
              type: integer
              minimum: 0
            publicExampleRuns:
              type: integer
              minimum: 0
            externalReportedRuns:
              type: integer
              minimum: 0
            unsafePathsBlocked:
              type: integer
              minimum: 0
        examples:
          type: array
          items:
            type: object
            required:
              - title
              - href
            properties:
              title:
                type: string
              href:
                type: string
    ProjectProofResponse:
      type: object
      required:
        - projectHash
        - counters
        - runs
      properties:
        projectHash:
          type: string
          pattern: "^[a-f0-9]{24}$"
        generatedAt:
          type: string
          format: date-time
        scope:
          type: string
          enum: [token-backed-project-proof]
        counters:
          type: object
          properties:
            totalRuns:
              type: integer
            passedRuns:
              type: integer
            failedRuns:
              type: integer
            ciRuns:
              type: integer
            localRuns:
              type: integer
            unsafePathsBlocked:
              type: integer
            sandboxPassedRuns:
              type: integer
        byRail:
          type: array
          items:
            type: object
            properties:
              rail:
                type: string
              runs:
                type: integer
        runs:
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/ProjectProofRun"
    ProjectProofRun:
      type: object
      properties:
        receivedAt:
          type: string
          format: date-time
        status:
          type: string
          enum: [passed, failed, no_payment_flow_detected, failed_no_payment_flow]
        ci:
          type: boolean
        strict:
          type: boolean
        applicable:
          type: boolean
        rails:
          type: array
          items:
            type: string
        findingCount:
          type: integer
        sandboxPassed:
          type: boolean
        hasUnprotectedPaymentFiles:
          type: boolean