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

```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"
  }'
```