openapi: 3.1.0
info:
  title: Wallet CEX Flows MCP (x402)
  version: 0.1.0
  description: |
    Pay-per-call EVM wallet ↔ CEX flow analysis. Three primitives:
    (1) wallet_cex_flows — composite per-chain per-CEX deposit/withdrawal scan
        across up to 5 chains via ERC-20 Transfer log scan + curated CEX
        address registry;
    (2) wallet_cex_attribution — is this address a known CEX hot wallet /
        deposit aggregator / cold storage?
    (3) cex_recent_inflows — top depositor addresses to a given CEX over a
        recent block window, optionally per-token.
    Multichain (ethereum/base/arbitrum/optimism/polygon).
    Settle USDC on Base via x402. No signup, no API key.
servers:
  - url: https://wallet-cex-flows-mcp.mtree.workers.dev
x-pricing:
  - path: /v1/wallet/cex_flows
    method: POST
    price: $0.30
    amount: "0.30"
    asset: USDC
    network: base
  - path: /v1/wallet/cex_attribution
    method: POST
    price: $0.05
    amount: "0.05"
    asset: USDC
    network: base
  - path: /v1/cex/recent_inflows
    method: POST
    price: $0.10
    amount: "0.10"
    asset: USDC
    network: base
paths:
  /healthz:
    get:
      summary: Service health
      responses:
        "200":
          description: OK
  /v1/wallet/cex_flows:
    post:
      summary: Composite wallet ↔ CEX flow scan
      description: |
        $0.30 USDC on Base via x402. For each chain, scan ERC-20 Transfer
        events involving the address (both directions) and match counterparties
        against a curated CEX address registry. Returns per-chain per-CEX
        deposit/withdrawal counts, USDC/USDT/ETH atomic totals each direction,
        and net flow direction (depositor / withdrawer / balanced). Capped to
        top 5 CEXes per chain by interaction count for latency.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [address]
              properties:
                address:
                  type: string
                  description: EVM address (0x… 20 bytes)
                chains:
                  type: array
                  items:
                    type: string
                    enum: [ethereum, base, arbitrum, optimism, polygon]
                  description: Optional. Default all 5.
                lookback_blocks:
                  type: number
                  description: Blocks to scan per chain. Default ~50000 (Base/Arb/Op), 5000 (Eth), 20000 (Polygon). Max 200000.
      responses:
        "402":
          description: Payment required (x402 envelope returned)
        "200":
          description: Wallet CEX flow payload
  /v1/wallet/cex_attribution:
    post:
      summary: Single-address CEX attribution
      description: |
        $0.05 USDC on Base via x402. Look up an EVM address in the curated
        CEX address registry. Returns is_cex + cex_label + exchange_family
        (Binance / Coinbase / Kraken / OKX / Crypto.com / Bitfinex / Bittrex
        / Gate.io) + cex_role (hot_wallet / deposit_aggregator / cold_storage).
        Confidence is 1.0 (registry hit) or 0.0 (no match — does NOT prove
        non-CEX).
      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: CEX attribution payload
  /v1/cex/recent_inflows:
    post:
      summary: Top depositors to a CEX
      description: |
        $0.10 USDC on Base via x402. For all registry addresses matching
        exchange + chain, scan inbound ERC-20 Transfer events. Optionally
        filter to a single token (USDC, USDT, …). Aggregate top 10 distinct
        sender addresses by total atomic volume. Excludes CEX↔CEX rebalancing.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [exchange]
              properties:
                exchange:
                  type: string
                  description: e.g. Binance / Coinbase / Kraken / OKX / Crypto.com / Bitfinex / Bittrex / Gate.io
                chain:
                  type: string
                  enum: [ethereum, base, arbitrum, optimism, polygon]
                  default: ethereum
                lookback_blocks:
                  type: number
                  description: Blocks to scan. Default 5000. Max 200000.
                token:
                  type: string
                  description: Optional ERC-20 token address to filter (USDC, USDT, …)
      responses:
        "402":
          description: Payment required (x402 envelope returned)
        "200":
          description: Recent CEX inflows payload
