Skip to main content
GET
/
2
/
token
/
trades
Get token trades
curl --request GET \
  --url https://demo-api.mobula.io/api/2/token/trades
{
  "data": [
    {
      "id": "<string>",
      "operation": "<string>",
      "type": "<string>",
      "baseTokenAmount": 123,
      "baseTokenAmountRaw": "<string>",
      "baseTokenAmountUSD": 123,
      "quoteTokenAmount": 123,
      "quoteTokenAmountRaw": "<string>",
      "quoteTokenAmountUSD": 123,
      "date": 123,
      "swapSenderAddress": "<string>",
      "transactionSenderAddress": "<string>",
      "blockchain": "<string>",
      "transactionHash": "<string>",
      "marketAddress": "<string>",
      "baseTokenPriceUSD": 123,
      "quoteTokenPriceUSD": 123,
      "preBalanceBaseToken": "<string>",
      "preBalanceQuoteToken": "<string>",
      "postBalanceBaseToken": "<string>",
      "postBalanceQuoteToken": "<string>",
      "swapRecipient": "<string>",
      "marketAddresses": [
        "<string>"
      ],
      "labels": [],
      "walletMetadata": {
        "entityName": "<string>",
        "entityLogo": "<string>",
        "entityLabels": [
          "<string>"
        ],
        "entityType": "<string>",
        "entityDescription": "<string>",
        "entityTwitter": "<string>",
        "entityWebsite": "<string>",
        "entityGithub": "<string>",
        "entityDiscord": "<string>",
        "entityTelegram": "<string>"
      },
      "baseToken": {
        "address": "<string>",
        "name": "<string>",
        "symbol": "<string>",
        "logo": "<string>",
        "decimals": 123
      },
      "quoteToken": {
        "address": "<string>",
        "name": "<string>",
        "symbol": "<string>",
        "logo": "<string>",
        "decimals": 123
      },
      "platform": {
        "id": "<string>",
        "name": "<string>",
        "logo": "<string>"
      },
      "totalFeesUSD": 123,
      "gasFeesUSD": 123,
      "platformFeesUSD": 123,
      "mevFeesUSD": 123
    }
  ]
}

​
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
typeNoFilter by trade direction: buy or sell
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
  • 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): 
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...",
      "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

Query Parameters

​
blockchain
string

Blockchain name or chain ID

​
address
string

Token or pool contract address

​
offset
number | null

Offset for pagination (default: 0)

​
limit
number | null

Number of trades per page (default: 10)

​
sortOrder
enum<string>
required

Sort order: asc or desc (default: desc)

Available options:
asc,
desc
​
label
enum<string>

Filter by wallet label (e.g., sniper, insider, bundler)

Available options:
sniper,
insider,
bundler,
proTrader,
smartTrader,
freshTrader,
dev,
liquidityPool
​
swapTypes

Comma-separated swap types to filter (e.g., "REGULAR,MEV")

​
transactionSenderAddresses

Comma-separated wallet addresses to filter (max 25)

​
maxAmountUSD
number | null

Maximum trade amount in USD

​
minAmountUSD
number | null

Minimum trade amount in USD

​
fromDate

Start date filter (timestamp or ISO string)

​
toDate

End date filter (timestamp or ISO string)

Response

200 - application/json

Token trades response

​
data
object[]
required