openapi: 3.1.0
info:
  title: Agent Health Monitor API
  description: 'Wallet intelligence API for autonomous agents on Base L2.


    Analyzes transaction failures, gas inefficiency, nonce issues, counterparty risk, and behavioural patterns. Returns actionable
    health reports, risk scores, gas optimization plans, and ready-to-sign retry transactions.


    **Payment:** All paid endpoints accept x402 protocol (USDC on Base) or a fiat-purchased API key via the `X-API-Key` header.


    **Free preview endpoints** are available for `/retry/preview` and `/agent/protect/preview`.


    **Coupon access** — partners can use coupon codes to access any paid endpoint without x402 payment via the `/coupon/{action}/{code}/{address}`
    routes.'
  contact:
    name: AHM Support
    url: https://agenthealthmonitor.xyz/
  license:
    name: Proprietary
  version: 1.8.0
servers:
- url: https://agenthealthmonitor.xyz
  description: Production
  x-apievangelist-note: 'Added by API Evangelist. The provider-served openapi.json at https://agenthealthmonitor.xyz/openapi.json
    declares no servers[]; the base is stated in the provider docs (docs.agenthealthmonitor.xyz API Quick Start: curl https://agenthealthmonitor.xyz/ahs/...)
    and in the README of github.com/moonshot-cyber/agent-health-monitor ("Base URL https://agenthealthmonitor.xyz"). Everything
    else in this file is the provider spec verbatim, converted from JSON to YAML.'
paths:
  /:
    get:
      tags:
      - Discovery & Info
      summary: Root
      description: 'Serve the marketing homepage, with its one live figure rendered in.


        The hero carries the ecosystem average AHS. It is a changing figure, so it

        is rendered from the database on every request rather than typed into the

        markup — it cannot go stale, and unlike the earlier client-fetched version

        it is present for crawlers, agents and curl instead of showing a dash.'
      operationId: root__get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
    head:
      tags:
      - Discovery & Info
      summary: Root
      description: 'Serve the marketing homepage, with its one live figure rendered in.


        The hero carries the ecosystem average AHS. It is a changing figure, so it

        is rendered from the database on every request rather than typed into the

        markup — it cannot go stale, and unlike the earlier client-fetched version

        it is present for crawlers, agents and curl instead of showing a dash.'
      operationId: root__get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /app:
    get:
      tags:
      - Discovery & Info
      summary: App Page
      description: Serve the developer tool (formerly the homepage).
      operationId: app_page_app_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /shield:
    get:
      tags:
      - Discovery & Info
      summary: Shield Page
      description: Serve the Shield SDK landing page.
      operationId: shield_page_shield_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /verify:
    get:
      tags:
      - Discovery & Info
      summary: Verify Page
      description: Serve the AHM Verify landing page.
      operationId: verify_page_verify_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /roadmap:
    get:
      tags:
      - Discovery & Info
      summary: Roadmap
      description: Serve the roadmap page.
      operationId: roadmap_roadmap_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /.well-known/agent-registration.json:
    get:
      tags:
      - Discovery & Info
      summary: Agent Registration
      description: ERC-8004 agent registration document.
      operationId: agent_registration__well_known_agent_registration_json_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /.well-known/agent.json:
    get:
      tags:
      - Discovery & Info
      summary: A2A Agent Card
      description: A2A Agent Card — public discovery endpoint per A2A protocol spec.
      operationId: a2a_agent_card__well_known_agent_json_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /.well-known/402index-verify.txt:
    get:
      tags:
      - Discovery & Info
      summary: Verify 402Index
      description: 402index.io domain verification token.
      operationId: verify_402index__well_known_402index_verify_txt_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /.well-known/x402:
    get:
      tags:
      - Discovery & Info
      summary: X402 Discovery
      description: 'x402 discovery document — lists all paid endpoints with payment

        requirements and bazaar metadata so crawlers like x402scan can

        auto-register the service.'
      operationId: x402_discovery__well_known_x402_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/info:
    get:
      tags:
      - Discovery & Info
      summary: Api Info
      description: Service info and pricing.
      operationId: api_info_api_info_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/ecosystem-stats:
    get:
      tags:
      - Discovery & Info
      summary: Ecosystem Stats
      description: Public aggregate ecosystem stats for the dashboard. No auth required.
      operationId: ecosystem_stats_api_ecosystem_stats_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/leaderboard:
    get:
      tags:
      - Discovery & Info
      summary: Leaderboard
      description: 'Public leaderboard: top 500 named agents by AHS score. No auth required.'
      operationId: leaderboard_api_leaderboard_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/agent/{address}:
    get:
      tags:
      - Discovery & Info
      summary: Get Agent Public
      description: 'Public agent profile: free-safe data for the Intelligence profile page.


        Returns composite score, grade, rank, percentile, and gap metrics.

        Dimensional breakdown (D1/D2/…) is excluded — that is the paid product.'
      operationId: get_agent_public_api_agent__address__get
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
          description: Ethereum wallet address (0x-prefixed, 40 hex chars)
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
          title: Address
        description: Ethereum wallet address (0x-prefixed, 40 hex chars)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentPublicProfile'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /scan/quality:
    get:
      tags:
      - Discovery & Info
      summary: Scan Quality
      description: Batch quality history for the last 30 days. No auth required.
      operationId: scan_quality_scan_quality_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /dashboard:
    get:
      tags:
      - Discovery & Info
      summary: Dashboard
      description: Serve the public ecosystem health dashboard, server-rendered.
      operationId: dashboard_dashboard_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /pay-by-card:
    get:
      tags:
      - Discovery & Info
      summary: Pay By Card
      description: Serve the card payment landing page.
      operationId: pay_by_card_pay_by_card_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/endpoint-info/{slug}:
    get:
      tags:
      - Discovery & Info
      summary: Endpoint Info
      description: Public endpoint metadata for marketing pages. No auth required.
      operationId: endpoint_info_api_endpoint_info__slug__get
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /endpoints/{slug}:
    get:
      tags:
      - Discovery & Info
      summary: Endpoint Page
      description: Serve the endpoint marketing page for any valid slug.
      operationId: endpoint_page_endpoints__slug__get
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /coupon/validate/{code}:
    get:
      tags:
      - Coupon Access
      summary: Validate Coupon
      description: Check if a coupon code is valid. Rate-limited to 5 attempts per IP per minute.
      operationId: validate_coupon_coupon_validate__code__get
      parameters:
      - name: code
        in: path
        required: true
        schema:
          type: string
          title: Code
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /coupon/risk/{code}/{address}:
    get:
      tags:
      - Coupon Access
      summary: Coupon Risk
      description: Quick risk score via coupon — mirrors GET /risk/{address}.
      operationId: coupon_risk_coupon_risk__code___address__get
      parameters:
      - name: code
        in: path
        required: true
        schema:
          type: string
          title: Code
      - name: address
        in: path
        required: true
        schema:
          type: string
          description: Ethereum wallet address (0x-prefixed, 40 hex chars)
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
          title: Address
        description: Ethereum wallet address (0x-prefixed, 40 hex chars)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /coupon/health/{code}/{address}:
    get:
      tags:
      - Coupon Access
      summary: Coupon Health
      description: Wallet health diagnosis via coupon — mirrors GET /health/{address}.
      operationId: coupon_health_coupon_health__code___address__get
      parameters:
      - name: code
        in: path
        required: true
        schema:
          type: string
          title: Code
      - name: address
        in: path
        required: true
        schema:
          type: string
          description: Ethereum wallet address (0x-prefixed, 40 hex chars)
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
          title: Address
        description: Ethereum wallet address (0x-prefixed, 40 hex chars)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /coupon/optimize/{code}/{address}:
    get:
      tags:
      - Coupon Access
      summary: Coupon Optimize
      description: Gas optimization report via coupon — mirrors GET /optimize/{address}.
      operationId: coupon_optimize_coupon_optimize__code___address__get
      parameters:
      - name: code
        in: path
        required: true
        schema:
          type: string
          title: Code
      - name: address
        in: path
        required: true
        schema:
          type: string
          description: Ethereum wallet address (0x-prefixed, 40 hex chars)
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
          title: Address
        description: Ethereum wallet address (0x-prefixed, 40 hex chars)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /coupon/retry/{code}/{address}:
    get:
      tags:
      - Coupon Access
      summary: Coupon Retry
      description: Retry bot via coupon — mirrors GET /retry/{address}.
      operationId: coupon_retry_coupon_retry__code___address__get
      parameters:
      - name: code
        in: path
        required: true
        schema:
          type: string
          title: Code
      - name: address
        in: path
        required: true
        schema:
          type: string
          description: Ethereum wallet address (0x-prefixed, 40 hex chars)
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
          title: Address
        description: Ethereum wallet address (0x-prefixed, 40 hex chars)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /coupon/protect/{code}/{address}:
    get:
      tags:
      - Coupon Access
      summary: Coupon Protect
      description: Full protection agent via coupon — mirrors GET /agent/protect/{address}.
      operationId: coupon_protect_coupon_protect__code___address__get
      parameters:
      - name: code
        in: path
        required: true
        schema:
          type: string
          title: Code
      - name: address
        in: path
        required: true
        schema:
          type: string
          description: Ethereum wallet address (0x-prefixed, 40 hex chars)
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
          title: Address
        description: Ethereum wallet address (0x-prefixed, 40 hex chars)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /coupon/alerts/{code}/{address}:
    get:
      tags:
      - Coupon Access
      summary: Coupon Alerts
      description: Alert subscription via coupon — mirrors GET /alerts/subscribe/{address}.
      operationId: coupon_alerts_coupon_alerts__code___address__get
      parameters:
      - name: code
        in: path
        required: true
        schema:
          type: string
          title: Code
      - name: address
        in: path
        required: true
        schema:
          type: string
          description: Ethereum wallet address (0x-prefixed, 40 hex chars)
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
          title: Address
        description: Ethereum wallet address (0x-prefixed, 40 hex chars)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /coupon/risk-premium/{code}/{address}:
    get:
      tags:
      - Coupon Access
      summary: Coupon Premium Risk
      description: Premium risk score via coupon — mirrors GET /risk/premium/{address}.
      operationId: coupon_premium_risk_coupon_risk_premium__code___address__get
      parameters:
      - name: code
        in: path
        required: true
        schema:
          type: string
          title: Code
      - name: address
        in: path
        required: true
        schema:
          type: string
          description: Ethereum wallet address (0x-prefixed, 40 hex chars)
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
          title: Address
        description: Ethereum wallet address (0x-prefixed, 40 hex chars)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /coupon/counterparties/{code}/{address}:
    get:
      tags:
      - Coupon Access
      summary: Coupon Counterparties
      description: Counterparty analysis via coupon — mirrors GET /counterparties/{address}.
      operationId: coupon_counterparties_coupon_counterparties__code___address__get
      parameters:
      - name: code
        in: path
        required: true
        schema:
          type: string
          title: Code
      - name: address
        in: path
        required: true
        schema:
          type: string
          description: Ethereum wallet address (0x-prefixed, 40 hex chars)
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
          title: Address
        description: Ethereum wallet address (0x-prefixed, 40 hex chars)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /coupon/network-map/{code}/{address}:
    get:
      tags:
      - Coupon Access
      summary: Coupon Network Map
      description: Network map via coupon — mirrors GET /network-map/{address}.
      operationId: coupon_network_map_coupon_network_map__code___address__get
      parameters:
      - name: code
        in: path
        required: true
        schema:
          type: string
          title: Code
      - name: address
        in: path
        required: true
        schema:
          type: string
          description: Ethereum wallet address (0x-prefixed, 40 hex chars)
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
          title: Address
        description: Ethereum wallet address (0x-prefixed, 40 hex chars)
      - name: chain
        in: query
        required: false
        schema:
          type: string
          default: ethereum
          title: Chain
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /coupon/wash/{code}/{address}:
    get:
      tags:
      - Coupon Access
      summary: Coupon Wash
      description: Hygiene scan via coupon — mirrors POST /wash/{address}.
      operationId: coupon_wash_coupon_wash__code___address__get
      parameters:
      - name: code
        in: path
        required: true
        schema:
          type: string
          title: Code
      - name: address
        in: path
        required: true
        schema:
          type: string
          description: Ethereum wallet address (0x-prefixed, 40 hex chars)
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
          title: Address
        description: Ethereum wallet address (0x-prefixed, 40 hex chars)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /coupon/ahs/{code}/{address}:
    get:
      tags:
      - Coupon Access
      summary: Coupon Ahs
      description: Agent Health Score via coupon — mirrors GET /ahs/{address}.
      operationId: coupon_ahs_coupon_ahs__code___address__get
      parameters:
      - name: code
        in: path
        required: true
        schema:
          type: string
          title: Code
      - name: address
        in: path
        required: true
        schema:
          type: string
          description: Ethereum wallet address (0x-prefixed, 40 hex chars)
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
          title: Address
        description: Ethereum wallet address (0x-prefixed, 40 hex chars)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /coupon/report-card/{code}/{address}:
    get:
      tags:
      - Coupon Access
      summary: Coupon Report Card
      description: Visual report card via coupon — mirrors GET /report-card/{address}.
      operationId: coupon_report_card_coupon_report_card__code___address__get
      parameters:
      - name: code
        in: path
        required: true
        schema:
          type: string
          title: Code
      - name: address
        in: path
        required: true
        schema:
          type: string
          description: Ethereum wallet address (0x-prefixed, 40 hex chars)
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
          title: Address
        description: Ethereum wallet address (0x-prefixed, 40 hex chars)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /chat:
    post:
      tags:
      - Utility
      summary: Chat
      description: AI chat about wallet analysis results.
      operationId: chat_chat_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /up:
    get:
      tags:
      - Utility
      summary: Up
      description: Unpaid liveness probe for load balancers.
      operationId: up_up_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /risk/premium/{address}:
    get:
      tags:
      - Scoring & Risk
      summary: Get Premium Risk Score
      description: 'Premium risk score enriched with Nansen wallet intelligence, PnL data,

        and operational health metrics (transaction failure rate analysis).


        Requires x402 payment ($0.05 USDC on Base) OR valid X-API-Key / X-Internal-Key header.


        Returns a 0-100 risk score plus Nansen smart money tags,

        entity labels, behavioral signals, PnL summary, and operational

        health (1hr/24hr revert rates, nonce gaps, volume anomalies).

        PnL data adjusts the risk score: profitable wallets get up to -10,

        unprofitable wallets get up to +10. Operational health adjusts:

        degraded +5, critical +10.'
      operationId: get_premium_risk_score_risk_premium__address__get
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
          description: Ethereum wallet address (0x-prefixed, 40 hex chars)
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
          title: Address
        description: Ethereum wallet address (0x-prefixed, 40 hex chars)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PremiumRiskResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /counterparties/{address}:
    get:
      tags:
      - Scoring & Risk
      summary: Get Counterparties
      description: 'Know Your Counterparty — top wallets/contracts this address interacts with.


        Requires x402 payment ($0.10 USDC on Base) OR valid X-API-Key / X-Internal-Key header.


        Returns the top counterparties ranked by interaction count, enriched

        with Nansen labels where available.'
      operationId: get_counterparties_counterparties__address__get
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
          description: Ethereum wallet address (0x-prefixed, 40 hex chars)
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
          title: Address
        description: Ethereum wallet address (0x-prefixed, 40 hex chars)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CounterpartyResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /network-map/{address}:
    get:
      tags:
      - Scoring & Risk
      summary: Get Network Map
      description: "Wallet Network Map — related wallets linked by funding, deployment, or multisig.\n\nRequires x402 payment\
        \ ($0.10 USDC on Base) OR valid X-API-Key / X-Internal-Key header.\n\nReturns wallets connected to this address via\
        \ first-funder relationships,\ncontract deployments, and multisig co-signer links, enriched with Nansen labels.\n\n\
        Query params:\n    chain: blockchain to query (default: ethereum). Does NOT support \"all\".\n           Valid: arbitrum,\
        \ avalanche, base, bnb, ethereum, polygon, solana, etc."
      operationId: get_network_map_network_map__address__get
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
          description: Ethereum wallet address (0x-prefixed, 40 hex chars)
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
          title: Address
        description: Ethereum wallet address (0x-prefixed, 40 hex chars)
      - name: chain
        in: query
        required: false
        schema:
          type: string
          default: ethereum
          title: Chain
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RelatedWalletsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /risk/{address}:
    get:
      tags:
      - Scoring & Risk
      summary: Get Risk Score
      description: 'Quick risk score for agent pre-flight checks.


        Requires x402 payment ($0.001 USDC on Base) OR valid X-API-Key / X-Internal-Key header.


        Returns a 0-100 risk score derived from transaction failure rate,

        wallet age, and contract interaction patterns. Designed for

        high-volume, low-latency use.'
      operationId: get_risk_score_risk__address__get
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
          description: Ethereum wallet address (0x-prefixed, 40 hex chars)
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
          title: Address
        description: Ethereum wallet address (0x-prefixed, 40 hex chars)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiskResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /health/{address}:
    get:
      tags:
      - Health & Hygiene
      summary: Get Health Report
      description: 'Analyze a Base wallet address and return a health report.


        Requires x402 payment ($0.50 USDC on Base) OR valid X-API-Key / X-Internal-Key header.


        - Fetches transaction history from Blockscout

        - Calculates success rate, gas efficiency, nonce health

        - Computes composite health score (0-100)

        - Generates specific optimization recommendations'
      operationId: get_health_report_health__address__get
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
          description: Ethereum wallet address (0x-prefixed, 40 hex chars)
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
          title: Address
        description: Ethereum wallet address (0x-prefixed, 40 hex chars)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /wash/{address}:
    post:
      tags:
      - Health & Hygiene
      summary: Get Wash Report
      description: 'Agent Wash: Hygiene scan for Base wallet addresses.


        Requires x402 payment ($0.50 USDC on Base) OR valid X-API-Key / X-Internal-Key header.


        Scans for:

        - Dust tokens (< $0.01 value)

        - Spam tokens (URL names, low holders, zero volume)

        - Gas efficiency (gasUsed/gas ratio analysis)

        - Failed transaction patterns (repeated failures, retry storms)

        - Nonce gaps


        Returns a cleanliness score (0-100) with prioritised cleanup recommendations.'
      operationId: get_wash_report_wash__address__post
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
          description: Ethereum wallet address (0x-prefixed, 40 hex chars)
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
          title: Address
        description: Ethereum wallet address (0x-prefixed, 40 hex chars)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WashResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /ahs/{address}:
    get:
      tags:
      - Health & Hygiene
      summary: Get Ahs Report
      description: 'Agent Health Score: Composite 0-100 index for on-chain agent wallets.


        Requires x402 payment ($1.00 USDC on Base) OR valid X-API-Key / X-Internal-Key header.


        Three dimensions:

        - D1 Wallet Hygiene (dust, spam, gas efficiency, failure rate, nonce gaps)

        - D2 Behavioural Patterns (repeated failures, gas adaptation, timing, diversity, retry storms)

        - D3 Infrastructure Health (optional — provide ?agent_url= to enable 3D mode)


        Plus cross-dimensional pattern detection (Zombie Agent, Cascading Failure, etc.)

        and temporal scoring via X-AHS-Previous JWT header.'
      operationId: get_ahs_report_ahs__address__get
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
          description: Ethereum wallet address (0x-prefixed, 40 hex chars)
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
          title: Address
        description: Ethereum wallet address (0x-prefixed, 40 hex chars)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AHSResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /ahs/route/policy:
    get:
      tags:
      - Health & Hygiene
      summary: Get Routing Policy
      description: 'Return the caller''s current routing policy configuration.


        Requires X-API-Key or x402 payment for authentication. Returns default

        thresholds if no custom policy has been configured.'
      operationId: get_routing_policy_ahs_route_policy_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoutingPolicyResponse'
    put:
      tags:
      - Health & Hygiene
      summary: Put Routing Policy
      description: 'Create or update the caller''s routing policy.


        Requires X-API-Key or x402 payment ($0.01). Validates that:

        - All 6 grades (A-F) are assigned to exactly one category

        - escrow_disabled consistency (no escrow grades when disabled)

        - Allowlist addresses are valid, max 1000

        - No self-allowlisting (caller''s own address)

        - Allowlisted addresses must have AHS Grade C or above'
      operationId: put_routing_policy_ahs_route_policy_put
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoutingPolicyRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoutingPolicyResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /ahs/route/{address}:
    get:
      tags:
      - Health & Hygiene
      summary: Get Trust Route
      description: 'Lightweight trust routing signal from the most recent cached AHS score.


        Returns a routing recommendation (instant_settle / escrow / reject) without

        re-running the full AHS scoring pipeline.  Useful for payment gateways and

        agent orchestrators that need a fast trust check.'
      operationId: get_trust_route_ahs_route__address__get
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
          description: Ethereum wallet address (0x-prefixed, 40 hex chars)
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
          title: Address
        description: Ethereum wallet address (0x-prefixed, 40 hex chars)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrustRouteResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /ahs/batch:
    post:
      tags:
      - Health & Hygiene
      summary: Get Ahs Batch
      description: "Batch Agent Health Score: score multiple wallets in a single call.\n\nTwo tiers apply — see canonical.json\
        \ -> batch. Pricing:\n- **x402 path:** flat batch price, capped at BATCH_X402_MAX wallets per call.\n- **API key path:**\
        \ 1 credit per wallet scored. Supports partial results\n  if credits are insufficient (scores as many as credits allow).\n\
        \nResults include the same AHS scoring as the single GET /ahs/{address}\nendpoint — composite 0-100 score with D1/D2\
        \ dimension breakdown,\npattern detection, and recommendations."
      operationId: get_ahs_batch_ahs_batch_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AHSBatchRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AHSBatchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /report-card/{address}:
    get:
      tags:
      - Health & Hygiene
      summary: Get Report Card
      description: 'Agent Report Card: Visual health report card with ecosystem benchmarks.


        Requires x402 payment ($2.00 USDC on Base) OR valid X-API-Key / X-Internal-Key header.


        Runs a full AHS scan, pulls ecosystem comparison data, and generates

        a personalised 1200x675 PNG report card image. Returns JSON with scores,

        benchmarks, and a URL to the generated image.'
      operationId: get_report_card_report_card__address__get
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
          description: Ethereum wallet address (0x-prefixed, 40 hex chars)
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
          title: Address
        description: Ethereum wallet address (0x-prefixed, 40 hex chars)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportCardResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /optimize/{address}:
    get:
      tags:
      - Optimization
      summary: Get Optimization Report
      description: 'Analyze a Base wallet and return a gas optimization report.


        Requires x402 payment ($5.00 USDC on Base) OR valid X-API-Key / X-Internal-Key header.


        - Groups transactions by type (contract + method)

        - Calculates optimal gas limits per type

        - Identifies wasted gas from failed transactions

        - Estimates monthly savings with before/after comparison'
      operationId: get_optimization_report_optimize__address__get
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
          description: Ethereum wallet address (0x-prefixed, 40 hex chars)
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
          title: Address
        description: Ethereum wallet address (0x-prefixed, 40 hex chars)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptimizeResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /agent/protect/preview/{address}:
    get:
      tags:
      - Protection
      summary: Protection Preview
      description: 'Free preview of protection agent analysis.


        Shows wallet risk level, health score, and which services

        would be run without executing the full analysis.'
      operationId: protection_preview_agent_protect_preview__address__get
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
          description: Ethereum wallet address (0x-prefixed, 40 hex chars)
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
          title: Address
        description: Ethereum wallet address (0x-prefixed, 40 hex chars)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProtectionPreviewResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /agent/protect/{address}:
    get:
      tags:
      - Protection
      summary: Get Protection Report
      description: 'Autonomous protection agent — full wallet analysis and action plan.


        Requires x402 payment ($25.00 USDC on Base) OR valid X-API-Key / X-Internal-Key header.


        Triages wallet risk and runs the appropriate services:

        - Score 90-100: Low risk — health report + recommend alerts

        - Score 70-89: Medium risk — health + gas optimization

        - Score 50-69: High risk — health + gas optimization + retry bot

        - Score 0-49: Critical — all services, urgent flagging


        Returns a unified report with all results and prioritized actions

        ranked by potential value recovered.'
      operationId: get_protection_report_agent_protect__address__get
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
          description: Ethereum wallet address (0x-prefixed, 40 hex chars)
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
          title: Address
        description: Ethereum wallet address (0x-prefixed, 40 hex chars)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProtectionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /retry/preview/{address}:
    get:
      tags:
      - Optimization
      summary: Retry Preview
      description: 'Free preview of retryable failed transactions.


        Shows count of retryable failures and estimated savings

        without returning the full optimized transactions.'
      operationId: retry_preview_retry_preview__address__get
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
          description: Ethereum wallet address (0x-prefixed, 40 hex chars)
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
          title: Address
        description: Ethereum wallet address (0x-prefixed, 40 hex chars)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetryPreviewResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /retry/{address}:
    get:
      tags:
      - Optimization
      summary: Get Retry Transactions
      description: 'Analyze failed transactions and return optimized retry transactions.


        Requires x402 payment ($10.00 USDC on Base) OR valid X-API-Key / X-Internal-Key header.


        Non-custodial: returns ready-to-sign transaction objects.

        The agent signs and submits the transactions themselves.


        - Fetches failed transactions from Blockscout

        - Classifies failure reasons: out_of_gas, reverted, nonce_conflict, slippage

        - Filters to retryable failures only

        - Builds optimized replacements with corrected gas parameters

        - Returns ready-to-sign EIP-1559 transaction objects'
      operationId: get_retry_transactions_retry__address__get
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
          description: Ethereum wallet address (0x-prefixed, 40 hex chars)
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
          title: Address
        description: Ethereum wallet address (0x-prefixed, 40 hex chars)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /alerts/subscribe/{address}:
    get:
      tags:
      - Alerts
      summary: Subscribe Alerts
      description: 'Subscribe a wallet to automated health monitoring (30 days).


        Requires x402 payment ($2.00 USDC on Base) OR valid X-API-Key header.


        After payment, configure your webhook via POST /alerts/configure.

        Health checks run every 6 hours and send alerts when thresholds are breached.'
      operationId: subscribe_alerts_alerts_subscribe__address__get
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
          description: Ethereum wallet address (0x-prefixed, 40 hex chars)
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
          title: Address
        description: Ethereum wallet address (0x-prefixed, 40 hex chars)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /alerts/configure:
    post:
      tags:
      - Alerts
      summary: Configure Alerts
      description: 'Configure webhook and thresholds for an active alert subscription.


        No payment required — must have an active subscription from GET /alerts/subscribe/{address}.'
      operationId: configure_alerts_alerts_configure_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigureRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /alerts/status/{address}:
    get:
      tags:
      - Alerts
      summary: Alert Status
      description: Check the status of an alert subscription.
      operationId: alert_status_alerts_status__address__get
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
          description: Ethereum wallet address (0x-prefixed, 40 hex chars)
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
          title: Address
        description: Ethereum wallet address (0x-prefixed, 40 hex chars)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /alerts/unsubscribe/{address}:
    delete:
      tags:
      - Alerts
      summary: Unsubscribe Alerts
      description: Remove an alert subscription.
      operationId: unsubscribe_alerts_alerts_unsubscribe__address__delete
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
          description: Ethereum wallet address (0x-prefixed, 40 hex chars)
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
          title: Address
        description: Ethereum wallet address (0x-prefixed, 40 hex chars)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /stripe/webhook:
    post:
      tags:
      - Billing
      summary: Stripe Webhook
      description: "Unified Stripe webhook handler for all payment events.\n\nHandles:\n- checkout.session.completed — issues\
        \ an API key (core) or creates\n  a Shield subscription (when metadata.product == \"shield\")\n- customer.subscription.updated\
        \ — updates Shield subscription status\n- customer.subscription.deleted — cancels Shield subscription"
      operationId: stripe_webhook_stripe_webhook_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /stripe/webhook/test:
    post:
      tags:
      - Billing
      summary: Stripe Webhook Test
      description: 'Test endpoint: simulate a Stripe checkout.session.completed event.


        Protected by X-Internal-Key header. For development/testing only.

        Generates a real API key for the given email without requiring Stripe.'
      operationId: stripe_webhook_test_stripe_webhook_test_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestWebhookRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /stripe/key/{session_id}:
    get:
      tags:
      - Billing
      summary: Retrieve Key
      description: 'One-time retrieval of an API key after Stripe checkout.


        Returns the plaintext key exactly once. Subsequent calls return

        ``{"status": "consumed"}``.  Expired (>24 h) or unknown session IDs

        return the corresponding status.'
      operationId: retrieve_key_stripe_key__session_id__get
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /checkout/success:
    get:
      tags:
      - Billing
      summary: Checkout Success Page
      description: Post-checkout success page — retrieves and displays the API key once.
      operationId: checkout_success_page_checkout_success_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /shield/subscribe:
    post:
      tags:
      - Billing
      summary: Shield Subscribe
      description: 'Create a Stripe Checkout session for a Shield subscription tier.


        Requires a valid X-API-Key header. The subscription will be linked to

        the API key used for authentication.'
      operationId: shield_subscribe_shield_subscribe_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShieldSubscribeRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/key/status:
    get:
      tags:
      - Billing
      summary: Api Key Status
      description: 'Check the status of an API key.


        Requires X-API-Key header. Returns tier, remaining calls, and key metadata.'
      operationId: api_key_status_api_key_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /partners/{partner_id}/usage:
    get:
      tags:
      - Billing
      summary: Partner Usage
      description: 'Usage report for a Shield reseller partner.


        Protected by X-Internal-Key header. Returns call count, wholesale cost,

        and billing period for the given partner_id.'
      operationId: partner_usage_partners__partner_id__usage_get
      parameters:
      - name: partner_id
        in: path
        required: true
        schema:
          type: string
          title: Partner Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /security/activity:
    get:
      tags:
      - Admin
      summary: Security Activity
      description: 'Recent security events (rate limits, suspicious patterns).


        Protected by X-Internal-Key header. Not accessible via x402 payment.'
      operationId: security_activity_security_activity_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /trust-registry:
    get:
      tags:
      - Admin
      summary: Trust Registry
      description: 'Aggregated scan statistics for the AHM trust layer.


        Protected by X-Internal-Key header. Not accessible via x402 payment.'
      operationId: trust_registry_trust_registry_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /internal/agent-profile/{address}:
    get:
      tags:
      - Admin
      summary: Internal Agent Profile
      description: 'Return AHS profile context for a single agent address.


        Protected by X-Internal-Key header. Used by ahm-verify to fetch

        agent scoring context for the adjudication panel.'
      operationId: internal_agent_profile_internal_agent_profile__address__get
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
          title: Address
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /acp-scan/trigger:
    post:
      tags:
      - Admin
      summary: Trigger Acp Scan
      description: 'Manually trigger the ACP nightly scan.


        Protected by X-Internal-Key header. Returns immediately;

        scan runs in the background.'
      operationId: trigger_acp_scan_acp_scan_trigger_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /acp-scan/status:
    get:
      tags:
      - Admin
      summary: Acp Scan Status
      description: 'Check if an ACP scan is currently running.


        Protected by X-Internal-Key header.'
      operationId: acp_scan_status_acp_scan_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /olas-scan/trigger:
    post:
      tags:
      - Admin
      summary: Trigger Olas Scan
      description: 'Manually trigger the Olas nightly scan.


        Protected by X-Internal-Key header. Returns immediately;

        scan runs in the background.'
      operationId: trigger_olas_scan_olas_scan_trigger_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /olas-scan/status:
    get:
      tags:
      - Admin
      summary: Olas Scan Status
      description: 'Check if an Olas scan is currently running.


        Protected by X-Internal-Key header.


        Also queries ``totalSupply()`` on the Olas ServiceRegistryL2 contract

        on Base so the dashboard can render a live saturation figure

        (e.g. "887 / 900") instead of looking stalled when the nightly

        scanner has already caught up to the registry. Any RPC failure is

        caught and surfaced as ``registry_total_supply: null`` rather than

        failing the whole status endpoint.'
      operationId: olas_scan_status_olas_scan_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /arc-scan/trigger:
    post:
      tags:
      - Admin
      summary: Trigger Arc Scan
      description: 'Manually trigger the Arc nightly scan.


        Protected by X-Internal-Key header. Returns immediately;

        scan runs in the background.'
      operationId: trigger_arc_scan_arc_scan_trigger_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /arc-scan/status:
    get:
      tags:
      - Admin
      summary: Arc Scan Status
      description: 'Check if an Arc scan is currently running.


        Protected by X-Internal-Key header.'
      operationId: arc_scan_status_arc_scan_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /celo-scan/trigger:
    post:
      tags:
      - Admin
      summary: Trigger Celo Scan
      description: 'Manually trigger the Celo nightly scan.


        Protected by X-Internal-Key header. Returns immediately;

        scan runs in the background.'
      operationId: trigger_celo_scan_celo_scan_trigger_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /celo-scan/status:
    get:
      tags:
      - Admin
      summary: Celo Scan Status
      description: 'Check if a Celo scan is currently running.


        Protected by X-Internal-Key header.'
      operationId: celo_scan_status_celo_scan_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /erc8004-scan/trigger:
    post:
      tags:
      - Admin
      summary: Trigger Erc8004 Scan
      description: 'Manually trigger the ERC-8004 Base-mainnet nightly scan.


        Protected by X-Internal-Key header. Returns immediately;

        scan runs in the background.'
      operationId: trigger_erc8004_scan_erc8004_scan_trigger_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /erc8004-scan/status:
    get:
      tags:
      - Admin
      summary: Erc8004 Scan Status
      description: 'Check if an ERC-8004 Base-mainnet scan is currently running.


        Protected by X-Internal-Key header.'
      operationId: erc8004_scan_status_erc8004_scan_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /erc8183/status:
    get:
      tags:
      - Admin
      summary: Erc8183 Status
      description: 'Check ERC-8183 evaluator worker status on Arc testnet.


        Protected by X-Internal-Key header.'
      operationId: erc8183_status_erc8183_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
components:
  schemas:
    AHSBatchRequest:
      properties:
        addresses:
          items:
            type: string
          type: array
          title: Addresses
        page:
          type: integer
          title: Page
          default: 1
        page_size:
          type: integer
          title: Page Size
          default: 10
      type: object
      required:
      - addresses
      title: AHSBatchRequest
    AHSBatchResponse:
      properties:
        results:
          items:
            $ref: '#/components/schemas/AHSBatchResultItem'
          type: array
          title: Results
        page:
          type: integer
          title: Page
        page_size:
          type: integer
          title: Page Size
        total_addresses:
          type: integer
          title: Total Addresses
        total_scored:
          type: integer
          title: Total Scored
        credits_used:
          type: integer
          title: Credits Used
        credits_remaining:
          anyOf:
          - type: integer
          - type: 'null'
          title: Credits Remaining
        errors:
          items:
            type: string
          type: array
          title: Errors
      type: object
      required:
      - results
      - page
      - page_size
      - total_addresses
      - total_scored
      - credits_used
      - errors
      title: AHSBatchResponse
    AHSBatchResultItem:
      properties:
        address:
          type: string
          title: Address
        ahs_score:
          type: integer
          title: Ahs Score
        grade:
          type: string
          title: Grade
        d1_score:
          type: integer
          title: D1 Score
        d2_score:
          type: integer
          title: D2 Score
        pattern:
          type: string
          title: Pattern
        verdict:
          type: string
          title: Verdict
        routing_recommendation:
          type: string
          title: Routing Recommendation
      type: object
      required:
      - address
      - ahs_score
      - grade
      - d1_score
      - d2_score
      - pattern
      - verdict
      - routing_recommendation
      title: AHSBatchResultItem
    AHSCrossDimensionalPattern:
      properties:
        name:
          type: string
          title: Name
          description: Pattern identifier
          examples:
          - Zombie Agent
        detected:
          type: boolean
          title: Detected
          description: Whether this pattern was detected
          examples:
          - true
        severity:
          type: string
          title: Severity
          description: 'Pattern severity: info, warning, or critical'
          examples:
          - warning
        description:
          type: string
          title: Description
          description: Human-readable explanation
          examples:
          - Wallet shows signs of abandoned automation
      type: object
      required:
      - name
      - detected
      - severity
      - description
      title: AHSCrossDimensionalPattern
    AHSDimensionScore:
      properties:
        dimension:
          type: string
          title: Dimension
        score:
          type: integer
          title: Score
        weight:
          type: number
          title: Weight
        contributing_factors:
          items: {}
          type: array
          title: Contributing Factors
      type: object
      required:
      - dimension
      - score
      - weight
      - contributing_factors
      title: AHSDimensionScore
    AHSReport:
      properties:
        address:
          type: string
          title: Address
          description: Wallet address scored
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
        agent_health_score:
          type: integer
          title: Agent Health Score
          description: Composite AHS score 0-100
          examples:
          - 67
        grade:
          type: string
          title: Grade
          description: Letter grade A-F
          examples:
          - C
        confidence:
          type: string
          title: Confidence
          description: 'Score confidence level: high, medium, or low'
          examples:
          - high
        mode:
          type: string
          title: Mode
          description: 'Scoring mode: 2D (wallet + behavioural) or 3D (+ infrastructure)'
          examples:
          - 2D
        dimensions:
          items:
            $ref: '#/components/schemas/AHSDimensionScore'
          type: array
          title: Dimensions
          description: Per-dimension score breakdown
        patterns_detected:
          items:
            $ref: '#/components/schemas/AHSCrossDimensionalPattern'
          type: array
          title: Patterns Detected
          description: Cross-dimensional anomaly patterns detected
        trend:
          anyOf:
          - type: string
          - type: 'null'
          title: Trend
          description: 'Score trend vs previous scan: improving, stable, or declining'
          examples:
          - stable
        recommendations:
          items:
            type: string
          type: array
          title: Recommendations
          description: Prioritised improvement recommendations
          examples:
          - - Reduce revert rate below 5% to improve D1 score
            - Investigate Zombie Agent pattern
        ahs_token:
          type: string
          title: Ahs Token
          description: JWT token for temporal trend tracking across scans
          examples:
          - eyJhbGciOiJIUzI1NiIs...
        model_version:
          type: string
          title: Model Version
          description: AHS scoring model version
          examples:
          - 2.1.0
        scan_timestamp:
          type: string
          title: Scan Timestamp
          description: ISO 8601 timestamp of this scan
          examples:
          - '2025-04-06T10:00:00Z'
        next_scan_recommended:
          type: string
          title: Next Scan Recommended
          description: Recommended next scan date
          examples:
          - '2025-04-13T10:00:00Z'
        shadow_signals:
          anyOf:
          - $ref: '#/components/schemas/AHSShadowSignals'
          - type: 'null'
          description: Shadow signal analysis (session continuity, budget exhaustion)
        routing_recommendation:
          type: string
          title: Routing Recommendation
          description: 'Trust-based routing signal: instant_settle, escrow, or reject'
          examples:
          - escrow
      type: object
      required:
      - address
      - agent_health_score
      - grade
      - confidence
      - mode
      - dimensions
      - patterns_detected
      - recommendations
      - ahs_token
      - model_version
      - scan_timestamp
      - next_scan_recommended
      - routing_recommendation
      title: AHSReport
    AHSResponse:
      properties:
        status:
          type: string
          title: Status
          description: Response status
          examples:
          - ok
        report:
          $ref: '#/components/schemas/AHSReport'
          description: Full Agent Health Score report
      type: object
      required:
      - status
      - report
      title: AHSResponse
    AHSShadowSignals:
      properties:
        session_continuity_score:
          anyOf:
          - type: integer
          - type: 'null'
          title: Session Continuity Score
        abrupt_sessions:
          type: integer
          title: Abrupt Sessions
          default: 0
        budget_exhaustion_count:
          type: integer
          title: Budget Exhaustion Count
          default: 0
        total_sessions:
          type: integer
          title: Total Sessions
          default: 0
        avg_session_length:
          type: number
          title: Avg Session Length
          default: 0.0
        shadow_patterns:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Shadow Patterns
          default: []
      type: object
      title: AHSShadowSignals
    AgentPublicProfile:
      properties:
        address:
          type: string
          title: Address
        agent_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Name
        registries:
          anyOf:
          - type: string
          - type: 'null'
          title: Registries
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
        latest_ahs:
          anyOf:
          - type: integer
          - type: 'null'
          title: Latest Ahs
        latest_grade:
          anyOf:
          - type: string
          - type: 'null'
          title: Latest Grade
        rank:
          anyOf:
          - type: integer
          - type: 'null'
          title: Rank
        percentile_rank:
          anyOf:
          - type: number
          - type: 'null'
          title: Percentile Rank
        first_seen_at:
          anyOf:
          - type: string
          - type: 'null'
          title: First Seen At
        last_scanned_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Scanned At
        scan_count:
          type: integer
          title: Scan Count
          default: 0
        gap_to_next_rank:
          anyOf:
          - type: integer
          - type: 'null'
          title: Gap To Next Rank
        gap_to_next_tier:
          anyOf:
          - type: integer
          - type: 'null'
          title: Gap To Next Tier
      type: object
      required:
      - address
      title: AgentPublicProfile
      description: 'Free-safe agent profile for the public profile page.


        This model is the security gate: only explicitly listed fields can be

        serialised.  Dimensional scores (d1, d2, …) are structurally excluded.'
    AlertThresholds:
      properties:
        health_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Health Score
        failure_rate:
          anyOf:
          - type: number
          - type: 'null'
          title: Failure Rate
        waste_usd:
          anyOf:
          - type: number
          - type: 'null'
          title: Waste Usd
      type: object
      title: AlertThresholds
    ChatRequest:
      properties:
        message:
          type: string
          title: Message
        context:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Context
      type: object
      required:
      - message
      title: ChatRequest
    ConfigureRequest:
      properties:
        address:
          type: string
          title: Address
        webhook_url:
          type: string
          title: Webhook Url
        webhook_type:
          type: string
          title: Webhook Type
          default: generic
        thresholds:
          anyOf:
          - $ref: '#/components/schemas/AlertThresholds'
          - type: 'null'
      type: object
      required:
      - address
      - webhook_url
      title: ConfigureRequest
    Counterparty:
      properties:
        address:
          type: string
          title: Address
        label:
          anyOf:
          - type: string
          - type: 'null'
          title: Label
        interaction_count:
          type: integer
          title: Interaction Count
          default: 0
        volume_usd:
          type: number
          title: Volume Usd
          default: 0.0
        last_interaction:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Interaction
      type: object
      required:
      - address
      title: Counterparty
    CounterpartyResponse:
      properties:
        status:
          type: string
          title: Status
        address:
          type: string
          title: Address
        counterparties:
          items:
            $ref: '#/components/schemas/Counterparty'
          type: array
          title: Counterparties
          default: []
        total_counterparties:
          type: integer
          title: Total Counterparties
          default: 0
        nansen_available:
          type: boolean
          title: Nansen Available
          default: false
      type: object
      required:
      - status
      - address
      title: CounterpartyResponse
    EcosystemComparison:
      properties:
        average_ahs:
          anyOf:
          - type: number
          - type: 'null'
          title: Average Ahs
          description: Ecosystem-wide average AHS score
          examples:
          - 58.3
        percentile_rank:
          type: integer
          title: Percentile Rank
          description: This wallet's percentile rank in the ecosystem (0-100)
          examples:
          - 72
        grade_distribution:
          additionalProperties: true
          type: object
          title: Grade Distribution
          description: Grade distribution across all scored agents
          examples:
          - A: 8
            B: 22
            C: 45
            D: 18
            F: 7
        total_agents_scored:
          type: integer
          title: Total Agents Scored
          description: Total agents in the comparison pool
          examples:
          - 1247
      type: object
      required:
      - percentile_rank
      - grade_distribution
      - total_agents_scored
      title: EcosystemComparison
    GasOptimizationReport:
      properties:
        address:
          type: string
          title: Address
        total_transactions_analyzed:
          type: integer
          title: Total Transactions Analyzed
        current_monthly_gas_usd:
          type: number
          title: Current Monthly Gas Usd
        optimized_monthly_gas_usd:
          type: number
          title: Optimized Monthly Gas Usd
        estimated_monthly_savings_usd:
          type: number
          title: Estimated Monthly Savings Usd
        total_wasted_gas_eth:
          type: number
          title: Total Wasted Gas Eth
        total_wasted_gas_usd:
          type: number
          title: Total Wasted Gas Usd
        tx_types:
          items:
            $ref: '#/components/schemas/TransactionTypeOptimization'
          type: array
          title: Tx Types
        recommendations:
          items:
            type: string
          type: array
          title: Recommendations
        eth_price_usd:
          type: number
          title: Eth Price Usd
        analyzed_at:
          type: string
          title: Analyzed At
      type: object
      required:
      - address
      - total_transactions_analyzed
      - current_monthly_gas_usd
      - optimized_monthly_gas_usd
      - estimated_monthly_savings_usd
      - total_wasted_gas_eth
      - total_wasted_gas_usd
      - tx_types
      - recommendations
      - eth_price_usd
      - analyzed_at
      title: GasOptimizationReport
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    HealthReport:
      properties:
        address:
          type: string
          title: Address
          description: Wallet address analysed
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
        is_contract:
          type: boolean
          title: Is Contract
          description: Whether the address is a smart contract
          examples:
          - false
        health_score:
          type: number
          title: Health Score
          description: Composite health score 0-100
          examples:
          - 74.5
        optimization_priority:
          type: string
          title: Optimization Priority
          description: 'Priority level: low, medium, high, critical'
          examples:
          - medium
        total_transactions:
          type: integer
          title: Total Transactions
          description: Total transactions in analysis window
          examples:
          - 1542
        successful:
          type: integer
          title: Successful
          description: Number of successful transactions
          examples:
          - 1480
        failed:
          type: integer
          title: Failed
          description: Number of failed transactions
          examples:
          - 62
        success_rate_pct:
          type: number
          title: Success Rate Pct
          description: Transaction success rate as percentage
          examples:
          - 95.98
        total_gas_spent_eth:
          type: number
          title: Total Gas Spent Eth
          description: Total gas spent in ETH
          examples:
          - 0.284
        wasted_gas_eth:
          type: number
          title: Wasted Gas Eth
          description: Gas wasted on failed transactions in ETH
          examples:
          - 0.019
        estimated_monthly_waste_usd:
          type: number
          title: Estimated Monthly Waste Usd
          description: Projected monthly USD waste at current rate
          examples:
          - 14.3
        avg_gas_efficiency_pct:
          type: number
          title: Avg Gas Efficiency Pct
          description: Average gas usage vs gas limit percentage
          examples:
          - 67.3
        out_of_gas_count:
          type: integer
          title: Out Of Gas Count
          description: Transactions that failed due to out-of-gas
          examples:
          - 3
        reverted_count:
          type: integer
          title: Reverted Count
          description: Transactions that reverted
          examples:
          - 59
        nonce_gap_count:
          type: integer
          title: Nonce Gap Count
          description: Detected nonce gaps
          examples:
          - 0
        retry_count:
          type: integer
          title: Retry Count
          description: Duplicate-nonce retry transactions detected
          examples:
          - 2
        top_failure_type:
          type: string
          title: Top Failure Type
          description: Most common failure reason
          examples:
          - execution reverted
        first_seen:
          type: string
          title: First Seen
          description: ISO 8601 timestamp of earliest transaction
          examples:
          - '2024-01-15T08:30:00Z'
        last_seen:
          type: string
          title: Last Seen
          description: ISO 8601 timestamp of most recent transaction
          examples:
          - '2025-04-05T14:22:00Z'
        recommendations:
          items:
            $ref: '#/components/schemas/Recommendation'
          type: array
          title: Recommendations
          description: Prioritised list of actionable recommendations
        eth_price_usd:
          type: number
          title: Eth Price Usd
          description: ETH/USD price used for calculations
          examples:
          - 3245.5
        analyzed_at:
          type: string
          title: Analyzed At
          description: ISO 8601 timestamp of this analysis
          examples:
          - '2025-04-06T10:00:00Z'
      type: object
      required:
      - address
      - is_contract
      - health_score
      - optimization_priority
      - total_transactions
      - successful
      - failed
      - success_rate_pct
      - total_gas_spent_eth
      - wasted_gas_eth
      - estimated_monthly_waste_usd
      - avg_gas_efficiency_pct
      - out_of_gas_count
      - reverted_count
      - nonce_gap_count
      - retry_count
      - top_failure_type
      - first_seen
      - last_seen
      - recommendations
      - eth_price_usd
      - analyzed_at
      title: HealthReport
    HealthResponse:
      properties:
        status:
          type: string
          title: Status
          description: Response status
          examples:
          - ok
        report:
          $ref: '#/components/schemas/HealthReport'
          description: Full health analysis report
        nansen_labels:
          items:
            $ref: '#/components/schemas/NansenLabel'
          type: array
          title: Nansen Labels
          description: Nansen wallet intelligence labels, if available
          default: []
        nansen_available:
          type: boolean
          title: Nansen Available
          description: Whether Nansen enrichment was successful
          default: false
        token_balances:
          items:
            $ref: '#/components/schemas/TokenBalance'
          type: array
          title: Token Balances
          description: Token balances across chains
          default: []
        total_portfolio_usd:
          type: number
          title: Total Portfolio Usd
          description: Total portfolio value in USD
          default: 0.0
          examples:
          - 4820.5
      type: object
      required:
      - status
      - report
      title: HealthResponse
    NansenLabel:
      properties:
        label:
          type: string
          title: Label
          description: Nansen wallet label
          examples:
          - Smart Money
        category:
          anyOf:
          - type: string
          - type: 'null'
          title: Category
          description: Label category
          examples:
          - behavioral
        definition:
          anyOf:
          - type: string
          - type: 'null'
          title: Definition
          description: Human-readable label definition
          examples:
          - Wallet that consistently trades profitably
      type: object
      required:
      - label
      title: NansenLabel
    OperationalHealth:
      properties:
        tx_failure_rate_1hr:
          type: number
          title: Tx Failure Rate 1Hr
          default: 0.0
        tx_failure_rate_24hr:
          type: number
          title: Tx Failure Rate 24Hr
          default: 0.0
        total_txs_1hr:
          type: integer
          title: Total Txs 1Hr
          default: 0
        total_txs_24hr:
          type: integer
          title: Total Txs 24Hr
          default: 0
        nonce_gaps_detected:
          type: boolean
          title: Nonce Gaps Detected
          default: false
        volume_anomaly:
          type: boolean
          title: Volume Anomaly
          default: false
        health_status:
          type: string
          title: Health Status
          default: unknown
        health_detail:
          type: string
          title: Health Detail
          default: ''
      type: object
      title: OperationalHealth
    OptimizeResponse:
      properties:
        status:
          type: string
          title: Status
        report:
          $ref: '#/components/schemas/GasOptimizationReport'
      type: object
      required:
      - status
      - report
      title: OptimizeResponse
    OptimizedTransaction:
      properties:
        to:
          type: string
          title: To
        data:
          type: string
          title: Data
        value:
          type: string
          title: Value
        gas_limit:
          type: string
          title: Gas Limit
        max_fee_per_gas:
          type: string
          title: Max Fee Per Gas
        max_priority_fee_per_gas:
          type: string
          title: Max Priority Fee Per Gas
      type: object
      required:
      - to
      - data
      - value
      - gas_limit
      - max_fee_per_gas
      - max_priority_fee_per_gas
      title: OptimizedTransaction
    PnlSummary:
      properties:
        realized_pnl_usd:
          type: number
          title: Realized Pnl Usd
          default: 0.0
        realized_pnl_percent:
          type: number
          title: Realized Pnl Percent
          default: 0.0
        win_rate:
          type: number
          title: Win Rate
          default: 0.0
        traded_token_count:
          type: integer
          title: Traded Token Count
          default: 0
        traded_times:
          type: integer
          title: Traded Times
          default: 0
        top_tokens:
          items:
            $ref: '#/components/schemas/PnlTokenSummary'
          type: array
          title: Top Tokens
          default: []
      type: object
      title: PnlSummary
    PnlTokenSummary:
      properties:
        token_symbol:
          type: string
          title: Token Symbol
        chain:
          type: string
          title: Chain
        realized_pnl:
          type: number
          title: Realized Pnl
        realized_roi:
          type: number
          title: Realized Roi
      type: object
      required:
      - token_symbol
      - chain
      - realized_pnl
      - realized_roi
      title: PnlTokenSummary
    PremiumRiskResponse:
      properties:
        risk_score:
          type: integer
          title: Risk Score
        risk_level:
          type: string
          title: Risk Level
        verdict:
          type: string
          title: Verdict
        nansen_labels:
          items:
            $ref: '#/components/schemas/NansenLabel'
          type: array
          title: Nansen Labels
        nansen_available:
          type: boolean
          title: Nansen Available
        pnl_summary:
          anyOf:
          - $ref: '#/components/schemas/PnlSummary'
          - type: 'null'
        pnl_available:
          type: boolean
          title: Pnl Available
          default: false
        operational_health:
          anyOf:
          - $ref: '#/components/schemas/OperationalHealth'
          - type: 'null'
      type: object
      required:
      - risk_score
      - risk_level
      - verdict
      - nansen_labels
      - nansen_available
      title: PremiumRiskResponse
    ProtectionActionItem:
      properties:
        priority:
          type: integer
          title: Priority
        action:
          type: string
          title: Action
        description:
          type: string
          title: Description
        potential_value_usd:
          type: number
          title: Potential Value Usd
          default: 0.0
        potential_savings_monthly_usd:
          type: number
          title: Potential Savings Monthly Usd
          default: 0.0
      type: object
      required:
      - priority
      - action
      - description
      title: ProtectionActionItem
    ProtectionPreviewResponse:
      properties:
        status:
          type: string
          title: Status
        address:
          type: string
          title: Address
        risk_level:
          type: string
          title: Risk Level
        health_score:
          type: number
          title: Health Score
        services_recommended:
          items:
            type: string
          type: array
          title: Services Recommended
        estimated_issues:
          type: integer
          title: Estimated Issues
        message:
          type: string
          title: Message
      type: object
      required:
      - status
      - address
      - risk_level
      - health_score
      - services_recommended
      - estimated_issues
      - message
      title: ProtectionPreviewResponse
    ProtectionReport:
      properties:
        address:
          type: string
          title: Address
        risk_level:
          type: string
          title: Risk Level
        health_score:
          type: number
          title: Health Score
        services_run:
          items:
            type: string
          type: array
          title: Services Run
        summary:
          $ref: '#/components/schemas/ProtectionSummaryModel'
        health_report:
          $ref: '#/components/schemas/HealthReport'
        gas_optimization:
          anyOf:
          - $ref: '#/components/schemas/GasOptimizationReport'
          - type: 'null'
        retry_transactions:
          anyOf:
          - items:
              $ref: '#/components/schemas/RetryTransactionItem'
            type: array
          - type: 'null'
          title: Retry Transactions
        recommended_actions:
          items:
            $ref: '#/components/schemas/ProtectionActionItem'
          type: array
          title: Recommended Actions
        analyzed_at:
          type: string
          title: Analyzed At
      type: object
      required:
      - address
      - risk_level
      - health_score
      - services_run
      - summary
      - health_report
      - recommended_actions
      - analyzed_at
      title: ProtectionReport
    ProtectionResponse:
      properties:
        status:
          type: string
          title: Status
        report:
          $ref: '#/components/schemas/ProtectionReport'
      type: object
      required:
      - status
      - report
      title: ProtectionResponse
    ProtectionSummaryModel:
      properties:
        total_issues_found:
          type: integer
          title: Total Issues Found
        total_potential_savings_usd:
          type: number
          title: Total Potential Savings Usd
        retry_transactions_ready:
          type: integer
          title: Retry Transactions Ready
        estimated_retry_cost_usd:
          type: number
          title: Estimated Retry Cost Usd
      type: object
      required:
      - total_issues_found
      - total_potential_savings_usd
      - retry_transactions_ready
      - estimated_retry_cost_usd
      title: ProtectionSummaryModel
    Recommendation:
      properties:
        category:
          type: string
          title: Category
          description: Issue category (gas, nonce, failure, balance)
          examples:
          - gas
        severity:
          type: string
          title: Severity
          description: 'Severity level: critical, high, medium, or info'
          examples:
          - high
        message:
          type: string
          title: Message
          description: Actionable recommendation text
          examples:
          - Gas waste detected — 12% of gas spent on reverted transactions
      type: object
      required:
      - category
      - severity
      - message
      title: Recommendation
    RelatedWallet:
      properties:
        address:
          type: string
          title: Address
        label:
          anyOf:
          - type: string
          - type: 'null'
          title: Label
        relation:
          type: string
          title: Relation
        chain:
          type: string
          title: Chain
        transaction_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: Transaction Hash
        block_timestamp:
          anyOf:
          - type: string
          - type: 'null'
          title: Block Timestamp
      type: object
      required:
      - address
      - relation
      - chain
      title: RelatedWallet
    RelatedWalletsResponse:
      properties:
        status:
          type: string
          title: Status
        address:
          type: string
          title: Address
        chain:
          type: string
          title: Chain
        related_wallets:
          items:
            $ref: '#/components/schemas/RelatedWallet'
          type: array
          title: Related Wallets
          default: []
        total_related:
          type: integer
          title: Total Related
          default: 0
        nansen_available:
          type: boolean
          title: Nansen Available
          default: false
      type: object
      required:
      - status
      - address
      - chain
      title: RelatedWalletsResponse
    ReportCardDimension:
      properties:
        dimension:
          type: string
          title: Dimension
          description: Dimension name (D1 Wallet Hygiene, D2 Behavioural, D3 Infrastructure)
          examples:
          - D1 Wallet Hygiene
        score:
          anyOf:
          - type: integer
          - type: 'null'
          title: Score
          description: Dimension score 0-100
          examples:
          - 84
        weight:
          type: number
          title: Weight
          description: Weight of this dimension in the composite score
          examples:
          - 0.5
      type: object
      required:
      - dimension
      - weight
      title: ReportCardDimension
    ReportCardReport:
      properties:
        address:
          type: string
          title: Address
          description: Wallet address scored
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
        agent_health_score:
          type: integer
          title: Agent Health Score
          description: Composite AHS score 0-100
          examples:
          - 67
        grade:
          type: string
          title: Grade
          description: Letter grade A-F
          examples:
          - C
        confidence:
          type: string
          title: Confidence
          description: 'Score confidence: high, medium, or low'
          examples:
          - high
        mode:
          type: string
          title: Mode
          description: 'Scoring mode: 2D or 3D'
          examples:
          - 2D
        dimensions:
          items:
            $ref: '#/components/schemas/ReportCardDimension'
          type: array
          title: Dimensions
          description: Per-dimension score breakdown
        patterns_detected:
          items:
            $ref: '#/components/schemas/AHSCrossDimensionalPattern'
          type: array
          title: Patterns Detected
          description: Cross-dimensional anomaly patterns detected
        recommendations:
          items:
            type: string
          type: array
          title: Recommendations
          description: Prioritised improvement actions
          examples:
          - - Reduce revert rate below 5%
        ecosystem_comparison:
          $ref: '#/components/schemas/EcosystemComparison'
          description: How this wallet compares to the ecosystem
        image_url:
          type: string
          title: Image Url
          description: URL to the generated report card PNG image
          examples:
          - https://agenthealthmonitor.xyz/static/report-cards/0xde0b...7bae.png
        share_url:
          type: string
          title: Share Url
          description: Shareable URL for this report card
          examples:
          - https://agenthealthmonitor.xyz/report-card/0xde0b...7bae
      type: object
      required:
      - address
      - agent_health_score
      - grade
      - confidence
      - mode
      - dimensions
      - patterns_detected
      - recommendations
      - ecosystem_comparison
      - image_url
      - share_url
      title: ReportCardReport
    ReportCardResponse:
      properties:
        status:
          type: string
          title: Status
          description: Response status
          examples:
          - ok
        report:
          $ref: '#/components/schemas/ReportCardReport'
          description: Full report card with ecosystem benchmarks
      type: object
      required:
      - status
      - report
      title: ReportCardResponse
    RetryPreviewResponse:
      properties:
        status:
          type: string
          title: Status
        address:
          type: string
          title: Address
        failed_transactions_analyzed:
          type: integer
          title: Failed Transactions Analyzed
        retryable_count:
          type: integer
          title: Retryable Count
        total_estimated_retry_cost_usd:
          type: number
          title: Total Estimated Retry Cost Usd
        potential_value_recovered_usd:
          type: number
          title: Potential Value Recovered Usd
        message:
          type: string
          title: Message
      type: object
      required:
      - status
      - address
      - failed_transactions_analyzed
      - retryable_count
      - total_estimated_retry_cost_usd
      - potential_value_recovered_usd
      - message
      title: RetryPreviewResponse
    RetryReport:
      properties:
        address:
          type: string
          title: Address
        failed_transactions_analyzed:
          type: integer
          title: Failed Transactions Analyzed
        retryable_count:
          type: integer
          title: Retryable Count
        retry_transactions:
          items:
            $ref: '#/components/schemas/RetryTransactionItem'
          type: array
          title: Retry Transactions
        total_estimated_retry_cost_usd:
          type: number
          title: Total Estimated Retry Cost Usd
        potential_value_recovered_usd:
          type: number
          title: Potential Value Recovered Usd
        analyzed_at:
          type: string
          title: Analyzed At
      type: object
      required:
      - address
      - failed_transactions_analyzed
      - retryable_count
      - retry_transactions
      - total_estimated_retry_cost_usd
      - potential_value_recovered_usd
      - analyzed_at
      title: RetryReport
    RetryResponse:
      properties:
        status:
          type: string
          title: Status
        report:
          $ref: '#/components/schemas/RetryReport'
      type: object
      required:
      - status
      - report
      title: RetryResponse
    RetryTransactionItem:
      properties:
        original_tx_hash:
          type: string
          title: Original Tx Hash
        failure_reason:
          type: string
          title: Failure Reason
        optimized_transaction:
          $ref: '#/components/schemas/OptimizedTransaction'
        estimated_gas_cost_usd:
          type: number
          title: Estimated Gas Cost Usd
        confidence:
          type: string
          title: Confidence
      type: object
      required:
      - original_tx_hash
      - failure_reason
      - optimized_transaction
      - estimated_gas_cost_usd
      - confidence
      title: RetryTransactionItem
    RiskResponse:
      properties:
        risk_score:
          type: integer
          title: Risk Score
          description: Risk score from 0 (safe) to 100 (dangerous)
          examples:
          - 32
        risk_level:
          type: string
          title: Risk Level
          description: 'Risk classification: LOW, MEDIUM, HIGH, or CRITICAL'
          examples:
          - LOW
        verdict:
          type: string
          title: Verdict
          description: One-line human-readable risk assessment
          examples:
          - Low-risk wallet with normal transaction patterns
      type: object
      required:
      - risk_score
      - risk_level
      - verdict
      title: RiskResponse
    RoutingPolicyRequest:
      properties:
        instant_grades:
          items:
            type: string
          type: array
          title: Instant Grades
          description: Grades that map to instant_settle
          examples:
          - - A
            - B
        escrow_grades:
          items:
            type: string
          type: array
          title: Escrow Grades
          description: Grades that map to escrow
          examples:
          - - C
        reject_grades:
          items:
            type: string
          type: array
          title: Reject Grades
          description: Grades that map to reject
          examples:
          - - D
            - E
            - F
        escrow_disabled:
          type: boolean
          title: Escrow Disabled
          description: If true, escrow grades fall through to reject (binary mode)
          default: false
        allowlist:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Allowlist
          description: Wallet addresses to bypass routing (always instant_settle). Max 1000.
        confidence_overrides:
          anyOf:
          - additionalProperties:
              additionalProperties:
                type: string
              type: object
            type: object
          - type: 'null'
          title: Confidence Overrides
          description: Per-grade confidence-level overrides. Outer keys are grades (A-F), inner keys are confidence levels
            (HIGH, MEDIUM, LOW, INSUFFICIENT), values are routing actions (instant_settle, escrow, reject).
          examples:
          - C:
              HIGH: instant_settle
            D:
              HIGH: escrow
      type: object
      required:
      - instant_grades
      - escrow_grades
      - reject_grades
      title: RoutingPolicyRequest
    RoutingPolicyResponse:
      properties:
        instant_grades:
          items:
            type: string
          type: array
          title: Instant Grades
          description: Grades that map to instant_settle
        escrow_grades:
          items:
            type: string
          type: array
          title: Escrow Grades
          description: Grades that map to escrow
        reject_grades:
          items:
            type: string
          type: array
          title: Reject Grades
          description: Grades that map to reject
        escrow_disabled:
          type: boolean
          title: Escrow Disabled
          description: Binary mode — no escrow tier
        allowlist_count:
          type: integer
          title: Allowlist Count
          description: Number of addresses in the allowlist
        confidence_overrides:
          anyOf:
          - additionalProperties:
              additionalProperties:
                type: string
              type: object
            type: object
          - type: 'null'
          title: Confidence Overrides
          description: Active confidence-level overrides (null if none configured)
        updated_at:
          type: string
          title: Updated At
          description: ISO 8601 timestamp of last policy update
      type: object
      required:
      - instant_grades
      - escrow_grades
      - reject_grades
      - escrow_disabled
      - allowlist_count
      - updated_at
      title: RoutingPolicyResponse
    ShieldSubscribeRequest:
      properties:
        tier:
          type: string
          title: Tier
          description: 'Shield tier: starter, pro, or enterprise'
        success_url:
          type: string
          title: Success Url
          description: URL to redirect after successful checkout
          default: https://agenthealthmonitor.xyz/shield?subscribed=true
        cancel_url:
          type: string
          title: Cancel Url
          description: URL to redirect if checkout is cancelled
          default: https://agenthealthmonitor.xyz/shield
      type: object
      required:
      - tier
      title: ShieldSubscribeRequest
    TestWebhookRequest:
      properties:
        email:
          type: string
          title: Email
        tier:
          type: string
          title: Tier
          default: starter
        key_type:
          type: string
          title: Key Type
          default: payg
        calls:
          type: integer
          title: Calls
          default: 100
      type: object
      required:
      - email
      title: TestWebhookRequest
    TokenBalance:
      properties:
        chain:
          type: string
          title: Chain
          description: Chain identifier
          examples:
          - base
        symbol:
          type: string
          title: Symbol
          description: Token ticker symbol
          examples:
          - USDC
        name:
          type: string
          title: Name
          description: Full token name
          examples:
          - USD Coin
        amount:
          type: number
          title: Amount
          description: Token balance amount
          examples:
          - 1250.75
        usd_value:
          type: number
          title: Usd Value
          description: USD value of the balance
          examples:
          - 1250.75
      type: object
      required:
      - chain
      - symbol
      - name
      - amount
      - usd_value
      title: TokenBalance
    TransactionTypeOptimization:
      properties:
        contract:
          type: string
          title: Contract
        method_id:
          type: string
          title: Method Id
        method_label:
          type: string
          title: Method Label
        tx_count:
          type: integer
          title: Tx Count
        failed_count:
          type: integer
          title: Failed Count
        failure_rate_pct:
          type: number
          title: Failure Rate Pct
        current_avg_gas_limit:
          type: integer
          title: Current Avg Gas Limit
        current_p50_gas_used:
          type: integer
          title: Current P50 Gas Used
        current_p95_gas_used:
          type: integer
          title: Current P95 Gas Used
        optimal_gas_limit:
          type: integer
          title: Optimal Gas Limit
        gas_limit_reduction_pct:
          type: number
          title: Gas Limit Reduction Pct
        wasted_gas_eth:
          type: number
          title: Wasted Gas Eth
        wasted_gas_usd:
          type: number
          title: Wasted Gas Usd
      type: object
      required:
      - contract
      - method_id
      - method_label
      - tx_count
      - failed_count
      - failure_rate_pct
      - current_avg_gas_limit
      - current_p50_gas_used
      - current_p95_gas_used
      - optimal_gas_limit
      - gas_limit_reduction_pct
      - wasted_gas_eth
      - wasted_gas_usd
      title: TransactionTypeOptimization
    TrustRouteResponse:
      properties:
        address:
          type: string
          title: Address
          description: Wallet address queried
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
        agent_health_score:
          type: integer
          title: Agent Health Score
          description: Most recent AHS score 0-100
          examples:
          - 67
        grade:
          type: string
          title: Grade
          description: Letter grade A-F
          examples:
          - C
        routing_recommendation:
          type: string
          title: Routing Recommendation
          description: 'Trust-based routing signal: instant_settle, escrow, or reject'
          examples:
          - escrow
        confidence:
          type: string
          title: Confidence
          description: Score confidence level
          examples:
          - high
        scored_at:
          type: string
          title: Scored At
          description: ISO 8601 timestamp of the cached score
          examples:
          - '2025-04-06T10:00:00Z'
        stale:
          type: boolean
          title: Stale
          description: True if the cached score is older than 24 hours
          examples:
          - false
        policy_applied:
          type: boolean
          title: Policy Applied
          description: True if a custom routing policy was used for this recommendation
          default: false
        allowlisted:
          type: boolean
          title: Allowlisted
          description: True if this address is in the caller's allowlist (instant_settle bypass)
          default: false
      type: object
      required:
      - address
      - agent_health_score
      - grade
      - routing_recommendation
      - confidence
      - scored_at
      - stale
      title: TrustRouteResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    WashIssue:
      properties:
        category:
          type: string
          title: Category
          description: 'Issue category: dust, spam, gas, failed_tx, or nonce'
          examples:
          - dust
        severity:
          type: string
          title: Severity
          description: 'Issue severity: low, medium, or high'
          examples:
          - medium
        description:
          type: string
          title: Description
          description: Human-readable description of the issue
          examples:
          - 14 dust tokens worth < $0.01 each cluttering wallet
        action:
          type: string
          title: Action
          description: Recommended cleanup action
          examples:
          - Consolidate or discard dust tokens to reduce clutter
        estimated_savings:
          anyOf:
          - type: string
          - type: 'null'
          title: Estimated Savings
          description: Potential savings from fixing this issue
          examples:
          - $0.42/month in gas
      type: object
      required:
      - category
      - severity
      - description
      - action
      title: WashIssue
    WashReport:
      properties:
        address:
          type: string
          title: Address
          description: Wallet address scanned
          examples:
          - '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
        cleanliness_score:
          type: integer
          title: Cleanliness Score
          description: Cleanliness score 0 (dirty) to 100 (spotless)
          examples:
          - 72
        cleanliness_grade:
          type: string
          title: Cleanliness Grade
          description: Letter grade A-F
          examples:
          - C
        total_issues:
          type: integer
          title: Total Issues
          description: Total hygiene issues found
          examples:
          - 8
        issues_by_severity:
          additionalProperties: true
          type: object
          title: Issues By Severity
          description: Issue count by severity level
          examples:
          - high: 1
            low: 4
            medium: 3
        dust_tokens:
          type: integer
          title: Dust Tokens
          description: Number of dust tokens (< $0.01 value)
          examples:
          - 14
        dust_total_usd:
          type: number
          title: Dust Total Usd
          description: Total USD value of dust tokens
          examples:
          - 0.03
        spam_tokens:
          type: integer
          title: Spam Tokens
          description: Number of suspected spam/airdrop tokens
          examples:
          - 5
        spam_token_list:
          items: {}
          type: array
          title: Spam Token List
          description: Names of detected spam tokens
          examples:
          - - FakeUSDT
            - SCAM-Airdrop
        gas_efficiency_pct:
          type: number
          title: Gas Efficiency Pct
          description: Gas usage efficiency percentage
          examples:
          - 71.4
        gas_efficiency_grade:
          type: string
          title: Gas Efficiency Grade
          description: Gas efficiency letter grade
          examples:
          - C
        wasted_gas_usd:
          type: number
          title: Wasted Gas Usd
          description: USD value of gas wasted on failed txs
          examples:
          - 8.2
        failed_tx_count_24hr:
          type: integer
          title: Failed Tx Count 24Hr
          description: Failed transactions in the last 24 hours
          examples:
          - 3
        failed_tx_patterns:
          items: {}
          type: array
          title: Failed Tx Patterns
          description: Detected failure pattern names
          examples:
          - - repeated_revert
        nonce_gaps:
          type: integer
          title: Nonce Gaps
          description: Number of nonce gaps detected
          examples:
          - 0
        issues:
          items:
            $ref: '#/components/schemas/WashIssue'
          type: array
          title: Issues
          description: Detailed list of hygiene issues found
        recommendations:
          items:
            type: string
          type: array
          title: Recommendations
          description: Prioritised cleanup recommendations
          examples:
          - - Revoke approvals for 5 spam tokens
            - Set tighter gas limits on swap calls
        scan_timestamp:
          type: string
          title: Scan Timestamp
          description: ISO 8601 timestamp of this scan
          examples:
          - '2025-04-06T10:00:00Z'
        next_wash_recommended:
          type: string
          title: Next Wash Recommended
          description: Recommended next scan date
          examples:
          - '2025-04-13T10:00:00Z'
      type: object
      required:
      - address
      - cleanliness_score
      - cleanliness_grade
      - total_issues
      - issues_by_severity
      - dust_tokens
      - dust_total_usd
      - spam_tokens
      - spam_token_list
      - gas_efficiency_pct
      - gas_efficiency_grade
      - wasted_gas_usd
      - failed_tx_count_24hr
      - failed_tx_patterns
      - nonce_gaps
      - issues
      - recommendations
      - scan_timestamp
      - next_wash_recommended
      title: WashReport
    WashResponse:
      properties:
        status:
          type: string
          title: Status
          description: Response status
          examples:
          - ok
        report:
          $ref: '#/components/schemas/WashReport'
          description: Full hygiene scan report
      type: object
      required:
      - status
      - report
      title: WashResponse
tags:
- name: Scoring & Risk
  description: Risk scoring, counterparty analysis, and wallet network mapping. Fast pre-flight checks from $0.001 to deep
    Nansen-enriched analysis at $0.10.
- name: Health & Hygiene
  description: Wallet health diagnosis, hygiene scans, composite Agent Health Score (AHS), and visual report cards. Core analysis
    endpoints from $0.50 to $2.00.
- name: Optimization
  description: Gas optimization reports and failed-transaction retry bot. Returns per-transaction-type savings and ready-to-sign
    EIP-1559 retry payloads.
- name: Protection
  description: Autonomous protection agent that triages risk and runs the appropriate combination of health, optimization,
    and retry services automatically.
- name: Alerts
  description: Subscribe wallets to automated health monitoring with webhook alerts. Health checks run every 6 hours; alerts
    fire when configurable thresholds are breached.
- name: Coupon Access
  description: Partner coupon routes — access any paid endpoint for free with a valid coupon code. Rate-limited to 5 requests
    per IP per minute.
- name: Discovery & Info
  description: Service discovery, pricing info, ecosystem statistics, and x402/ERC-8004 well-known documents for automated
    agent registration.
- name: Billing
  description: Stripe checkout webhooks and API key management for fiat-paid access.
- name: Admin
  description: Internal admin endpoints protected by X-Internal-Key header. Security activity logs, trust registry, and registry
    scan triggers.
- name: Utility
  description: Health checks and AI chat assistant.