ERC20 Token Transfers
Track transfers of ERC20 tokens including stablecoins (USDT, USDC, DAI) and other tokens.
Endpoint: GET /v1/erc20/events/transfer
Supported Networks: ETH, POLYGON, ARB, OP, BASE, BSC, AVAX
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
token | string | Yes | Token symbol (e.g., USDT) or contract address (e.g., 0x...). Case-insensitive for symbols (usdt, Usdt, USDT are equivalent). |
decimals | integer | No | Token decimals when using custom address (default: 18) |
min_amount | number | No | Minimum transfer amount (in token units) |
max_amount | number | No | Maximum transfer amount (0 = no limit) |
sender | string | No | Filter by sender address |
receiver | string | No | Filter by receiver address |
involving | string | No | Filter by address involved as either sender OR receiver. Mutually exclusive with sender and receiver. |
involving_label | string | No | Filter where any address matches a label substring (e.g., Binance). Mutually exclusive with involving, `sender,receiver`. |
involving_category | string | No | Filter where any address matches a category (e.g., exchange). Mutually exclusive with involving, `sender,receiver`. |
sender_label | string | No | Filter sender by label substring. Mutually exclusive with sender, sender_category, `involving`.* |
sender_category | string | No | Filter sender by category. Mutually exclusive with sender, sender_label, `involving`.* |
receiver_label | string | No | Filter receiver by label substring. Mutually exclusive with receiver, receiver_category, `involving`.* |
receiver_category | string | No | Filter receiver by category. Mutually exclusive with receiver, receiver_label, `involving`.* |
Supported Tokens:
The API supports a wide range of ERC20 tokens including major stablecoins (USDT, USDC, DAI, USDE, etc.) and other tokens. You can also track any ERC20 token by providing its contract address directly.
To get the full list of supported token symbols, call the List Tokens discovery endpoint:
curl -H "X-API-Key: $API_KEY"
"https://api.defistream.dev/v1/tokens"Sample Results:
| block_number | token | sender | receiver | amount | time |
|---|---|---|---|---|---|
| 24000000 | USDT | 0x2158…a6a9 | 0x8b07…1d4d | 28.0 | 2025-12-13T00:06:11Z |
| 24000000 | USDT | 0x5050…2edf | 0x11b8…7f6 | 7638.83 | 2025-12-13T00:06:11Z |
| 24000000 | USDT | 0xae71…4bc6 | 0x1c01…06bd | 320.86 | 2025-12-13T00:06:11Z |
| 24000000 | USDT | 0x5050…2edf | 0xc7bb…f9b | 5308.99 | 2025-12-13T00:06:11Z |
| 24000000 | USDT | 0x5050…2edf | 0x0000…a90 | 4661.27 | 2025-12-13T00:06:11Z |
Example: Track large USDT transfers
curl -H "X-API-Key: $API_KEY"
"https://api.defistream.dev/v1/erc20/events/transfer?network=ETH&block_start=24000000&block_end=24010000&token=USDT&min_amount=100000"Example: Track transfers to a specific address
curl -H "X-API-Key: $API_KEY"
"https://api.defistream.dev/v1/erc20/events/transfer?network=ETH&block_start=24000000&block_end=24010000&token=USDC&receiver=0x1234567890abcdef1234567890abcdef12345678"Example: Custom token by address
curl -H "X-API-Key: $API_KEY"
"https://api.defistream.dev/v1/erc20/events/transfer?network=ETH&block_start=24000000&block_end=24010000&token=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48&decimals=6"Example: Track USDT transfers involving Binance wallets
curl -H "X-API-Key: $API_KEY"
"https://api.defistream.dev/v1/erc20/events/transfer?network=ETH&block_start=24000000&block_end=24010000&token=USDT&involving_label=Binance"Example: Track USDT transfers FROM exchanges TO DeFi protocols
curl -H "X-API-Key: $API_KEY"
"https://api.defistream.dev/v1/erc20/events/transfer?network=ETH&block_start=24000000&block_end=24010000&token=USDT&sender_category=exchange&receiver_category=defi"Aggregate Queries
Bucket ERC20 transfer events into time or block intervals with summary statistics.
Endpoint: GET /v1/erc20/events/transfer/aggregate
Requires group_by (time or block_number) and period (e.g., 2h, 1d, 10000).
Aggregated columns: agg_amount (sum of transfer amounts), count (number of transfers)
Example: Hourly USDT transfer volume
curl -H "X-API-Key: $API_KEY"
"https://api.defistream.dev/v1/erc20/events/transfer/aggregate?network=ETH&block_start=21000000&block_end=21100000&token=USDT&group_by=time&period=1h"Sample Aggregate Results:
| time_start | time_end | agg_amount | count |
|---|---|---|---|
| 2024-11-08T00:00:00Z | 2024-11-08T01:00:00Z | 45823190.42 | 1247 |
| 2024-11-08T01:00:00Z | 2024-11-08T02:00:00Z | 38291045.18 | 1053 |
| 2024-11-08T02:00:00Z | 2024-11-08T03:00:00Z | 29104582.67 | 892 |
| 2024-11-08T03:00:00Z | 2024-11-08T04:00:00Z | 31578204.91 | 964 |
| 2024-11-08T04:00:00Z | 2024-11-08T05:00:00Z | 42195063.35 | 1128 |
Quota & Limits
ERC-20 endpoints use a block-based quota model. Cost formula: max(100, round(block_range × network_discount × aggregate_discount)).
| Format | Max time range | Max block range | Quota cost |
|---|---|---|---|
| JSON | 7 days | 10,000 | block_range (min 100) |
| CSV / Parquet | 7 days | 1,000,000 | block_range (min 100) |
| CSV / Parquet (ARB) | 7 days | 10,000,000 | block_range × 0.2 (min 100) |
| Aggregate | 7 days | same as above | block_range × 0.5 (min 100) |
Check response headers X-RateLimit-Remaining and X-Request-Cost to monitor usage.