# ClearTrace — Neutral On-Chain Benchmarking

## Overview
ClearTrace provides neutral, third-party benchmarking of DEX aggregators and DEXs based on actual on-chain execution: realized slippage versus a VWAP baseline, transaction revert rates, and sandwich-attack (MEV) detection, plus cross-frontend attribution of trade routing.

## Metrics (last sync 2026-09-08)
- Supported Chains: Ethereum, Base, Arbitrum, Optimism
- DEX/Aggregators tracked: 15+ (Uniswap, 1inch, CoW Protocol, KyberSwap, ParaSwap, etc.)
- Trades analyzed (latest window): ~3.7 million
- Attributed volume (latest window): ~$11 billion
- Refresh: batch pipeline (not a real-time feed); see the "last sync" date above

## Methodology — Cross-Frontend Attribution Engine

ClearTrace uses four advanced attribution vectors to identify hidden frontends and institutional routing:

### 1. Calldata Suffix Trapping
Many modular frontends and wallet-native swap extensions (Phantom, MetaMask, private portfolio apps) append a static hex suffix to the end of execution calldata. We parse the last 4-8 bytes of transaction data to isolate repeating hex fingerprints and attribute volume to unidentified mobile apps or private interfaces.

### 2. Proxy-Router Hunting (tx_to vs project_contract_address Mismatch)
Hidden frontends or institutional desks route transactions through proprietary proxy contracts before hitting DEX pools. We identify instances where tx_to != project_contract_address and the intermediate address is not a known aggregator, revealing custom enterprise frontends and institutional smart wallets.

### 3. Multi-Hop Origin Trace (Behavioral Sequence Analysis)
We use window functions over dex.trades to track sequential transaction habits by wallet address. This reveals interface churn patterns — e.g., "68% of users who leave CowSwap execute their next trade on Uniswap within 14 minutes."

### 4. Fee-Recipient Attribution
Hidden frontends monetize by skimming a cut of the swap to a fee-collection address. We scan the ERC-20 transfer events inside the swap's own transaction and rule out the structural recipients (the user, the called contract, the pools, the token contracts, and burn sinks); any recipient left over is treated as a fee collector, and the frontend is attributed by resolving that address's label. This vector returns **medium** confidence, never high, because an affiliate payment is indirect evidence of the interface. The fee amount is reported as an exact raw integer with no decimals or pricing applied, so no basis-point rate is derived and no clustering by fee rate is performed.

## Key Metrics Definitions

**Slippage Score (0-100)**: Derived from median realized slippage versus a 1-minute VWAP baseline, as `100 - slippage_bps` (clipped). Higher = lower slippage. This is a slippage-only metric; MEV exposure and revert rates are reported separately, not folded in.

**VWAP Slippage**: Difference between the expected price (1-minute volume-weighted average price) and the actual execution price, in basis points.

**Sandwich / MEV exposure**: Sandwich attacks (frontrun → victim → backrun) detected in block ordering, reported as attack counts and total value sandwiched. Tracked separately; not currently a per-aggregator scored rate.

**Revert Rate**: Percentage of routing transactions that fail on-chain — a distinct, per-aggregator metric.

**Attribution Volume**: Total USD volume attributed to a specific frontend or aggregator through our 4-vector attribution engine.

## Data Sources
- **Dune Analytics**: On-chain trade data from dex.trades and dex_aggregator.trades tables (batch attribution queries)
- **Alchemy**: Multi-chain RPC infrastructure for real-time contract resolution, token balance lookups (alchemy_getTokenBalances), asset transfer tracing (alchemy_getAssetTransfers), and on-chain data across Ethereum, Base, Arbitrum, Optimism, and Polygon
- **DefiLlama**: Protocol TVL, stablecoin market caps, yield data, protocol financials
- **Polymarket Gamma API**: Prediction market data for DeFi sentiment analysis

## API Endpoints
- GET /api/v1/protocols — Ranked list of protocols by Slippage Score (with avg_slippage_bps)
- GET /api/v1/transactions — Recent transaction sample with execution metrics
- GET /api/v1/attribution — Bulk cross-frontend attribution data (4 vectors per contract)
- GET /api/v1/mev/sandwiches — Detected sandwich-attack events with victim wallet and trade size
- GET /api/v1/revert-rates — Per-aggregator, per-chain transaction revert (failure) rates
- GET /api/v1/flows — Interface-to-interface routing flows (source → target volume)
- GET /api/v1/labels — Auto-discovered contract labels
- GET /api/v1/contract/{address}/attribution — Per-address 4-vector attribution breakdown + label
- GET /api/v1/contract/{address}/profile — On-chain profile for any address (Alchemy)
- GET /api/v1/tx/{hash} — Live per-transaction attribution: which frontend/router originated a trade, vectors matched, fee recipients, pools, sandwich flag
- GET /api/v1/gas — Live multi-chain gas prices
- GET /health — Health check endpoint with database status
- GET /docs — Interactive API documentation (Swagger UI)

## MCP Server (for AI agents)
ClearTrace runs an official Model Context Protocol server, so an agent can call this data as tools instead of raw HTTP. Remote endpoint, Streamable HTTP, nothing to install:
- Endpoint: https://cleartracedata.com/mcp
- Tools: execution_benchmarks, revert_rates, attribution, contract_attribution, explain_transaction, gas_prices, request_api_key
- Auth: none required. An optional free X-API-Key header multiplies rate limits by 10 and changes nothing else; every figure is public and identical either way.
- Setup walkthrough: https://cleartracedata.com/docs/quickstart

## Research & Methodology
- Full methodology whitepaper: https://cleartracedata.com/methodology
- Research reports: https://cleartracedata.com/research

## Contact
For data partnerships, API access, or research inquiries: https://cleartracedata.com

## Last Updated
Data as of last sync 2026-09-08 (batch pipeline).