Skip to main content

​
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
ParameterRequiredDescription
blockchainYesBlockchain identifier (e.g., “base”, “ethereum”, “bsc”)
addressYesToken or pool address depending on mode
modeNoQuery mode: pair (default) or asset
limitNoNumber of results per page (default: 10, max: 1000)
offsetNoOffset for pagination (default: 0)
sortOrderNoSort order: asc or desc (default: desc)
labelNoFilter by wallet label (e.g., PRO_TRADER, SMART_TRADER, FRESH_TRADER, DEV)
swapTypesNoArray of swap types to filter (e.g., REGULAR, DEPOSIT, WITHDRAWAL)
transactionSenderAddressesNoArray of transaction sender addresses to filter (max: 25)
minAmountUSDNoMinimum trade amount in USD
maxAmountUSDNoMaximum trade amount in USD
fromDateNoStart date for trade filtering (ISO 8601 or Unix timestamp)
toDateNoEnd date for trade filtering (ISO 8601 or Unix timestamp)

​
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
  • 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)
  • 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): 
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): 
curl -X GET "https://api.mobula.io/api/2/token/trades?blockchain=base&address=0x4200000000000000000000000000000000000006&mode=asset&limit=20"
Query trades with filters: 
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

{
  "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...",
      "baseTokenPriceUSD": 11.95,
      "quoteTokenPriceUSD": 1.0,
      "labels": ["smart-money", "smart-trader"],
      "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