openapi: 3.1.0
info:
  title: MEV History MCP (x402)
  version: 0.1.0
  description: |
    Pay-per-call EVM MEV-history service. Three primitives:
    (1) sandwich_check classifies a single tx as sandwiched/not via block-position
    heuristic + DEX-router routing + gas-priority pattern;
    (2) mev_exposure scores a wallet's recent MEV exposure 0–100 by sampling
    recent blocks;
    (3) recent_mev_density measures sandwich density at a DEX pool by scanning
    its recent logs. Multichain (ethereum/base/arbitrum/optimism/polygon).
    Settle USDC on Base via x402. No signup, no API key.
servers:
  - url: https://mev-history-mcp.mtree.workers.dev
x-pricing:
  - path: /v1/wallet/mev_exposure
    method: POST
    price: $0.30
    amount: "0.30"
    asset: USDC
    network: base
  - path: /v1/tx/sandwich_check
    method: POST
    price: $0.05
    amount: "0.05"
    asset: USDC
    network: base
  - path: /v1/pool/recent_mev_density
    method: POST
    price: $0.10
    amount: "0.10"
    asset: USDC
    network: base
paths:
  /healthz:
    get:
      summary: Service health
      responses:
        "200":
          description: OK
  /v1/wallet/mev_exposure:
    post:
      summary: Per-wallet MEV exposure score (0–100)
      description: |
        $0.30 USDC on Base via x402. Samples recent blocks, identifies the
        wallet's swap-related tx via known DEX router targets, and applies a
        block-position sandwich heuristic to each. Returns 0–100 exposure
        score, sandwich count, swap count, and per-sandwich attacker / frontrun /
        backrun details.
      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: base
                lookback_blocks:
                  type: number
                  description: How many recent blocks to sample. Default 1500 (Base/Arb/Op), 200 (Eth), 1000 (Polygon). Max 5000.
      responses:
        "402":
          description: Payment required (x402 envelope returned)
        "200":
          description: Wallet MEV exposure payload
  /v1/tx/sandwich_check:
    post:
      summary: Single-tx sandwich classifier
      description: |
        $0.05 USDC on Base via x402. Takes a tx_hash + chain, fetches the
        tx + its block, and applies the block-position heuristic against the
        immediately-preceding and immediately-following txs. Returns
        is_sandwiched + confidence (none/weak/medium/strong/confirmed) +
        attacker_addr + frontrun/backrun details.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [tx_hash]
              properties:
                tx_hash:
                  type: string
                  description: 32-byte hex tx hash (0x… 64 hex chars)
                chain:
                  type: string
                  enum: [ethereum, base, arbitrum, optimism, polygon]
                  default: base
      responses:
        "402":
          description: Payment required (x402 envelope returned)
        "200":
          description: Sandwich classification payload
  /v1/pool/recent_mev_density:
    post:
      summary: Pool-level recent sandwich density
      description: |
        $0.10 USDC on Base via x402. Takes a pool address + chain, fetches
        every log emitted by the pool in the lookback window, dedupes by
        tx_hash, and runs the sandwich heuristic per tx. Returns
        sandwich_density (0.0–1.0), density_band (none/low/medium/high),
        and up to 5 sample sandwiches.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [pool_address]
              properties:
                pool_address:
                  type: string
                  description: DEX pool contract address
                chain:
                  type: string
                  enum: [ethereum, base, arbitrum, optimism, polygon]
                  default: base
                lookback_blocks:
                  type: number
                  description: How many recent blocks to scan logs across. Default 1500 (Base/Arb/Op), 200 (Eth), 1000 (Polygon). Max 5000.
      responses:
        "402":
          description: Payment required (x402 envelope returned)
        "200":
          description: Pool MEV density payload
