Developer Quickstart

Integrate neutral execution benchmarking — slippage, revert rates, MEV detection, and routing topologies — into your application.

API Basics

The ClearTrace API provides programmatic access to our cross-frontend attribution engine and on-chain benchmarking data.

Base URL: https://cleartracedata.com/api/v1
Authentication: Currently open. No API keys required.
Rate Limit: 60 requests per minute per IP address.
Data Freshness: Data is synchronized from Dune Analytics on a periodic batch pipeline — not a real-time mempool feed. The dashboard shows the last-sync date.

Open OpenAPI Swagger

1. Fetch Protocol Quality Scores

Get a ranked list of DEX aggregators scored by their execution quality and MEV protection.

cURL

curl -X GET "https://cleartracedata.com/api/v1/protocols?limit=3&offset=0" \
     -H "Accept: application/json"

Python

import requests

response = requests.get(
    "https://cleartracedata.com/api/v1/protocols",
    params={"limit": 3, "offset": 0}
)
print(response.json())

2. Fetch Recent Transactions

Retrieve a sample of recent on-chain transactions with exact gas costs, routing legs, and execution status.

cURL

curl -X GET "https://cleartracedata.com/api/v1/transactions?chain=arbitrum&aggregator=1inch&limit=5" \
     -H "Accept: application/json"

Python

import requests

response = requests.get(
    "https://cleartracedata.com/api/v1/transactions",
    params={
        "chain": "arbitrum",
        "aggregator": "1inch",
        "limit": 5
    }
)
print(response.json())

3. Fetch Bulk Attribution Data

Retrieve aggregated volume data across our 4 attribution vectors. This endpoint provides access to over 172,000 distinct contracts and entities we've labeled.

cURL

curl -X GET "https://cleartracedata.com/api/v1/attribution?chain=ethereum&limit=1" \
     -H "Accept: application/json"

Python

import requests

response = requests.get(
    "https://cleartracedata.com/api/v1/attribution",
    params={
        "chain": "ethereum",
        "limit": 1000
    }
)
print(f"Fetched {response.json()['total']} total attribution records.")

4. Detect Sandwich Attacks (MEV)

Pull real sandwich-attack events identified in block ordering — the victim's transaction hash, wallet, trade size, and DEX/pair — plus trailing-7-day attack counts and total value sandwiched per chain. Filter by chain, project, or a minimum victim trade size.

cURL

curl -X GET "https://cleartracedata.com/api/v1/mev/sandwiches?chain=ethereum&min_victim_volume_usd=1000&limit=5" \
     -H "Accept: application/json"

Python

import requests

response = requests.get(
    "https://cleartracedata.com/api/v1/mev/sandwiches",
    params={
        "chain": "ethereum",
        "min_victim_volume_usd": 1000,
        "limit": 5
    }
)
data = response.json()
print(f"${data['total_sandwiched_usd_7d']:,.0f} sandwiched across all chains in 7d")

5. Compare Aggregator Revert Rates

The revert rate is the share of an aggregator's routing transactions that fail on-chain — a reliability metric distinct from slippage, reported per chain. Each row also carries user_revert_rate_pct (methodology v6): the same rate over only senders classified as genuine users — the honest number for cells whose headline is a documented bot-spam residual. Filter by chain or project.

cURL

curl -X GET "https://cleartracedata.com/api/v1/revert-rates?chain=ethereum&limit=10" \
     -H "Accept: application/json"

Python

import requests

response = requests.get(
    "https://cleartracedata.com/api/v1/revert-rates",
    params={"chain": "ethereum", "limit": 10}
)
for r in response.json()["revert_rates"]:
    print(f"{r['project']}: {r['revert_rate_pct']}% reverted")

6. Map Interface Routing Flows

Each edge is a source → target volume aggregate from the attribution engine — e.g. how much direct-retail volume flows into a given router or unknown proxy. Filter by source or target (substring match).

cURL

curl -X GET "https://cleartracedata.com/api/v1/flows?source=Direct&limit=10" \
     -H "Accept: application/json"

Python

import requests

response = requests.get(
    "https://cleartracedata.com/api/v1/flows",
    params={"source": "Direct", "limit": 10}
)
for edge in response.json()["flows"]:
    print(f"{edge['source']} → {edge['target']}: ${edge['volume_usd']:,.0f}")

7. Look Up Attribution for an Address

Given any contract or wallet, get its per-chain volume split across the four attribution vectors, enriched with any label we've resolved. Most useful for the unlabeled proxies and hidden frontends the engine surfaces as Unknown Proxy/Frontend (0x…). Add ?chain=ethereum to scope to one chain.

cURL

curl -X GET "https://cleartracedata.com/api/v1/contract/0x83d55acdc72027ed339d267eebaf9a41e47490d5/attribution" \
     -H "Accept: application/json"

Python

import requests

addr = "0x83d55acdc72027ed339d267eebaf9a41e47490d5"
response = requests.get(
    f"https://cleartracedata.com/api/v1/contract/{addr}/attribution"
)
data = response.json()
print(f"${data['total_volume_usd']:,.0f} attributed across {data['chains_found']} chain(s)")
for rec in data["records"]:
    print(f"  {rec['chain']}: {rec['label'] or rec['resolved_contract_name']}")

8. Attribute a Single Transaction

Paste any transaction hash to classify it live against the four attribution vectors: which frontend/router originated the trade, the pools touched, fee recipients, and whether it was sandwiched. Results are cached permanently (mined transactions never change). Fee amounts are exact raw token units — no USD is applied. Add ?deep=true to use internal call traces, which catches aggregators that sit as intermediates behind allowance-holder contracts and runs the suffix test per sub-call. Add ?price=true for a best-effort, approximate USD trade size (dominant priced leg, DefiLlama spot price — never a settlement figure).

cURL

curl -X GET "https://cleartracedata.com/api/v1/tx/0xee24d08530006e146b9afc88f015f768447d727685f060c5a801484e7b585982?chain=ethereum" \
     -H "Accept: application/json"

Python

import requests

tx = "0xee24d08530006e146b9afc88f015f768447d727685f060c5a801484e7b585982"
data = requests.get(
    f"https://cleartracedata.com/api/v1/tx/{tx}",
    params={"chain": "ethereum"}
).json()
print(f"origin: {data['aggregator_name'] or data['originator']['name']}")
print(f"vector: {data['primary_vector']} | legs: {data['routing_legs']} | sandwiched: {data['sandwiched']}")