Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Cleartracedata Com Contract Intelligence API
version: 1.4.0
description: 'Operations tagged Contract Intelligence across 2 of this provider''s published API definitions: cleartracedata-com-openapi.json, cleartracedata-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://cleartracedata.com
description: 'Production (base stated in https://cleartracedata.com/docs/quickstart: https://cleartracedata.com/api/v1)'
tags:
- name: Contract Intelligence
paths:
/api/v1/contract/{address}/profile:
get:
tags:
- Contract Intelligence
summary: Get Contract On-Chain Profile
description: '**Public API: Returns a full on-chain profile for any contract or wallet address.**
Powered by Alchemy''s enhanced APIs, this endpoint provides:
- **Token Balances**: All ERC-20 tokens held by the address via `alchemy_getTokenBalances`
- **Contract Metadata**: Bytecode size, ETH balance, account nonce
- **Auto-Classification**: Heuristic-based classification (treasury, MEV bot, router, factory, etc.)
Note on `nonce`: it is an activity count only for an EOA. A contract''s nonce
starts at 1 and increments only on CREATE, so for a contract it reports
contracts deployed (`nonce - 1`), not transactions sent. That derived count
is served directly as `contracts_deployed` (null for an EOA, where it cannot
be read off the nonce). The legacy `transaction_count` field carries the
same value as `nonce` and is deprecated.
This is useful for identifying unknown proxy contracts in DEX attribution data.'
operationId: get_contract_profile_api_v1_contract__address__profile_get
parameters:
- name: address
in: path
required: true
schema:
type: string
title: Address
- name: chain
in: query
required: false
schema:
type: string
description: Blockchain network to query.
enum:
- ethereum
- base
- arbitrum
- optimism
default: ethereum
title: Chain
description: Blockchain network to query.
responses:
'200':
description: A comprehensive on-chain profile including token balances, code size, ETH balance, and automated classification.
content:
application/json:
schema:
$ref: '#/components/schemas/ContractProfileResponse'
/api/v1/contract/{address}/attribution:
get:
tags:
- Contract Intelligence
summary: Get Address Attribution Breakdown
description: '**Public API: Returns the attribution breakdown for a single address.**
Pairs the cross-frontend attribution engine with the labeling pipeline: for
a given contract or wallet, this returns its per-chain volume split across
the four attribution vectors (proxy, calldata-suffix, fee-recipient,
aggregator), plus any human-readable label we''ve resolved.
Most useful for the **unlabeled** proxies and hidden frontends the engine
surfaces as `Unknown Proxy/Frontend (0x…)` — known, named protocol
contracts are keyed by name rather than address and may not resolve here.'
operationId: get_address_attribution_api_v1_contract__address__attribution_get
parameters:
- name: address
in: path
required: true
schema:
type: string
title: Address
- name: chain
in: query
required: false
schema:
type: string
description: Filter to a single blockchain (ethereum, base, arbitrum, optimism).
title: Chain
description: Filter to a single blockchain (ethereum, base, arbitrum, optimism).
responses:
'200':
description: The cross-frontend attribution breakdown (4 vectors) for a single address, enriched with its auto-discovered label.
content:
application/json:
schema:
$ref: '#/components/schemas/AddressAttributionResponse'
/api/v1/tx/{tx_hash}:
get:
tags:
- Contract Intelligence
summary: Per-Transaction Attribution
description: '**Public API: Classifies a single transaction against the attribution engine.**
Given a transaction hash, this fetches the transaction and its receipt from
Alchemy and applies the same four vectors used in our aggregate attribution
(calldata-suffix, proxy-router, fee-recipient, aggregator) to tell you
*which frontend/router originated the trade and how we know* — plus the
pools touched, fee recipients, and whether the tx was sandwiched.
Results are cached permanently (mined transactions are immutable). Fee
amounts are exact raw token units. With `price=true`, an APPROXIMATE USD
trade size is added (best-effort spot price, dominant leg) — never treat it
as a settlement figure.'
operationId: get_tx_attribution_api_v1_tx__tx_hash__get
parameters:
- name: tx_hash
in: path
required: true
schema:
type: string
title: Tx Hash
- name: chain
in: query
required: false
schema:
type: string
description: Blockchain to query.
enum:
- ethereum
- base
- arbitrum
- optimism
default: ethereum
title: Chain
description: Blockchain to query.
- name: deep
in: query
required: false
schema:
type: boolean
description: Use internal call traces to refine the classification (catches aggregators that sit as intermediates, e.g. a router reached through a separate settlement contract, and runs the calldata-suffix test per sub-call). Costs more Alchemy CU; trace support is strongest on Ethereum.
default: false
title: Deep
description: Use internal call traces to refine the classification (catches aggregators that sit as intermediates, e.g. a router reached through a separate settlement contract, and runs the calldata-suffix test per sub-call). Costs more Alchemy CU; trace support is strongest on Ethereum.
- name: price
in: query
required: false
schema:
type: boolean
description: Add a best-effort, APPROXIMATE USD trade size (dominant priced leg via the free DefiLlama spot-price API). Adds latency; never a settlement figure.
default: false
title: Price
description: Add a best-effort, APPROXIMATE USD trade size (dominant priced leg via the free DefiLlama spot-price API). Adds latency; never a settlement figure.
responses:
'200':
description: Live classification of a single transaction against the four attribution vectors.
content:
application/json:
schema:
$ref: '#/components/schemas/TxAttributionResponse'
/api/v1/labels:
get:
tags:
- Contract Intelligence
summary: Auto-Discovered Contract Labels
description: '**Public API: Returns contract labels discovered by the auto-labeling pipeline.**
Each sync, the highest-volume unattributed contracts are profiled through
local intelligence tables and Alchemy RPC (token metadata, bytecode size,
activity) to classify and, where possible, name them.'
operationId: get_contract_labels_api_v1_labels_get
parameters:
- name: chain
in: query
required: false
schema:
type: string
description: Filter by blockchain (ethereum, base, arbitrum, optimism).
title: Chain
description: Filter by blockchain (ethereum, base, arbitrum, optimism).
- name: limit
in: query
required: false
schema:
type: integer
maximum: 200
minimum: 1
description: Maximum number of labels to return.
default: 50
title: Limit
description: Maximum number of labels to return.
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
description: Pagination offset.
default: 0
title: Offset
description: Pagination offset.
responses:
'200':
description: Labels for high-volume contracts resolved by the Alchemy-powered auto-labeling pipeline.
content:
application/json:
schema:
$ref: '#/components/schemas/ContractLabelsResponse'
components:
schemas:
AddressAttributionResponse:
properties:
address:
type: string
title: Address
description: The queried address (lower-cased).
records:
items:
$ref: '#/components/schemas/AddressAttributionRecord'
type: array
title: Records
description: Per-chain attribution breakdown for this address, largest volume first.
total_volume_usd:
type: number
title: Total Volume Usd
description: Total attributed volume for this address summed across all returned chains.
chains_found:
type: integer
title: Chains Found
description: Number of chains on which this address has attributed volume.
type: object
required:
- address
- records
- total_volume_usd
- chains_found
title: AddressAttributionResponse
OriginatingFrontend:
properties:
bucket:
type: string
title: Bucket
description: 'Taxonomy class: named_frontend, aggregator_api_direct, wallet_embedded, bots_mev, or unattributed.'
example: aggregator_api_direct
frontend_name:
anyOf:
- type: string
- type: 'null'
title: Frontend Name
description: Resolved frontend/aggregator identity, when confident.
example: '1inch: AggregationRouterV6'
method:
type: string
title: Method
description: 'How the frontend was attributed: calldata_suffix, fee_recipient, aggregator, router_heuristic, or none.'
example: aggregator
confidence:
type: string
title: Confidence
description: 'Attribution-method strength: high (suffix), medium (router/fee), low (inferred), or none.'
example: medium
attributed:
type: boolean
title: Attributed
description: True when the swap was confidently placed into a class (bucket != unattributed).
fingerprinted:
type: boolean
title: Fingerprinted
description: True when a calldata fingerprint proves a frontend tagged the swap but its identity could not be resolved.
default: false
type: object
required:
- bucket
- method
- confidence
- attributed
title: OriginatingFrontend
TxAttributionResponse:
properties:
tx_hash:
type: string
title: Tx Hash
description: The queried transaction hash (lower-cased).
chain:
type: string
title: Chain
description: The blockchain the lookup ran against.
example: ethereum
found:
type: boolean
title: Found
description: Whether the transaction was found and classified.
status:
anyOf:
- type: integer
- type: 'null'
title: Status
description: On-chain receipt status (1 = success, 0 = reverted).
example: 1
primary_vector:
anyOf:
- type: string
- type: 'null'
title: Primary Vector
description: 'The dominant attribution vector: proxy, aggregator, fee_recipient, calldata_suffix, direct, or unclassified.'
example: aggregator
vectors:
items:
type: string
type: array
title: Vectors
description: All attribution vectors this transaction matches.
originator:
anyOf:
- $ref: '#/components/schemas/TxOriginator'
- type: 'null'
description: The contract that originated the trade (tx_to) and its resolved name.
is_direct:
type: boolean
title: Is Direct
description: Whether the caller hit a DEX pool directly.
default: false
is_proxy:
type: boolean
title: Is Proxy
description: Whether the trade routed through a proxy/router (hidden-frontend signal).
default: false
is_aggregator:
type: boolean
title: Is Aggregator
description: Whether a known aggregator router was involved.
default: false
aggregator_name:
anyOf:
- type: string
- type: 'null'
title: Aggregator Name
description: Name of the matched aggregator, if any.
has_calldata_suffix:
type: boolean
title: Has Calldata Suffix
description: Whether the calldata carries a non-ABI-aligned suffix fingerprint.
default: false
fee_recipients:
items:
$ref: '#/components/schemas/TxFeeRecipient'
type: array
title: Fee Recipients
description: Addresses that skimmed a fee out of the swap.
pools:
items:
type: string
type: array
title: Pools
description: Liquidity pools (Swap-event emitters) touched by the transaction.
routing_legs:
type: integer
title: Routing Legs
description: Number of Swap events (pool legs) in the transaction.
default: 0
sandwiched:
type: boolean
title: Sandwiched
description: Whether this transaction appears as a victim in our detected sandwich set.
default: false
trace_used:
type: boolean
title: Trace Used
description: Whether internal traces were used to refine the classification (deep mode).
default: false
deep:
type: boolean
title: Deep
description: Whether deep (trace-based) classification was requested.
default: false
estimated_volume_usd:
anyOf:
- type: number
- type: 'null'
title: Estimated Volume Usd
description: Best-effort, APPROXIMATE USD trade size (dominant priced leg, DefiLlama spot price). Null when pricing was not requested or no leg could be priced. Never use as a settlement figure.
volume_estimate_basis:
anyOf:
- type: string
- type: 'null'
title: Volume Estimate Basis
description: How estimated_volume_usd was derived, when present.
price:
type: boolean
title: Price
description: Whether best-effort USD sizing was requested.
default: false
cached:
type: boolean
title: Cached
description: Whether this result was served from cache.
default: false
originating_frontend:
anyOf:
- $ref: '#/components/schemas/OriginatingFrontend'
- type: 'null'
description: The trade's originating frontend, mapped onto the ClearTrace taxonomy (the spine). Derived from the attribution vectors.
note:
anyOf:
- type: string
- type: 'null'
title: Note
description: Diagnostic note (e.g. when Alchemy is unconfigured or the tx is unknown).
type: object
required:
- tx_hash
- chain
- found
title: TxAttributionResponse
AddressAttributionRecord:
properties:
chain:
type: string
title: Chain
description: The blockchain network.
example: ethereum
resolved_contract_name:
type: string
title: Resolved Contract Name
description: The name the attribution engine assigned this address (often 'Unknown Proxy/Frontend (0x…)' for unlabeled contracts).
example: Unknown Frontend (0x8f10b468b06c6fd214b65f87778827f7d113f996)
label:
anyOf:
- type: string
- type: 'null'
title: Label
description: Human-readable label from the auto-labeling pipeline, if one exists for this address+chain.
example: Banana Gun Router
entity_type:
anyOf:
- type: string
- type: 'null'
title: Entity Type
description: 'Classification from the labeling pipeline: token, router_or_proxy, contract, eoa, or delegated_eoa (EIP-7702).'
example: router_or_proxy
label_source:
anyOf:
- type: string
- type: 'null'
title: Label Source
description: Where the label came from (nansen, arkham, etherscan, alchemy-*).
example: arkham
confidence:
anyOf:
- type: string
- type: 'null'
title: Confidence
description: 'Label confidence: high, medium, or low.'
example: high
total_volume_usd:
type: number
title: Total Volume Usd
description: Total USD volume attributed to this address on this chain. This is the sum of the four PARTITION columns (`aggregator_partner_volume_usd`, `aggregator_volume_usd`, `direct_volume_usd`, `proxy_volume_usd`) and deliberately EXCLUDES the overlay columns (`calldata_suffix_volume_usd`, `erc20_fee_volume_usd`), so summing every volume field double-counts.
example: 10156290.0
aggregator_partner_volume_usd:
type: number
title: Aggregator Partner Volume Usd
description: Volume explicitly tagged with an aggregator partner code.
example: 0.0
aggregator_volume_usd:
type: number
title: Aggregator Volume Usd
description: Standard aggregator volume.
example: 0.0
calldata_suffix_volume_usd:
type: number
title: Calldata Suffix Volume Usd
description: 'Volume attributed via calldata suffix fingerprinting. OVERLAY, not a component of `total_volume_usd`: it re-describes dollars already counted in the partition columns, seen through a different attribution vector, and is deliberately excluded from the total. It may therefore EXCEED `total_volume_usd`, which is correct and not a bug. Never add it to a partition column: that double-counts.'
example: 0.0
direct_volume_usd:
type: number
title: Direct Volume Usd
description: Volume routed directly to DEX pools.
example: 0.0
erc20_fee_volume_usd:
type: number
title: Erc20 Fee Volume Usd
description: 'Volume attributed via secondary fee transfers: the fee-kickback vector credits the full trade amount to every intermediate transfer recipient in a transaction, so pools, vaults and multisigs accumulate large figures without being swap venues. OVERLAY, not a component of `total_volume_usd`: it re-describes dollars already counted in the partition columns, seen through a different attribution vector, and is deliberately excluded from the total. It may therefore EXCEED `total_volume_usd`, which is correct and not a bug. Never add it to a partition column: that double-counts.'
example: 0.0
proxy_volume_usd:
type: number
title: Proxy Volume Usd
description: Volume routed through an unverified proxy before hitting DEX pools.
example: 0.0
type: object
required:
- chain
- resolved_contract_name
- total_volume_usd
- aggregator_partner_volume_usd
- aggregator_volume_usd
- calldata_suffix_volume_usd
- direct_volume_usd
- erc20_fee_volume_usd
- proxy_volume_usd
title: AddressAttributionRecord
ContractProfile:
properties:
address:
type: string
title: Address
description: The queried contract address.
chain:
type: string
title: Chain
description: The blockchain network.
example: ethereum
is_contract:
type: boolean
title: Is Contract
description: Whether the address is a smart contract.
example: true
code_size_bytes:
type: integer
title: Code Size Bytes
description: Size of the deployed bytecode in bytes.
example: 4096
eth_balance:
type: number
title: Eth Balance
description: Native ETH balance.
example: 1.25
nonce:
type: integer
title: Nonce
description: 'The account nonce (eth_getTransactionCount). For an EOA this is the number of transactions sent. For a CONTRACT it is NOT an activity count: a contract''s nonce starts at 1 and increments only on CREATE, so it counts contracts deployed (nonce - 1).'
example: 42
contracts_deployed:
anyOf:
- type: integer
- type: 'null'
title: Contracts Deployed
description: 'How many contracts this address has CREATEd, for a CONTRACT: it is `nonce - 1`, served directly so a consumer does not have to know that rule. NULL when `is_contract` is false — an EOA''s nonce counts the transactions it sent, and some of those may have been deployments, so the CREATE count is genuinely unknown from the nonce alone. Null means unknown here, never zero.'
example: 1612
transaction_count:
type: integer
title: Transaction Count
description: DEPRECATED, use `nonce` instead. Identical value, kept for backward compatibility. The name is misleading for contracts, where this counts contracts deployed rather than transactions sent.
deprecated: true
example: 42
token_balances:
items:
$ref: '#/components/schemas/TokenBalance'
type: array
title: Token Balances
description: All ERC-20 token balances held by this address.
classification_hint:
type: string
title: Classification Hint
description: Automated classification based on on-chain signals.
example: treasury
type: object
required:
- address
- chain
- is_contract
- code_size_bytes
- eth_balance
- nonce
- transaction_count
- token_balances
- classification_hint
title: ContractProfile
ContractProfileResponse:
properties:
profile:
$ref: '#/components/schemas/ContractProfile'
description: Full on-chain profile of the contract address.
type: object
required:
- profile
title: ContractProfileResponse
ContractLabelsResponse:
properties:
labels:
items:
$ref: '#/components/schemas/ContractLabel'
type: array
title: Labels
description: Contract labels discovered by the auto-labeling pipeline.
total:
type: integer
title: Total
description: Total number of matching labels.
limit:
type: integer
title: Limit
description: The maximum number of labels returned.
offset:
type: integer
title: Offset
description: The offset used for pagination.
type: object
required:
- labels
- total
- limit
- offset
title: ContractLabelsResponse
TokenBalance:
properties:
contract:
type: string
title: Contract
description: The ERC-20 token contract address.
example: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
symbol:
type: string
title: Symbol
description: The token ticker symbol.
example: USDC
name:
type: string
title: Name
description: The full token name.
example: USD Coin
balance:
type: number
title: Balance
description: The human-readable token balance.
example: 1542.5
type: object
required:
- contract
- symbol
- name
- balance
title: TokenBalance
TxOriginator:
properties:
address:
type: string
title: Address
description: The contract the transaction called (tx_to).
example: '0x111111125421ca6dc452d289314280a0f8842a65'
name:
anyOf:
- type: string
- type: 'null'
title: Name
description: Resolved label for that contract, if known.
example: '1inch: AggregationRouterV6'
type: object
required:
- address
title: TxOriginator
TxFeeRecipient:
properties:
address:
type: string
title: Address
description: The fee-collecting address.
example: '0x37305b1cd40574e4c5ce33f8e8306be057fd7341'
name:
anyOf:
- type: string
- type: 'null'
title: Name
description: Resolved label for the recipient, if known.
example: 'Banana Gun: Fee Wallet'
token_contract:
type: string
title: Token Contract
description: The ERC-20 contract the fee was paid in.
example: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
raw_amount:
type: string
title: Raw Amount
description: Exact token amount transferred (raw integer, no decimals/USD applied).
example: '1250000'
type: object
required:
- address
- token_contract
- raw_amount
title: TxFeeRecipient
ContractLabel:
properties:
address:
type: string
title: Address
description: The contract address.
example: '0xbdb3ba9ffe392549e1f8658dd2630c141fdf47b6'
chain:
type: string
title: Chain
description: The blockchain the contract was profiled on.
example: ethereum
label:
anyOf:
- type: string
- type: 'null'
title: Label
description: Resolved human-readable name, when one was found.
example: Banana Gun Router
entity_type:
type: string
title: Entity Type
description: 'Classification: token, router_or_proxy, contract, eoa, or delegated_eoa (EIP-7702).'
example: router_or_proxy
source:
type: string
title: Source
description: 'Where the label came from: nansen, arkham, etherscan, alchemy-token-metadata, or alchemy-heuristic.'
example: alchemy-heuristic
confidence:
type: string
title: Confidence
description: 'Label confidence: high, medium, or low.'
example: medium
code_size:
anyOf:
- type: integer
- type: 'null'
title: Code Size
description: Deployed bytecode size in bytes (0 for EOAs).
example: 12048
type: object
required:
- address
- chain
- entity_type
- source
- confidence
title: ContractLabel
x-refined-from:
- cleartracedata-com-openapi.json
- cleartracedata-com-openapi.yml