Get Enriched Token Trades

Retrieve enriched trades for a specific pool, returning the same swap-enriched schema used by WebSocket multi-event streams — including full pairData (market details), baseTokenData & quoteTokenData (token details), and position (PnL).

GET /2/token/trades-enriched

Get enriched token trades

cURL

curl --request GET \
  --url https://demo-api.mobula.io/api/2/token/trades-enriched

200

{
  "data": [
    {
      "addressToken0": "<string>",
      "addressToken1": "<string>",
      "amount0": 123,
      "amount1": 123,
      "rawAmount0": "<string>",
      "rawAmount1": "<string>",
      "swapType": "<string>",
      "poolType": "<string>",
      "poolAddress": "<string>",
      "swapSenderAddress": "<string>",
      "transactionHash": "<string>",
      "transactionSenderAddress": "<string>",
      "transactionIndex": 123,
      "transactionSwapsCount": 123,
      "swapIndex": 123,
      "ratio": 123,
      "chainId": "<string>",
      "timestamp": "<string>",
      "blockHash": "<string>",
      "logIndex": 123,
      "rawPreBalance0": "<string>",
      "rawPreBalance1": "<string>",
      "rawPostBalance0": "<string>",
      "rawPostBalance1": "<string>",
      "gasFeesUSD": 123,
      "platformFeesUSD": 123,
      "mevFeesUSD": 123,
      "totalFeesUSD": 123,
      "gasFeesNativeRaw": "<string>",
      "platformFeesNativeRaw": "<string>",
      "mevFeesNativeRaw": "<string>",
      "totalFeesNativeRaw": "<string>",
      "baseToken": "<string>",
      "quoteToken": "<string>",
      "pair": "<string>",
      "date": "<string>",
      "tokenPrice": 123,
      "tokenPriceVs": 123,
      "priceNative": 123,
      "tokenAmount": 123,
      "tokenAmountVs": 123,
      "type": "<string>",
      "operation": "<string>",
      "blockchain": "<string>",
      "hash": "<string>",
      "sender": "<string>",
      "tokenAmountRaw": "<string>",
      "tokenAmountRawVs": "<string>",
      "amountUSD": 123,
      "priceUSDToken0": 123,
      "priceUSDToken1": 123,
      "swapRecipient": "<string>",
      "blockHeight": null,
      "platform": "<string>",
      "tokenAmountUSD": 123,
      "marketCapUSD": 123,
      "marketCapDilutedUSD": 123,
      "totalSupply": 123,
      "circulatingSupply": 123,
      "labels": [
        "<string>"
      ],
      "walletMetadata": {
        "entityName": "<string>",
        "entityLogo": "<string>",
        "entityLabels": [
          "<string>"
        ],
        "entityType": "<string>",
        "entityDescription": "<string>",
        "entityTwitter": "<string>",
        "entityWebsite": "<string>",
        "entityGithub": "<string>",
        "entityDiscord": "<string>",
        "entityTelegram": "<string>"
      },
      "platformMetadata": {
        "id": "<string>",
        "name": "<string>",
        "logo": "<string>"
      }
    }
  ]
}

WebSocket Stream Parity: This endpoint returns the exact same schema as the Multi-Event WebSocket Stream swap-enriched event. Use it to backfill historical trades so that your UI renders identically whether the data came from the live stream or from this REST endpoint.

Query Details

Query enriched trades by pool/pair address (same access pattern as Get Token Trades, but with the enriched WebSocket schema).

Parameter	Required	Description
blockchain	Yes	Blockchain name or chain ID (e.g., "base", "ethereum", 56)
address	Yes	Pool/pair contract address
limit	No	Number of trades per page (default: 10)
offset	No	Offset for pagination (default: 0)
sortOrder	No	Sort order: asc or desc (default: desc)
label	No	Filter by wallet label (e.g., proTrader, smartTrader, freshTrader, dev)
swapTypes	No	Comma-separated swap types to filter (e.g., "REGULAR,MEV")
type	No	Filter by trade direction: buy or sell
transactionSenderAddresses	No	Comma-separated wallet addresses to filter (max 25)
minAmountUSD	No	Minimum trade amount in USD
maxAmountUSD	No	Maximum trade amount in USD
fromDate	No	Start date filter (ISO 8601 or Unix timestamp)
toDate	No	End date filter (ISO 8601 or Unix timestamp)

---

Response Overview

The response data[] array contains trades in the swap-enriched stream format — the same schema produced by the WebSocket multi-event stream. All field names are camelCase.

Core Trade Fields

Field	Type	Description
addressToken0	string	Token 0 address
addressToken1	string	Token 1 address
amount0	number	Absolute formatted amount of token 0
amount1	number	Absolute formatted amount of token 1
amountUSD	number?	USD value of the trade
rawAmount0	string	Raw (smallest unit) amount of token 0
rawAmount1	string	Raw (smallest unit) amount of token 1
priceUSDToken0	number?	USD price of token 0 at execution
priceUSDToken1	number?	USD price of token 1 at execution
swapType	string	Swap type (e.g., REGULAR, MEV, DEPOSIT, WITHDRAWAL)
poolType	string | null	Pool type (e.g., uniswap-v2, uniswap-v3, raydium-clmm)
poolAddress	string	Pool/pair address
swapSenderAddress	string | null	Swap sender address
transactionHash	string	Transaction hash
transactionSenderAddress	string	Transaction sender (tx.from)
transactionIndex	number | null	Transaction index in block (null for historical)
transactionSwapsCount	number	Number of swaps in this transaction
swapRecipient	string | null	Actual beneficiary of the swap (important for AA wallets)
swapIndex	number	Index of this swap within the transaction
ratio	number	Swap ratio
chainId	string	Chain ID (e.g., evm:8453, solana:solana)
timestamp	string	Trade timestamp in milliseconds (as string)
blockHeight	number | null	Block height (null for historical REST)
blockHash	string | null	Block hash (null for historical REST)
logIndex	number | null	Log index (null for historical REST)
platform	string | null	Trading platform/aggregator identifier

Balance Fields

Field	Type	Description
rawPreBalance0	string | null	Pre-swap raw balance of token 0
rawPreBalance1	string | null	Pre-swap raw balance of token 1
rawPostBalance0	string | null	Post-swap raw balance of token 0
rawPostBalance1	string | null	Post-swap raw balance of token 1

Fee Fields

Field	Type	Description
gasFeesUSD	number	Gas fees in USD
platformFeesUSD	number	Platform fees in USD
mevFeesUSD	number	MEV fees in USD
totalFeesUSD	number	Total fees in USD
gasFeesNativeRaw	string	Gas fees in native token (raw)
platformFeesNativeRaw	string	Platform fees in native token (raw)
mevFeesNativeRaw	string	MEV fees in native token (raw)
totalFeesNativeRaw	string	Total fees in native token (raw)

Derived View Fields

These fields are computed using the same deriveSwapView() logic as the WebSocket stream:

Field	Type	Description
baseToken	string	Base token address
quoteToken	string	Quote token address
pair	string	Pool/pair address
date	string	Trade date (ISO 8601)
tokenPrice	number	Base token price in USD
tokenPriceVs	number	Quote token price in USD
priceNative	number	Base token price in quote token terms
tokenAmount	number	Formatted base token amount traded
tokenAmountVs	number	Formatted quote token amount traded
tokenAmountUSD	number?	USD value of the trade
type	string	Trade direction: buy or sell
operation	string	Operation type (e.g., regular, deposit, withdrawal)
blockchain	string	Blockchain name
hash	string	Transaction hash
sender	string	Transaction sender address
tokenAmountRaw	string	Raw base token amount (smallest units)
tokenAmountRawVs	string	Raw quote token amount (smallest units)

Enrichment Data

Field	Type	Description
baseTokenData	object?	Full TokenDetailsOutput for the base token — see below
quoteTokenData	object?	Full TokenDetailsOutput for the quote token — see below
pairData	object?	Full MarketDetailsOutput for the pool — see below
marketCapUSD	number?	Base token market cap (convenience shortcut from baseTokenData)
marketCapDilutedUSD	number?	Base token diluted market cap
totalSupply	number?	Base token total supply
circulatingSupply	number?	Base token circulating supply

Position (PnL)

When available, the position object contains the swap recipient’s aggregated PnL data for this token:

Field	Type	Description
position.balance	number	Estimated current token balance
position.rawBalance	string	Raw balance (smallest units)
position.amountUSD	number	Current position value in USD
position.nativeBalanceRaw	string	Native token balance (raw)
position.nativeBalance	number	Native token balance
position.buys	number	Total buy count
position.sells	number	Total sell count
position.volumeBuyToken	number	Total tokens bought
position.volumeSellToken	number	Total tokens sold
position.volumeBuy	number	Total buy volume in USD
position.volumeSell	number	Total sell volume in USD
position.avgBuyPriceUSD	number	Average buy price in USD
position.avgSellPriceUSD	number	Average sell price in USD
position.realizedPnlUSD	number	Realized PnL in USD
position.unrealizedPnlUSD	number	Unrealized PnL in USD
position.totalPnlUSD	number	Total PnL (realized + unrealized)
position.realizedPnlPercent	number	Realized PnL as percentage
position.unrealizedPnlPercent	number	Unrealized PnL as percentage

REST-Only Enrichments

These fields are only available in the REST endpoint (not in the WebSocket stream):

Field	Type	Description
labels	string[]?	Wallet labels (e.g., smartTrader, sniper, dev, bundler)
walletMetadata	object | null	Entity info (name, logo, labels, type) from known wallets database
platformMetadata	object | null	Platform details: id, name, logo

Fields only available in real-time stream: The following fields exist in the WebSocket stream but are not stored in the database and will be absent from REST responses: rawPostBalanceRecipient0, rawPostBalanceRecipient1, rawPostBalanceNativeSender, rawPostBalanceNativeRecipient, miniBlockSlot. Additionally, blockHeight, blockHash, logIndex, and transactionIndex are returned as null.

pairData (MarketDetailsOutput)

Full market/pair details including token metadata, price changes, volumes, trade counts, holder stats, socials, and security flags. Key fields:

Field	Type	Description
token0 / token1	object	Token metadata (address, chainId, symbol, name, decimals, id, priceUSD, logo, totalSupply, circulatingSupply, marketCapUSD, marketCapDilutedUSD, deployer, createdAt, athUSD, atlUSD, athDate, atlDate, bonded, bondingPercentage, …)
baseToken / quoteToken	string	Base and quote token addresses
liquidityUSD	number | null	Pool liquidity in USD
priceUSD	number | null	Current token price in USD
priceToken	number | null	Price in quote token terms
priceChange{T}Percentage	number | null	Price change % for T = 1min, 5min, 1h, 4h, 6h, 12h, 24h
volume{T}USD	number | null	Volume in USD for T = 1min, 5min, 15min, 1h, 4h, 6h, 12h, 24h
volumeBuy{T}USD / volumeSell{T}USD	number | null	Buy/sell volume split for each timeframe
trades{T}	number | null	Trade count for each timeframe
buys{T} / sells{T}	number | null	Buy/sell count for each timeframe
buyers{T} / sellers{T} / traders{T}	number | null	Unique buyer/seller/trader count for each timeframe
feesPaid{T}USD	number | null	Fees paid in USD for each timeframe
holdersCount	number | null	Number of token holders
top10HoldingsPercentage	number | null	% held by top 10 wallets
devHoldingsPercentage	number | null	% held by deployer
insidersHoldingsPercentage	number | null	% held by insiders
bundlersHoldingsPercentage	number | null	% held by bundlers
snipersHoldingsPercentage	number | null	% held by snipers
exchange	object | null	{ name, logo } — DEX exchange info
type	string | null	Pool type (e.g., univ2, univ3)
security	object | null	Security flags (honeypot, mintable, etc.)

baseTokenData / quoteTokenData (TokenDetailsOutput)

Full token details for the base and quote tokens respectively. Key fields:

Field	Type	Description
address	string	Token contract address
chainId	string	Chain ID (e.g., evm:1)
symbol / name	string	Token symbol and name
decimals	number	Token decimals
priceUSD	number | null	Current price in USD
totalSupply / circulatingSupply	number | null	Supply metrics
marketCapUSD / marketCapDilutedUSD	number | null	Market cap metrics
liquidityUSD	number | null	Liquidity in USD
priceChange{T}Percentage	number | null	Price change % for each timeframe
volume{T}USD	number | null	Volume in USD for each timeframe
holdersCount	number | null	Number of holders
deployer	string | null	Deployer address
security	object | null	Security flags

walletMetadata

Field	Type	Description
entityName	string | null	Entity name (e.g., “Binance 14”)
entityLogo	string | null	Entity logo URL
entityLabels	string[]	Entity labels
entityType	string | null	Entity type (e.g., “cex”)
entityDescription	string | null	Entity description
entityTwitter	string | null	Entity Twitter handle
entityWebsite	string | null	Entity website
entityGithub	string | null	Entity GitHub
entityDiscord	string | null	Entity Discord
entityTelegram	string | null	Entity Telegram

platformMetadata

Field	Type	Description
id	string	Platform identifier (e.g., "photon")
name	string	Display name (e.g., "Photon")
logo	string | null	Platform logo URL

The pairData, baseTokenData, and quoteTokenData objects are fetched once per request (since all trades belong to the same pool) and attached to every trade in the response. This makes the response self-contained — no additional API calls are needed to render a full trade row.

The type filter (buy/sell) is applied after fetching from the database, so using it with small limit values may return fewer results than expected. Increase limit if you need a specific number of buys or sells.

---

Usage Examples

Fetch latest enriched trades for a pool:

curl -X GET "https://api.mobula.io/api/2/token/trades-enriched?blockchain=ethereum&address=0x0d4a11d5eeaac28ec3f61d100daf4d40471f1852&limit=10"

Fetch enriched trades with filters (POST):

curl -X POST "https://api.mobula.io/api/2/token/trades-enriched" \
  -H "Content-Type: application/json" \
  -d '{
    "blockchain": "ethereum",
    "address": "0x0d4a11d5eeaac28ec3f61d100daf4d40471f1852",
    "limit": 50,
    "minAmountUSD": 1000,
    "type": "buy",
    "sortOrder": "desc"
  }'

Historical backfill with pagination:

# Page 1
curl "https://api.mobula.io/api/2/token/trades-enriched?blockchain=bsc&address=0x16b9a82891338f9bA80E2D6970FddA79D1eb0daE&limit=100&offset=0&sortOrder=asc&fromDate=2026-03-01T00:00:00Z"

# Page 2
curl "https://api.mobula.io/api/2/token/trades-enriched?blockchain=bsc&address=0x16b9a82891338f9bA80E2D6970FddA79D1eb0daE&limit=100&offset=100&sortOrder=asc&fromDate=2026-03-01T00:00:00Z"

Special Labels

The label parameter accepts the following values (these are the actual enum string values to pass):

• proTrader: Trades from known professional trading platforms
• smartTrader: Trades from wallets identified as smart traders in the last 7 days
• freshTrader: Trades from newly funded wallets (within last 24 hours)
• dev: Trades from token deployer addresses
• sniper: Trades from sniper wallets
• insider: Trades from insider wallets
• bundler: Trades from bundler wallets
• Custom labels created via the wallet labels API

Comparison with Token Trades

Feature	/token/trades	/token/trades-enriched
Schema	Custom REST format	Stream swap-enriched format
pairData	Not included	Full MarketDetailsOutput
baseTokenData	Not included	Full TokenDetailsOutput
quoteTokenData	Not included	Full TokenDetailsOutput
position (PnL)	Not included	Full PnL per swap recipient
labels	Not included	Wallet labels per trade
Use case	General trade queries	Historical backfill for live feeds
Field naming	camelCase	camelCase (matches WS stream)

Query Parameters

blockchain · string

Blockchain name or chain ID

address · string

Pool/pair 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 · string string[]

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

type · enum<string>

Filter by trade direction: "buy" or "sell"

Available options: buy, sell

transactionSenderAddresses · string string[]

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 · integer string any

Start date filter (timestamp or ISO string)

toDate · integer string any

End date filter (timestamp or ISO string)

Response

200 - application/json

Enriched token trades response

data · object[] · required

Show child attributes