Get DEX trades for a specific token.
**Modes:**
- `onchain_tokens` (default): Analyze on-chain tokens by contract address
- `perps`: Analyze Hyperliquid perpetual futures by symbol (chain auto-set to "hyperliquid")
**NOTE:** In onchain_tokens mode, only ETH is supported among native tokens. For other native tokens (SOL, BTC, BNB, etc.), use perps mode instead.
Args:
request: TokenDexTradesRequest containing parameters, pagination settings, and optional sorting
Returns:
DEX trading activity as markdown. Returns empty string if no trades found.
**Common Columns (all modes):**
- **Time**: Timestamp when the trade occurred (datetime: YYYY-MM-DD HH:MM:SS)
- **Token**: Symbol of the token/perpetual contract
- **Price USD**: Price per token in USD at time of trade (currency formatted)
- **Value USD**: Total USD value of the trade/position change (currency formatted)
- **Trader**: Nansen label or name of the trading address
- **Tx Hash**: Blockchain transaction hash for verification
**onchain_tokens mode:**
- **Action**: Trade direction - BUY or SELL from perspective of the token
- **Token Amount**: Quantity of the target token traded (numeric)
- **Traded Amount**: Quantity of the other token in the swap (numeric)
- **Traded Token**: Symbol of the token traded against (e.g., WETH, USDC)
**perps mode:**
- **Side**: Position direction - Long or Short
- **Action**: Order action - Add, Reduce, Open, Close
- **Size**: Quantity of the perpetual contract (numeric)
Sorting Options (all fields support "asc"/"desc"):
Available for sorting: timestamp, valueUsd, amount, priceUsd
Examples:
# On-chain tokens (default mode)
```
{
"mode": "onchain_tokens",
"chain": "ethereum",
"tokenAddress": "0xa0b86a33e6b6c4b3add000b44b3a1234567890ab",
"dateRange": {"from": "24H_AGO", "to": "NOW"}
}
```
# Hyperliquid perpetual futures
```
{
"mode": "perps",
"tokenAddress": "PENGU",
"dateRange": {"from": "7D_AGO", "to": "NOW"},
"action": "Open",
"side": "Long"
}
```
# Find biggest trades by USD value (whale watching)
```
{
"mode": "onchain_tokens",
"chain": "ethereum",
"tokenAddress": "0xa0b86a33e6b6c4b3add000b44b3a1234567890ab",
"dateRange": {"from": "7D_AGO", "to": "NOW"},
"order_by": "valueUsd",
"order_by_direction": "desc"
}
```
# Find who bought the dip vs who bought the top (price analysis)
```
{
"chain": "ethereum",
"tokenAddress": "0xa0b86a33e6b6c4b3add000b44b3a1234567890ab",
"dateRange": {"from": "30D_AGO", "to": "NOW"},
"order_by": "priceUsd",
"order_by_direction": "asc"
}
```
Connector