openapi: 3.1.0
info:
  title: Wallet Funding Trace MCP (x402)
  version: 0.1.0
  description: |
    Pay-per-call EVM wallet funding/origin tracing service. Three primitives:
    (1) funding_trace walks back from a target address through predecessor
    addresses (default 3 hops) classifying each against CEX / mixer / OFAC /
    bridge registries — returns funding_classification (clean / tc_tainted /
    sanctioned / mixer_tainted / multi_hop_cex / fresh_mint / unknown) and
    risk_band (clean / low / medium / high / critical);
    (2) funding_summary is a lightweight 1-hop classifier (initial funder +
    wallet age);
    (3) funding_path returns the predecessor at any specific hop depth.
    Multichain (ethereum/base/arbitrum/optimism/polygon).
    Settle USDC on Base via x402. No signup, no API key.
servers:
  - url: https://wallet-funding-trace-mcp.mtree.workers.dev
x-pricing:
  - path: /v1/wallet/funding_trace
    method: POST
    price: $0.30
    amount: "0.30"
    asset: USDC
    network: base
  - path: /v1/wallet/funding_summary
    method: POST
    price: $0.10
    amount: "0.10"
    asset: USDC
    network: base
  - path: /v1/wallet/funding_path
    method: POST
    price: $0.05
    amount: "0.05"
    asset: USDC
    network: base
paths:
  /healthz:
    get:
      summary: Service health
      responses:
        "200":
          description: OK
  /v1/wallet/funding_trace:
    post:
      summary: Multi-hop funding/origin trace
      description: |
        $0.30 USDC on Base via x402. Walks back from the target address
        through predecessor addresses up to max_hops, classifying each hop
        against CEX / mixer / sanctioned / bridge registries. Returns full
        trace_path + terminal_source + funding_classification + risk_band.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [address]
              properties:
                address:
                  type: string
                  description: EVM address (0x… 20 bytes)
                chain:
                  type: string
                  enum: [ethereum, base, arbitrum, optimism, polygon]
                  default: ethereum
                max_hops:
                  type: number
                  description: Max predecessor hops to walk (default 3, max 5).
                lookback_blocks:
                  type: number
                  description: Blocks back from head to scan for funding logs (default 200000, max 1000000).
      responses:
        "402":
          description: Payment required (x402 envelope returned)
        "200":
          description: Funding trace payload
  /v1/wallet/funding_summary:
    post:
      summary: Lightweight 1-hop funding summary
      description: |
        $0.10 USDC on Base via x402. Returns the first inbound tracked-token
        Transfer + immediate predecessor classification (cex / bridge / mixer /
        contract_mint / eoa / unknown) + age_blocks + age_days_estimate.
        ~10x faster than funding_trace.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [address]
              properties:
                address:
                  type: string
                  description: EVM address (0x… 20 bytes)
                chain:
                  type: string
                  enum: [ethereum, base, arbitrum, optimism, polygon]
                  default: ethereum
      responses:
        "402":
          description: Payment required (x402 envelope returned)
        "200":
          description: Funding summary payload
  /v1/wallet/funding_path:
    post:
      summary: Single-hop predecessor lookup at requested depth
      description: |
        $0.05 USDC on Base via x402. Returns the predecessor address at hop=N
        (default 1 = immediate funder) + classification + via_tx (tx_hash,
        block, value, token). Use to drill into a specific hop without paying
        for the full multi-hop trace.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [address]
              properties:
                address:
                  type: string
                  description: EVM address (0x… 20 bytes)
                chain:
                  type: string
                  enum: [ethereum, base, arbitrum, optimism, polygon]
                  default: ethereum
                hop:
                  type: number
                  description: Hop depth — 1 = immediate funder, 2 = funder's funder, etc. Max 5.
      responses:
        "402":
          description: Payment required (x402 envelope returned)
        "200":
          description: Predecessor payload

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