# ClearTrace

> Neutral data on how well decentralised exchanges execute trades on Ethereum, Base, Arbitrum and Optimism. Rank exchanges by slippage, find out which app or router a trade came through, track sandwich attacks and failed-transaction rates, see where volume flows, profile any address and check live gas prices. Free and open, no account needed.

App · 11 actions. Web page: https://docs.lodol.com/docs/integrations/cleartrace

## Actions

### Get an address profile

See what a wallet or contract address is and what it holds: whether it is a contract, ClearTrace's guess at what kind (a treasury, a trading bot, a router), its ETH balance and its token balances.

**Inputs**

- Address (`address`, text, required): The wallet or contract address (0x and 40 characters), or a block explorer link to it.
- Chain (`chain`, text): Which chain to look on. One of: `ethereum`, `base`, `arbitrum`, `optimism`. Default: `ethereum`.

**Outputs**

- `address` (text)
- `chain` (text)
- `classification` (text): ClearTrace's guess at what it is, such as eoa_wallet, router or mev_bot.
- `code_size_bytes` (number)
- `contracts_deployed` (number): For a contract, how many it has created.
- `eth_balance` (number)
- `explorer_url` (text)
- `is_contract` (true/false)
- `nonce` (number): For a wallet, how many transactions it has sent.
- `token_balances` (list)
- `token_count` (number)

**Example output**

```json
{
  "address": "0x000000000004444c5dc75cb358380d2e3de08a90",
  "chain": "ethereum",
  "classification": "diverse_token_holdings",
  "code_size_bytes": 24009,
  "contracts_deployed": 0,
  "eth_balance": 56338.13,
  "explorer_url": "https://etherscan.io/address/0x000000000004444c5dc75cb358380d2e3de08a90",
  "is_contract": true,
  "nonce": 1,
  "token_balances": [
    {
      "balance": 1250000.5,
      "contract": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "name": "USD Coin",
      "symbol": "USDC"
    }
  ],
  "token_count": 1
}
```

### Get an address's trading volume

See how much exchange volume ClearTrace has traced through one contract or wallet, per chain, split by how it was routed: direct, through a proxy or through an aggregator. Most useful for unnamed proxies and hidden frontends; a well-known exchange is listed by name rather than address.

**Inputs**

- Address (`address`, text, required): The contract or wallet address, or a block explorer link to it.
- Chain (`chain`, text): One chain, or every chain it is on. One of: `all` (All chains), `ethereum`, `base`, `arbitrum`, `optimism`. Default: `all`.

**Outputs**

- `address` (text)
- `chains_found` (number)
- `name` (text)
- `records` (list)
- `total_volume_usd` (number)

**Example output**

```json
{
  "address": "0x83d55acdc72027ed339d267eebaf9a41e47490d5",
  "chains_found": 1,
  "name": "Wintermute-linked Market Maker (Bot)",
  "records": [
    {
      "aggregator_partner_volume_usd": 0.0,
      "aggregator_volume_usd": 888.84,
      "calldata_suffix_volume_usd": 867652.06,
      "chain": "base",
      "direct_volume_usd": 0.0,
      "entity_type": "contract",
      "fee_transfer_volume_usd": 2445198.16,
      "label": null,
      "label_confidence": "low",
      "name": "Wintermute-linked Market Maker (Bot)",
      "proxy_volume_usd": 886500384.24,
      "total_volume_usd": 886501273.08
    }
  ],
  "total_volume_usd": 886501273.08
}
```

### Get failed transaction rates

See how often each aggregator's transactions fail on chain, per chain, both overall and for regular users. By default only venues that can fairly be compared are shown: on batch-auction and intent venues an order that can't be filled never reaches the chain, so their rate is always near zero.

**Inputs**

- Chain (`chain`, text): One chain, or all four. One of: `all` (All chains), `ethereum`, `base`, `arbitrum`, `optimism`. Default: `all`.
- Aggregator (`project`, text): Only this aggregator. Leave empty for all of them.
- Only fair comparisons (`comparable_only`, true/false): Show only venues where the user sends the swap themselves, so the rates can be ranked against each other. Turn off to include every venue. Default: `true`.
- Number of rows (`limit`, number): How many rows to return, from 1 to 200. Defaults to 50. From 1 to 200. Default: `50`.

**Outputs**

- `rate_count` (number)
- `rates` (list)
- `total_matches` (number)

**Example output**

```json
{
  "rate_count": 1,
  "rates": [
    {
      "chain": "arbitrum",
      "comparable": true,
      "execution_model": "router",
      "failed_txs": 383,
      "project": "okx",
      "revert_rate_pct": 5.95,
      "total_txs": 6436,
      "user_failed_txs": 42,
      "user_revert_rate_pct": 0.79,
      "user_txs": 5307
    }
  ],
  "total_matches": 53
}
```

### Get gas prices

Get the gas price right now on Ethereum, Base, Arbitrum and Optimism, and which is cheapest, to time a transaction or compare costs.

**Inputs**: None.

**Outputs**

- `arbitrum_gwei` (number)
- `base_gwei` (number)
- `cheapest_chain` (text)
- `ethereum_gwei` (number)
- `optimism_gwei` (number)
- `prices` (list)

**Example output**

```json
{
  "arbitrum_gwei": 0.02,
  "base_gwei": 0.006,
  "cheapest_chain": "optimism",
  "ethereum_gwei": 0.1371,
  "optimism_gwei": 0.001,
  "prices": [
    {
      "chain": "ethereum",
      "gas_price_gwei": 0.1371,
      "gas_price_wei": 137139772
    },
    {
      "chain": "base",
      "gas_price_gwei": 0.006,
      "gas_price_wei": 6000000
    },
    {
      "chain": "arbitrum",
      "gas_price_gwei": 0.02,
      "gas_price_wei": 20000000
    },
    {
      "chain": "optimism",
      "gas_price_gwei": 0.001,
      "gas_price_wei": 1004144
    }
  ]
}
```

### Get recent trades

Get a sample of recent exchange trades on one chain, newest first: the tokens swapped, the dollar value, the exchange and any aggregator, the gas paid and whether it went through. The sample is small and refreshed on each data sync, not a live feed of every trade.

**Inputs**

- Chain (`chain`, text): Which chain to sample. One of: `ethereum`, `base`, `arbitrum`, `optimism`. Default: `ethereum`.
- Exchange (`dex`, text): Only trades filled on this exchange. Leave empty for any.
- Aggregator (`aggregator`, text): Only trades routed by this aggregator. Leave empty for any.
- Token sold (`token_sold`, text): Only trades selling this token symbol, such as USDT.
- Token bought (`token_bought`, text): Only trades buying this token symbol, such as WETH.
- From (`after`, date and time): Only trades at or after this time (UTC if no zone).
- To (`before`, date and time): Only trades at or before this time (UTC if no zone).
- Outcome (`outcome`, text): Every trade, or only ones that went through or failed. One of: `any`, `succeeded` (Went through), `failed`. Default: `any`.
- Number of trades (`limit`, number): How many trades to return, from 1 to 50. Defaults to 10. From 1 to 50. Default: `10`.

**Outputs**

- `chain` (text)
- `total_matches` (number)
- `trade_count` (number)
- `trades` (list)

**Example output**

```json
{
  "chain": "ethereum",
  "total_matches": 44,
  "trade_count": 1,
  "trades": [
    {
      "aggregator": null,
      "chain": "ethereum",
      "dex": "curve",
      "explorer_url": "https://etherscan.io/tx/0x7475a4141180d3157456eddbe0fb1681ca8209e7f4e57a65af4bf09680da9611",
      "gas_fee_eth": 0.0001598116,
      "gas_fee_usd": 0.3864,
      "gas_used": 847188,
      "routing_legs": 1,
      "succeeded": true,
      "time": "2026-10-14T21:09:23Z",
      "timestamp": 1792012163,
      "token_bought": "crvUSD",
      "token_sold": "USDT",
      "tx_hash": "0x7475a4141180d3157456eddbe0fb1681ca8209e7f4e57a65af4bf09680da9611",
      "volume_usd": 23438.36
    }
  ]
}
```

### Get routing flows

See where trades are handed from one interface to another, largest first: for example how much volume regular wallets send into a given router. Filter either end by part of its name.

**Inputs**

- From (`source`, text): Only flows starting at a name containing this.
- To (`target`, text): Only flows ending at a name containing this.
- Number of flows (`limit`, number): How many flows to return, from 1 to 500. Defaults to 25. From 1 to 500. Default: `25`.

**Outputs**

- `flow_count` (number)
- `flows` (list)
- `total_flows` (number)

**Example output**

```json
{
  "flow_count": 1,
  "flows": [
    {
      "source": "Direct Retail (EOA)",
      "target": "GPv2Settlement",
      "volume_usd": 3162062436.46
    }
  ],
  "total_flows": 136
}
```

### Get sandwich attacks

Get the biggest sandwich attacks of the last 7 days, where a bot trades just before and after someone to profit from their trade, with the victim's wallet and trade size and the week's totals. Weekly totals count victims trading at least $1,000.

**Inputs**

- Chain (`chain`, text): One chain, or all four. One of: `all` (All chains), `ethereum`, `base`, `arbitrum`, `optimism`. Default: `all`.
- Exchange (`project`, text): Only attacks on this exchange. Leave empty for any.
- Smallest victim trade (USD) (`min_victim_usd`, number): Only attacks where the victim's trade was at least this many US dollars. Leave empty for any size. From 0 to 1000000000.
- Number of attacks (`limit`, number): How many attacks to return, from 1 to 200. Defaults to 25. From 1 to 200. Default: `25`.

**Outputs**

- `attack_count` (number)
- `attacks` (list)
- `attacks_7d` (number): Attacks in the last 7 days, all chains.
- `sandwiched_usd_7d` (number): Dollars sandwiched in the last 7 days.
- `top_pair_7d` (text)
- `top_pair_chain` (text)
- `top_pair_share_pct` (number): Share of the week's attacks on that one pair. Above 50, the total mostly describes one pool.
- `total_matches` (number)
- `victim_floor_usd` (number): Smallest victim trade the weekly totals count.

**Example output**

```json
{
  "attack_count": 1,
  "attacks": [
    {
      "chain": "optimism",
      "chain_attacks_7d": 44,
      "chain_sandwiched_usd_7d": 152381.95,
      "explorer_url": "https://optimistic.etherscan.io/tx/0x67560cab23095518f56ac9ef8cd582eb6a9e7595667c4f64061488b1e4a657b8",
      "project": "velodrome",
      "time": "2026-10-14T21:03:51Z",
      "token_pair": "USDC-WETH",
      "tx_hash": "0x67560cab23095518f56ac9ef8cd582eb6a9e7595667c4f64061488b1e4a657b8",
      "victim_volume_usd": 1336.5,
      "victim_wallet": "0x7c40c792f376d2921854faa4c52985b906aae2f3"
    }
  ],
  "attacks_7d": 7554,
  "sandwiched_usd_7d": 65300347.46,
  "top_pair_7d": "USDC-XDP",
  "top_pair_chain": "base",
  "top_pair_share_pct": 69.3,
  "total_matches": 302,
  "victim_floor_usd": 1000.0
}
```

### Get volume by source

See which apps, routers and contracts send the most exchange volume, largest first, split by how it was routed. This is ClearTrace's main attribution table.

**Inputs**

- Chain (`chain`, text): One chain, or all four. One of: `all` (All chains), `ethereum`, `base`, `arbitrum`, `optimism`. Default: `all`.
- Name contains (`project`, text): Only sources whose name contains this, such as 1inch.
- Number of sources (`limit`, number): How many sources to return, from 1 to 1000. Defaults to 25. From 1 to 1000. Default: `25`.
- Skip (`skip`, number): How many rows to skip first, to page through a long list. Leave at 0 for the top of the list. From 0 to 1000000. Default: `0`.

**Outputs**

- `record_count` (number)
- `records` (list)
- `total_records` (number)

**Example output**

```json
{
  "record_count": 1,
  "records": [
    {
      "aggregator_partner_volume_usd": 0.0,
      "aggregator_volume_usd": 888.84,
      "calldata_suffix_volume_usd": 867652.06,
      "chain": "base",
      "direct_volume_usd": 0.0,
      "fee_transfer_volume_usd": 2445198.16,
      "name": "uniswap: UniversalRouter",
      "proxy_volume_usd": 886500384.24,
      "total_volume_usd": 886501273.08
    }
  ],
  "total_records": 9323
}
```

### List contract labels

List the busy contracts ClearTrace has profiled, with the name it found for each where it found one, what kind of contract it is and how sure it is.

**Inputs**

- Chain (`chain`, text): One chain, or all four. One of: `all` (All chains), `ethereum`, `base`, `arbitrum`, `optimism`. Default: `all`.
- Number of contracts (`limit`, number): How many contracts to return, from 1 to 200. Defaults to 50. From 1 to 200. Default: `50`.
- Skip (`skip`, number): How many rows to skip first, to page through a long list. Leave at 0 for the top of the list. From 0 to 1000000. Default: `0`.

**Outputs**

- `label_count` (number)
- `labels` (list)
- `total_labels` (number)

**Example output**

```json
{
  "label_count": 1,
  "labels": [
    {
      "address": "0x7293d41c28e5fc2292e62d26fec60e22a145d1a5",
      "chain": "base",
      "code_size_bytes": 731,
      "confidence": "high",
      "entity_type": "router_or_proxy",
      "explorer_url": "https://basescan.org/address/0x7293d41c28e5fc2292e62d26fec60e22a145d1a5",
      "label": "TerminalSwapX (proxy)",
      "source": "proxy-implementation"
    }
  ],
  "total_labels": 3669
}
```

### Look up where a trade came from

Look up one trade by its transaction hash and find out which app, router or aggregator it came through and how ClearTrace knows, plus the pools it touched, any fees skimmed off it and whether it was sandwiched. A block explorer link to the transaction works in place of the hash.

**Inputs**

- Transaction hash (`tx_hash`, text, required): The trade's transaction hash (0x and 64 characters), or a block explorer link to it.
- Chain (`chain`, text): The chain the trade happened on. One of: `ethereum`, `base`, `arbitrum`, `optimism`. Default: `ethereum`.
- Estimate the dollar value (`estimate_usd`, true/false): Add a rough dollar size for the trade, from today's spot price. Slower, and never a settlement figure. Default: `false`.
- Check internal calls (`use_traces`, true/false): Look inside the transaction's internal calls to catch an aggregator hidden behind another contract. Slower; works best on Ethereum. Default: `false`.

**Outputs**

- `aggregator_name` (text)
- `chain` (text)
- `estimated_volume_usd` (number)
- `explorer_url` (text)
- `fee_recipients` (list)
- `frontend_attributed` (true/false)
- `frontend_confidence` (text)
- `frontend_method` (text)
- `frontend_name` (text): The app it came from, when ClearTrace is sure.
- `frontend_type` (text): named_frontend, aggregator_api_direct, wallet_embedded, bots_mev or unattributed.
- `has_calldata_suffix` (true/false)
- `is_aggregator` (true/false)
- `is_direct` (true/false)
- `is_proxy` (true/false)
- `originator_address` (text): The contract the trade called.
- `originator_name` (text)
- `pools` (list)
- `primary_vector` (text): The main way it was routed: proxy, aggregator, fee_recipient, calldata_suffix, direct or unclassified.
- `routing_legs` (number)
- `sandwiched` (true/false)
- `succeeded` (true/false)
- `tx_hash` (text)
- `vectors` (list)
- `volume_estimate_basis` (text)

**Example output**

```json
{
  "aggregator_name": null,
  "chain": "ethereum",
  "estimated_volume_usd": 23439.91,
  "explorer_url": "https://etherscan.io/tx/0xee24d08530006e146b9afc88f015f768447d727685f060c5a801484e7b585982",
  "fee_recipients": [],
  "frontend_attributed": false,
  "frontend_confidence": "none",
  "frontend_method": "none",
  "frontend_name": null,
  "frontend_type": "unattributed",
  "has_calldata_suffix": false,
  "is_aggregator": false,
  "is_direct": false,
  "is_proxy": true,
  "originator_address": "0x950fd558f47e234a2fde23b7d61f7ccdbcb4a86f",
  "originator_name": null,
  "pools": [
    "0x000000000004444c5dc75cb358380d2e3de08a90"
  ],
  "primary_vector": "proxy",
  "routing_legs": 2,
  "sandwiched": false,
  "succeeded": true,
  "tx_hash": "0xee24d08530006e146b9afc88f015f768447d727685f060c5a801484e7b585982",
  "vectors": [
    "proxy"
  ],
  "volume_estimate_basis": "approximate: DefiLlama spot price"
}
```

### Rank exchanges by slippage

Rank decentralised exchanges and aggregators by how close their trades land to the market price, best first. Each gets a Slippage Score from 0 to 100 and the number of trades it is based on. Exchanges with fewer than 1,000 trades are left out.

**Inputs**

- Chain (`chain`, text): Rank on one chain, or blend all four. Scores differ by chain, so pick one to compare like with like. One of: `all` (All chains), `ethereum`, `base`, `arbitrum`, `optimism`. Default: `all`.
- Number of exchanges (`limit`, number): How many exchanges to return, from 1 to 100. Defaults to 20. From 1 to 100. Default: `20`.

**Outputs**

- `best_name` (text)
- `best_score` (number)
- `chain` (text)
- `protocol_count` (number)
- `protocols` (list)
- `total_protocols` (number): How many exchanges are scored in all.

**Example output**

```json
{
  "best_name": "maverick",
  "best_score": 98.61,
  "chain": "base",
  "protocol_count": 1,
  "protocols": [
    {
      "category": "DEX",
      "dispersion_ratio": 8.18,
      "median_slippage_bps": 1.39,
      "name": "maverick",
      "pct_trades_paid": 53.5,
      "rank": 1,
      "signed_median_bps": 0.17,
      "slippage_direction": "cost",
      "slippage_score": 98.61,
      "trades_analyzed": 4199
    }
  ],
  "total_protocols": 17
}
```