> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobula.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Token Trades
> Retrieve trades for a specific token or pool with pagination, filtering by swap types, addresses, dates, and amounts.
### Query Details
You can query trades either by pool address or by asset address:
* **mode: pair** - Query trades for a specific pool/pair address
* **mode: asset** - Query trades across top pools for a token asset
| Parameter | Required | Description |
| ---------------------------- | -------- | ---------------------------------------------------------------------------------- |
| `blockchain` | Yes | Blockchain identifier (e.g., "base", "ethereum", "bsc") |
| `address` | Yes | Token or pool address depending on mode |
| `mode` | No | Query mode: `pair` (default) or `asset` |
| `limit` | No | Number of results per page (default: 10, max: 1000) |
| `offset` | No | Offset for pagination (default: 0) |
| `sortOrder` | No | Sort order: `asc` or `desc` (default: `desc`) |
| `label` | No | Filter by wallet label (e.g., `PRO_TRADER`, `SMART_TRADER`, `FRESH_TRADER`, `DEV`) |
| `swapTypes` | No | Array of swap types to filter (e.g., `REGULAR`, `DEPOSIT`, `WITHDRAWAL`) |
| `transactionSenderAddresses` | No | Array of transaction sender addresses to filter (max: 25) |
| `minAmountUSD` | No | Minimum trade amount in USD |
| `maxAmountUSD` | No | Maximum trade amount in USD |
| `type` | No | Filter by trade direction: `buy` or `sell` |
| `fromDate` | No | Start date for trade filtering (ISO 8601 or Unix timestamp) |
| `toDate` | No | End date for trade filtering (ISO 8601 or Unix timestamp) |
### Step-by-Step Tutorial and Video Walkthrough
* Check out the guide: [Here](https://docs.mobula.io/guides/how-to-track-token-trades)
***
### Response Overview
Each item in `data[]` represents a single trade:
* **id**: Unique swap identifier
* **operation**: Swap operation type (regular, deposit, withdrawal)
* **type**: Trade type (`buy`, `sell`, `deposit`, or `withdrawal`)
* **baseTokenAmount**: Amount of base token traded (formatted)
* **baseTokenAmountRaw**: Amount of base token traded in smallest units
* **baseTokenAmountUSD**: USD value of base token traded
* **quoteTokenAmount**: Amount of quote token traded (formatted)
* **quoteTokenAmountRaw**: Amount of quote token traded in smallest units
* **quoteTokenAmountUSD**: USD value of quote token traded
* **date**: Trade timestamp in milliseconds
* **swapSenderAddress**: Address that executed the swap
* **transactionSenderAddress**: Transaction originator address (tx.from)
* **swapRecipient**: The actual beneficiary of the swap - the wallet that receives the output tokens. This is the most important address for accurate PnL tracking, especially for Account Abstraction (AA) scenarios where `transactionSenderAddress` may be a bundler, relayer, or smart contract wallet.
* **blockchain**: Blockchain name
* **transactionHash**: Transaction hash
* **marketAddress**: Pool/market address where trade occurred
* **marketAddresses**: Array of all market addresses involved in the trade (for multi-hop swaps)
* **preBalanceBaseToken**: Pre-swap balance of base token (raw string, nullable)
* **preBalanceQuoteToken**: Pre-swap balance of quote token (raw string, nullable)
* **postBalanceBaseToken**: Post-swap balance of base token (raw string, nullable)
* **postBalanceQuoteToken**: Post-swap balance of quote token (raw string, nullable)
* **baseTokenPriceUSD**: Base token price in USD at execution
* **quoteTokenPriceUSD**: Quote token price in USD at execution
* **labels**: Array of wallet labels (e.g., `smart-money`, `pro-trader`)
* **walletMetadata**: Enriched wallet metadata (entity name, logo, labels) from known wallets database. `null` if not available.
* **baseToken**: Minimal metadata for the base token (name, symbol, decimals, address, chainId, logo, priceUSD)
* **quoteToken**: Minimal metadata for the quote token (name, symbol, decimals, address, chainId, logo, priceUSD)
* **platform**: Trading platform/aggregator used for the trade (e.g., Photon, BullX, Axiom, GMGN, Trojan). Object with `id`, `name`, `logo` fields. `null` if not available.
* **totalFeesUSD**: Total fees paid in USD (sum of gas, platform, and MEV fees)
* **gasFeesUSD**: Gas fees paid in USD
* **platformFeesUSD**: Platform/aggregator fees paid in USD (e.g., Axiom, GMGN, Trojan)
* **mevFeesUSD**: MEV/priority fees paid in USD
The base token is determined by the baseQuote logic, which identifies the most relevant token in the pair.
**Account Abstraction (AA) Support**: The `swapRecipient` field is critical for accurate wallet tracking when users trade via bundlers, relayers, or smart contract wallets. In these cases, `transactionSenderAddress` may be an intermediary contract, while `swapRecipient` represents the actual user who receives the tokens. Always use `swapRecipient` when available for accurate PnL calculations.
When using `mode: asset`, trades are aggregated from the top 5 pools by liquidity for that token.
### Usage Examples
**Query trades for a specific pool (pair mode):**
```bash theme={null}
curl -X GET "https://api.mobula.io/api/2/token/trades?blockchain=base&address=0x4200000000000000000000000000000000000006&mode=pair&limit=10"
```
**Query trades for a token across all pools (asset mode):**
```bash theme={null}
curl -X GET "https://api.mobula.io/api/2/token/trades?blockchain=base&address=0x4200000000000000000000000000000000000006&mode=asset&limit=20"
```
**Query trades with filters:**
```bash theme={null}
curl -X POST "https://api.mobula.io/api/2/token/trades" \
-H "Content-Type: application/json" \
-d '{
"blockchain": "base",
"address": "0x4200000000000000000000000000000000000006",
"mode": "asset",
"limit": 50,
"minAmountUSD": 1000,
"label": "SMART_TRADER",
"swapTypes": ["REGULAR"]
}'
```
#### Sample Response
```json theme={null}
{
"data": [
{
"id": "123456789",
"operation": "regular",
"type": "buy",
"baseTokenAmount": 100.5,
"baseTokenAmountRaw": "100500000000000000000",
"baseTokenAmountUSD": 1200.5,
"quoteTokenAmount": 1200.5,
"quoteTokenAmountRaw": "1200500000",
"quoteTokenAmountUSD": 1200.5,
"date": 1699545600000,
"swapSenderAddress": "0xabc123...",
"transactionSenderAddress": "0xdef456...",
"swapRecipient": "0xabc123...",
"blockchain": "Base",
"transactionHash": "0x789abc...",
"marketAddress": "0x420000...",
"marketAddresses": ["0x420000..."],
"preBalanceBaseToken": "50000000000000000000",
"preBalanceQuoteToken": "2400000000",
"postBalanceBaseToken": "150500000000000000000",
"postBalanceQuoteToken": "1199500000",
"baseTokenPriceUSD": 11.95,
"quoteTokenPriceUSD": 1.0,
"labels": ["smart-money", "smart-trader"],
"walletMetadata": null,
"baseToken": {
"name": "Example Token",
"symbol": "EXT",
"decimals": 18,
"address": "0xToken...",
"chainId": "evm:8453",
"logo": "https://...",
"priceUSD": 11.95
},
"quoteToken": {
"name": "USD Coin",
"symbol": "USDC",
"decimals": 6,
"address": "0xQuote...",
"chainId": "evm:8453",
"logo": "https://...",
"priceUSD": 1.0
},
"platform": {
"id": "axiom",
"name": "Axiom",
"logo": "https://..."
},
"totalFeesUSD": 2.45,
"gasFeesUSD": 0.85,
"platformFeesUSD": 1.20,
"mevFeesUSD": 0.40
}
]
}
```
### Special Labels
The `label` parameter accepts the following values:
* **PRO\_TRADER**: Trades from known professional trading platforms
* **SMART\_TRADER**: Trades from wallets identified as smart traders in the last 7 days
* **FRESH\_TRADER**: Trades from newly funded wallets (within last 24 hours)
* **DEV**: Trades from token deployer addresses
* Custom labels created via the wallet labels API
## OpenAPI
````yaml get /2/token/trades
openapi: 3.0.0
info:
version: 1.0.0
title: Mobula API
description: >-
Documentation of the Mobula API
**Demo API**: The default server (demo-api.mobula.io) is a demo API with
rate limits.
For production use, please use api.mobula.io with an API key from
https://admin.mobula.io
servers:
- url: https://demo-api.mobula.io/api/
description: Demo API (rate limited, for testing only)
- url: https://api.mobula.io/api/
description: Production API (requires API key)
security: []
tags:
- name: V2 - Token
description: Token details, price, security, ATH, and holder data
- name: V2 - Market Data
description: Market details, OHLCV history, and lighthouse metrics
- name: V2 - Trades
description: Token trades, enriched trades, and trade filters
- name: V2 - Wallet
description: Wallet positions, activity, trades, analysis, and labels
- name: V2 - Assets
description: Cross-chain asset details and price history
- name: V2 - Swap
description: Swap quoting and execution
- name: V2 - Perps
description: Perpetual futures quoting, execution, and positions
- name: V2 - Bridge
description: Cross-chain bridge quoting and intent status (Alpha Preview)
- name: V2 - DeFi
description: Bonding pools and pulse data
- name: V2 - Search
description: Universal fast search
- name: V2 - Blockchains
description: System metadata and chain listings
- name: V1 - Market Data
description: Market prices, history, sparklines, pairs, and multi-data
- name: V1 - Wallet
description: Wallet portfolio, transactions, history, and NFTs
- name: V1 - Token
description: First buyers
- name: V1 - Trades
description: Market trades by pair
- name: V1 - Metadata
description: Token metadata, categories, trendings, and news
- name: V1 - Assets
description: List all assets
- name: V1 - Search
description: Search for assets, tokens, and pairs
- name: V1 - DeFi
description: Bonding pool pulse data
- name: V1 - Blockchains
description: Blockchain listings, pairs, and stats
- name: V1 - Webhooks
description: Webhook management
- name: V1 - Feed
description: Custom feed creation
paths:
/2/token/trades:
get:
tags:
- V2 - Trades
summary: Get token trades
description: >-
Retrieve trades for a specific token or pool with pagination, filtering
by swap types, addresses, dates, and amounts.
parameters:
- schema:
type: string
description: Blockchain chain ID (e.g., "evm:56", "solana:solana")
required: false
description: Blockchain chain ID (e.g., "evm:56", "solana:solana")
name: chainId
in: query
- schema:
type: string
description: Token or pool contract address
required: false
description: Token or pool contract address
name: address
in: query
- schema:
type: number
nullable: true
description: 'Offset for pagination (default: 0)'
required: false
description: 'Offset for pagination (default: 0)'
name: offset
in: query
- schema:
type: number
nullable: true
description: 'Number of trades per page (default: 10)'
required: false
description: 'Number of trades per page (default: 10)'
name: limit
in: query
- schema:
type: string
enum:
- asc
- desc
description: 'Sort order: asc or desc (default: desc)'
required: true
description: 'Sort order: asc or desc (default: desc)'
name: sortOrder
in: query
- schema:
type: string
enum:
- pair
- pool
- asset
description: >-
Query mode: "pair" (pool address), "asset" (token address).
Auto-detects if omitted.
required: true
description: >-
Query mode: "pair" (pool address), "asset" (token address).
Auto-detects if omitted.
name: mode
in: query
- schema:
type: string
enum:
- sniper
- insider
- bundler
- proTrader
- smartTrader
- freshTrader
- dev
- liquidityPool
- locker
description: Filter by wallet label (e.g., sniper, insider, bundler)
required: false
description: Filter by wallet label (e.g., sniper, insider, bundler)
name: label
in: query
- schema:
anyOf:
- type: string
- type: array
items:
type: string
description: Comma-separated swap types to filter (e.g., "REGULAR,MEV")
required: false
description: Comma-separated swap types to filter (e.g., "REGULAR,MEV")
name: swapTypes
in: query
- schema:
type: string
enum:
- buy
- sell
description: 'Filter by trade direction: "buy" or "sell"'
required: false
description: 'Filter by trade direction: "buy" or "sell"'
name: type
in: query
- schema:
anyOf:
- type: string
- type: array
items:
type: string
description: Comma-separated wallet addresses to filter (max 25)
required: false
description: Comma-separated wallet addresses to filter (max 25)
name: transactionSenderAddresses
in: query
- schema:
type: number
nullable: true
description: Maximum trade amount in USD
required: false
description: Maximum trade amount in USD
name: maxAmountUSD
in: query
- schema:
type: number
nullable: true
description: Minimum trade amount in USD
required: false
description: Minimum trade amount in USD
name: minAmountUSD
in: query
- schema:
anyOf:
- type: integer
nullable: true
- type: string
nullable: true
- nullable: true
description: Start date filter (timestamp or ISO string)
required: false
description: Start date filter (timestamp or ISO string)
name: fromDate
in: query
- schema:
anyOf:
- type: integer
nullable: true
- type: string
nullable: true
- nullable: true
description: End date filter (timestamp or ISO string)
required: false
description: End date filter (timestamp or ISO string)
name: toDate
in: query
responses:
'200':
description: Token trades response
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
operation:
type: string
enum:
- regular
- mev
- mev_sandwiched
- deposit
- withdrawal
- bond
type:
type: string
enum:
- buy
- sell
- deposit
- withdrawal
baseTokenAmount:
type: number
baseTokenAmountRaw:
type: string
baseTokenAmountUSD:
type: number
quoteTokenAmount:
type: number
quoteTokenAmountRaw:
type: string
quoteTokenAmountUSD:
type: number
preBalanceBaseToken:
type: string
nullable: true
preBalanceQuoteToken:
type: string
nullable: true
postBalanceBaseToken:
type: string
nullable: true
postBalanceQuoteToken:
type: string
nullable: true
date:
type: number
swapSenderAddress:
type: string
transactionSenderAddress:
type: string
swapRecipient:
type: string
nullable: true
blockchain:
type: string
transactionHash:
type: string
marketAddress:
type: string
marketAddresses:
type: array
items:
type: string
baseTokenPriceUSD:
type: number
quoteTokenPriceUSD:
type: number
baseTokenMarketCapUSD:
type: number
nullable: true
quoteTokenMarketCapUSD:
type: number
nullable: true
labels:
type: array
nullable: true
items:
type: string
default: []
walletMetadata:
type: object
nullable: true
properties:
entityName:
type: string
nullable: true
entityLogo:
type: string
nullable: true
entityLabels:
type: array
items:
type: string
entityType:
type: string
nullable: true
entityDescription:
type: string
nullable: true
entityTwitter:
type: string
nullable: true
entityWebsite:
type: string
nullable: true
entityGithub:
type: string
nullable: true
entityDiscord:
type: string
nullable: true
entityTelegram:
type: string
nullable: true
extra:
type: object
additionalProperties:
nullable: true
required:
- entityName
- entityLogo
- entityLabels
- entityType
- entityDescription
- entityTwitter
- entityWebsite
- entityGithub
- entityDiscord
- entityTelegram
baseToken:
type: object
nullable: true
properties:
address:
type: string
name:
type: string
nullable: true
symbol:
type: string
nullable: true
logo:
type: string
nullable: true
decimals:
type: number
required:
- address
- name
- symbol
- logo
- decimals
quoteToken:
type: object
nullable: true
properties:
address:
type: string
name:
type: string
nullable: true
symbol:
type: string
nullable: true
logo:
type: string
nullable: true
decimals:
type: number
required:
- address
- name
- symbol
- logo
- decimals
platform:
type: object
nullable: true
properties:
id:
type: string
name:
type: string
logo:
type: string
nullable: true
required:
- id
- name
- logo
totalFeesUSD:
type: number
nullable: true
gasFeesUSD:
type: number
nullable: true
platformFeesUSD:
type: number
nullable: true
mevFeesUSD:
type: number
nullable: true
required:
- id
- operation
- type
- baseTokenAmount
- baseTokenAmountRaw
- baseTokenAmountUSD
- quoteTokenAmount
- quoteTokenAmountRaw
- quoteTokenAmountUSD
- date
- swapSenderAddress
- transactionSenderAddress
- blockchain
- transactionHash
- marketAddress
- baseTokenPriceUSD
- quoteTokenPriceUSD
required:
- data
````