Skip to main content

​
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

V1V2
GET/api/1/wallet/trades/api/2/wallet/trades
POSTNot supported/api/2/wallet/trades

​
Parameter Mapping

V1 ParameterV2 ParameterNotes
walletwalletSame
walletswalletsSame
blockchainsblockchainsSame (comma-separated)
fromfromSame (timestamp in ms)
totoSame (timestamp in ms)
limitlimitDefault changed: V1 varies, V2 = 50 (max 100)
offsetoffsetSame
orderorderSame (asc/desc)
page-Removed (use offset instead, page is computed in response)
assettokenAddressNow 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 FieldV2 FieldNotes
sidetypeSame values: "buy" / "sell"
swap_typeoperationLowercased (e.g., "regular" instead of "REGULAR")
amount_usdbaseTokenAmountUSDSame value
amount_basebaseTokenAmountSame value
amount_quotequoteTokenAmountSame value
amount_base_rawbaseTokenAmountRawSame value
amount_quote_rawquoteTokenAmountRawSame value
basebaseToken.addressWas a string, now inside object
quotequoteToken.addressWas a string, now inside object
base_tokenbaseTokenWas 100+ fields, now only: address, name, symbol, logo, decimals
pool_addressmarketAddressRenamed
transaction_hashtransactionHashcamelCase
transaction_sender_addresstransactionSenderAddresscamelCase
datedateChanged: ISO string -> timestamp in ms
chain_idblockchainChanged: chain ID (e.g., "evm:1") -> name (e.g., "Ethereum")
price_usd_token0 / price_usd_token1baseTokenPriceUSD / quoteTokenPriceUSDOriented to base/quote instead of token0/token1
raw_pre_balance0 / raw_pre_balance1preBalanceBaseToken / preBalanceQuoteTokenOriented to base/quote
raw_post_balance0 / raw_post_balance1postBalanceBaseToken / postBalanceQuoteTokenOriented to base/quote
labelslabelsSame
walletMetadata-Removed in V2
-idNew: unique trade identifier
-swapSenderAddressNew: separate from transaction sender
-swapRecipientNew: 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"
  }'