Tracking token transfers
token_transfersGet 25 token transfers (per page) for a specific token based on the sort order. Default: the last 24 hours, largest transfers first (orderBy "amount", "desc").
Direction rules (fromAddress = the sender, toAddress = the receiver):
"Transfers of X", "X's transfers", "track X", and "what is X doing" do not name a direction. For these, make two calls with the same address: one with fromAddress, one with toAddress. Sort both by amount. Each call then shows different transactions: the largest sent and the largest received.
Use only fromAddress when the user asks what X sent (outflows, withdrawals, "sent to", "moved to an exchange").
Use only toAddress when the user asks what X received (inflows, deposits, "where did X get").
Do not put the same address in fromAddress and toAddress of one call. The filters combine with AND, so the call returns only transfers from the wallet to itself (usually none).
If the user names no wallet, do not add an address filter.
NOTE: This tool does not support native tokens (so11111111111111111111111111111111111111112, 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee).
Columns returned:
Time: Timestamp when the transfer occurred (block_timestamp: ISO 8601 format)
From Label: Source address label (from_address_label: sender of tokens)
To Label: Destination address label (to_address_label: receiver of tokens)
From Address: Raw source address (from_address: hex address)
To Address: Raw destination address (to_address: hex address)
Amount: Quantity of tokens transferred (transfer_amount: numeric)
Value USD: USD value of the transfer at time of transaction (transfer_value_usd: currency formatted)
Type: Transfer category (transaction_type: DEX, CEX, transfer, etc.)
Tx Hash: Blockchain transaction hash for verification (transaction_hash)
Sorting Options (all fields support "asc"/"desc"): Available for sorting: timestamp, amount - amount (default): largest transfers first. Use it when the user asks about size, value, dollar amounts, the largest transfers, or whales. - timestamp: latest transfers first. Use it only when the user asks for the latest transfers or for a time order.
Examples:
# Basic request (largest transfers in the last 24 hours, the default sort)
{ "chain": "ethereum", "tokenAddress": "0xa0b86a33e6b6c4b3add000b44b3a1234567890ab", "dateRange": {"from": "24H_AGO", "to": "NOW"}, "orderBy": "amount", "order_by_direction": "desc" }
# Latest transfers first (only when the user asks for the latest)
```
{
"chain": "ethereum",
"tokenAddress": "0xa0b86a33e6b6c4b3add000b44b3a1234567890ab",
"dateRange": {"from": "24H_AGO", "to": "NOW"},
"orderBy": "timestamp",
"order_by_direction": "desc"
}
```
# Smart money only filter (largest transfers first)
```
{
"chain": "ethereum",
"tokenAddress": "0xa0b86a33e6b6c4b3add000b44b3a1234567890ab",
"dateRange": {"from": "7D_AGO", "to": "NOW"},
"transferOriginCategories": ["all_transfers"],
"onlySmartTradersAndFunds": true,
"orderBy": "amount",
"order_by_direction": "desc"
}
```
# Filter by DEX only with minimum transfer value (USD)
```
{
"chain": "ethereum",
"tokenAddress": "0xa0b86a33e6b6c4b3add000b44b3a1234567890ab",
"dateRange": {"from": "24H_AGO", "to": "NOW"},
"transferOriginCategories": ["dex"],
"transferValueUsd": {"from": 1000}
}
```
# One wallet, no direction named: make two calls, both sorted by amount
# Call 1: what the wallet sent
```
{
"chain": "base",
"tokenAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
"dateRange": {"from": "7D_AGO", "to": "NOW"},
"fromAddress": "0x2b060b9c89B8aD04e5E1fD40F1f327e41DD32c72",
"orderBy": "amount",
"order_by_direction": "desc"
}
```
# Call 2: what the wallet received
```
{
"chain": "base",
"tokenAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
"dateRange": {"from": "7D_AGO", "to": "NOW"},
"toAddress": "0x2b060b9c89B8aD04e5E1fD40F1f327e41DD32c72",
"orderBy": "amount",
"order_by_direction": "desc"
}
```Available Filters:
Address Filters:
fromAddress (str or list[str], optional): the wallet(s) that SENT the tokens Example: "0x2b060b9c89B8aD04e5E1fD40F1f327e41DD32c72" Example: ["0xaddr1", "0xaddr2"]
toAddress (str or list[str], optional): the wallet(s) that RECEIVED the tokens See the Direction rules at the top.
Transfer Origin Categories:
transferOriginCategories (list[str]): List of transfer types to include Possible values: ['dex', 'cex', 'non_exchange_transfers', 'all_transfers'] Default: ['all_transfers'] Examples:
['dex'] - only DEX transfers
['cex'] - only CEX transfers
['dex', 'cex'] - both DEX and CEX
['non_exchange_transfers'] - only non-exchange transfers
['all_transfers'] - all types (default)
Smart Money Filter:
onlySmartTradersAndFunds (bool): Only show smart money transfers (default: false) When true, filters to show only transfers involving profitable addresses
Numeric Range Filter:
transferValueUsd (object, optional): Filter by USD value of transfer Format: {"from": X, "to": Y} or {"from": X} or {"to": Y}
Specify only
fromfor minimum bound (no maximum)Specify only
tofor maximum bound (no minimum)Specify both for a bounded range Example: {"from": 1000} - only transfers worth at least $1,000 USD Example: {"to": 50000} - only transfers up to $50,000 USD Example: {"from": 1000, "to": 50000} - transfers between $1,000 and $50,000 USD Note: This filters by the USD value of the transfer at time of transaction
Notes: - Use fromAddress/toAddress for a specific wallet (see Direction rules) - Use transferOriginCategories to control which transfer origins are included - Smart Money filter shows only transfers involving profitable addresses (definition of Smart Money) - transferValueUsd filters by USD value at time of transaction
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |