Migrating from Wallet Trades V1 to V2

Why V2?

The V2 wallet trades endpoint is a complete rewrite that addresses several pain points from V1:

Lighter responses: baseToken/quoteToken return only essential metadata (address, name, symbol, logo, decimals) instead of 100+ fields with volumes, trending scores, and market stats
Built-in pagination: Response includes a pagination object with page, offset, limit, and pageEntries
Consistent naming: All fields use camelCase (no more mixed snake_case and camelCase)
Consistent params: Same parameter names as other V2 wallet endpoints (blockchains, from/to, order, offset/limit)
Token filtering: New tokenAddress parameter to filter trades involving a specific token
Date as timestamp: date returns millisecond timestamps (number) instead of ISO strings

Endpoint Changes

	V1	V2
GET	`/api/1/wallet/trades`	`/api/2/wallet/trades`
POST	Not supported	`/api/2/wallet/trades`

Parameter Mapping

V1 Parameter	V2 Parameter	Notes
`wallet`	`wallet`	Same
`wallets`	`wallets`	Same
`blockchains`	`blockchains`	Same (comma-separated)
`from`	`from`	Same (timestamp in ms)
`to`	`to`	Same (timestamp in ms)
`limit`	`limit`	Default changed: V1 varies, V2 = 50 (max 100)
`offset`	`offset`	Same
`order`	`order`	Same (`asc`/`desc`)
`page`	-	Removed (use `offset` instead, `page` is computed in response)
`asset`	`tokenAddress`	Now uses contract address instead of asset name
`cache`	-	Removed
`recheckContract`	-	Removed
`unlistedAssets`	-	Removed (V2 returns all trades)
`trades`	-	Removed
`stale`	-	Removed
`onlyAssets`	-	Removed (use `tokenAddress` instead)
`pagination`	-	Removed (always paginated in V2)

Response Field Mapping

Trade object

V1 Field	V2 Field	Notes
`side`	`type`	Same values: `"buy"` / `"sell"`
`swap_type`	`operation`	Lowercased (e.g., `"regular"` instead of `"REGULAR"`)
`amount_usd`	`baseTokenAmountUSD`	Same value
`amount_base`	`baseTokenAmount`	Same value
`amount_quote`	`quoteTokenAmount`	Same value
`amount_base_raw`	`baseTokenAmountRaw`	Same value
`amount_quote_raw`	`quoteTokenAmountRaw`	Same value
`base`	`baseToken.address`	Was a string, now inside object
`quote`	`quoteToken.address`	Was a string, now inside object
`base_token`	`baseToken`	Was 100+ fields, now only: address, name, symbol, logo, decimals
`pool_address`	`marketAddress`	Renamed
`transaction_hash`	`transactionHash`	camelCase
`transaction_sender_address`	`transactionSenderAddress`	camelCase
`date`	`date`	Changed: ISO string -> timestamp in ms
`chain_id`	`blockchain`	Changed: chain ID (e.g., `"evm:1"`) -> name (e.g., `"Ethereum"`)
`price_usd_token0` / `price_usd_token1`	`baseTokenPriceUSD` / `quoteTokenPriceUSD`	Oriented to base/quote instead of token0/token1
`raw_pre_balance0` / `raw_pre_balance1`	`preBalanceBaseToken` / `preBalanceQuoteToken`	Oriented to base/quote
`raw_post_balance0` / `raw_post_balance1`	`postBalanceBaseToken` / `postBalanceQuoteToken`	Oriented to base/quote
`labels`	`labels`	Same
`walletMetadata`	-	Removed in V2
-	`id`	New: unique trade identifier
-	`swapSenderAddress`	New: separate from transaction sender
-	`swapRecipient`	New: swap beneficiary (important for AA wallets)

Pagination

V1 returns all matching trades in a flat array. V2 always returns paginated results with offset-based pagination (same as /wallet/activity and /wallet/positions):

// V1
{ "data": [...trades] }

// V2
{
  "data": [...trades],
  "pagination": {
    "page": 1,
    "offset": 0,
    "limit": 50,
    "pageEntries": 42
  }
}

page is computed as Math.floor(offset / limit) + 1. Use offset and limit to paginate.

Migration Examples

Basic query

# V1
curl "https://api.mobula.io/api/1/wallet/trades?wallet=0xaF88...&limit=10&order=desc"

# V2 (same param names for these)
curl "https://api.mobula.io/api/2/wallet/trades?wallet=0xaF88...&limit=10&order=desc"

Filter by token

# V1 - filter by asset name
curl "https://api.mobula.io/api/1/wallet/trades?wallet=0xaF88...&asset=ETH"

# V2 - filter by contract address
curl "https://api.mobula.io/api/2/wallet/trades?wallet=0xaF88...&tokenAddress=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2&blockchains=ethereum"

Date range

# V1
curl "https://api.mobula.io/api/1/wallet/trades?wallet=0xaF88...&from=1704067200000&to=1735689600000"

# V2 (same param names)
curl "https://api.mobula.io/api/2/wallet/trades?wallet=0xaF88...&from=1704067200000&to=1735689600000"

Pagination with offset

# V1 (page-based)
curl "https://api.mobula.io/api/1/wallet/trades?wallet=0xaF88...&limit=10&page=2"

# V2 (offset-based, same as wallet/activity and wallet/positions)
curl "https://api.mobula.io/api/2/wallet/trades?wallet=0xaF88...&limit=10&offset=10"

Reading the response

// V1
const v1Trade = response.data[0];
const side = v1Trade.side;              // "buy" or "sell"
const symbol = v1Trade.base_token.symbol;
const date = new Date(v1Trade.date);    // ISO string
const chain = v1Trade.chain_id;         // "evm:1"

// V2
const v2Trade = response.data[0];
const side = v2Trade.type;              // "buy" or "sell"
const symbol = v2Trade.baseToken.symbol;
const date = new Date(v2Trade.date);    // timestamp in ms
const chain = v2Trade.blockchain;       // "Ethereum"

POST Support (V2 only)

V2 supports POST for complex queries:

curl -X POST "https://api.mobula.io/api/2/wallet/trades" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet": "0xaF88370abD82EC6943cdB3D4ec7b764B92c35B43",
    "wallets": "0xaF88370abD82EC6943cdB3D4ec7b764B92c35B43,4tqMHgB8jjbTgefVfqtVFYzyfQz2LQ8T3E922ePmt6kZ",
    "blockchains": "ethereum",
    "tokenAddress": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "limit": 20,
    "order": "desc"
  }'

How to Track Token First Buyers Across Solana, Ethereum, BNB, Base & More How to Track Token Markets Across Ethereum, Solana, BNB, Base & More

⌘I

Overview

Getting Started

Guides

Blog

Migrating from Wallet Trades V1 to V2

Why V2?

Endpoint Changes

Parameter Mapping

Response Field Mapping

Trade object

Migration Examples

Basic query

Filter by token

Date range

Reading the response

POST Support (V2 only)

​Why V2?

​Endpoint Changes

​Parameter Mapping

​Response Field Mapping

​Trade object

​Pagination

​Migration Examples

​Basic query

​Filter by token

​Date range

​Pagination with offset

​Reading the response

​POST Support (V2 only)

Why V2?

Endpoint Changes

Parameter Mapping

Response Field Mapping

Trade object

Pagination

Migration Examples

Basic query

Filter by token

Date range

Pagination with offset

Reading the response

POST Support (V2 only)