openapi: 3.2.0
info:
  title: Agent Health Monitor Health & Hygiene API
  description: Wallet intelligence API for autonomous agents on Base L2.
  contact:
    name: AHM Support
    url: https://agenthealthmonitor.xyz/
  license:
    name: Proprietary
  version: 1.8.0
tags:
- 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.
paths:
  /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.


        Two tiers apply — see canonical.json -> batch. Pricing:

        - **x402 path:** flat batch price, capped at BATCH_X402_MAX wallets per call.

        - **API key path:** 1 credit per wallet scored. Supports partial results

        if credits are insufficient (scores as many as credits allow).


        Results include the same AHS scoring as the single GET /ahs/{address}

        endpoint — composite 0-100 score with D1/D2 dimension breakdown,

        pattern 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'
components:
  schemas:
    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
    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
    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
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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