> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobula.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating from Wallet Trades V1 to V2

> Guide to upgrade from /api/1/wallet/trades to /api/2/wallet/trades

## 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 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`):

```json theme={null}
// 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```javascript theme={null}
// 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:

```bash theme={null}
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"
  }'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.