> ## 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.
# Get Wallet Trades
> Retrieve swap trades for a single wallet (GET or flat POST), or for multiple wallets in one batch request (POST), with pagination, token filtering, and enriched base/quote metadata.
### Query Details
#### Required Parameters
* `wallet` - Wallet address to query trades for (supports EVM and Solana addresses)
#### Optional Parameters
| Parameter | Type | Default | Description |
| -------------- | ------ | ------- | ------------------------------------------------------------------------------ |
| `tokenAddress` | string | - | Filter trades involving this token contract address |
| `blockchains` | string | - | Comma-separated list of blockchain IDs (e.g., `"ethereum,base,solana:solana"`) |
| `limit` | number | 50 | Number of trades per page (min: 1, max: 100) |
| `offset` | number | 0 | Offset for pagination |
| `order` | string | "desc" | Sort order by date: `"asc"` or `"desc"` |
| `from` | number | - | Start timestamp in milliseconds |
| `to` | number | - | End timestamp in milliseconds |
`POST /2/wallet/trades` accepts the same flat wallet body as `GET` query params. To fetch trades for **multiple wallets** in one call, use the batch array or `items` body (see [Batch requests](#batch-requests-multiple-wallets) below).
### Step-by-Step Tutorial and Video Walkthrough
* Check out the guide: [Here](https://docs.mobula.io/guides/how-to-track-wallet-swap-trades-using-mobula-api)
### Pagination
Pagination is offset-based, consistent with other V2 wallet endpoints (`/wallet/activity`, `/wallet/positions`).
* Use `offset` and `limit` to control which slice of results you receive
* `page` in the response is computed as `Math.floor(offset / limit) + 1`
The response includes a `pagination` object:
```json theme={null}
{
"pagination": {
"page": 1,
"offset": 0,
"limit": 50,
"pageEntries": 42
}
}
```
`pageEntries` indicates the actual number of trades returned (may be less than `limit` on the last page).
***
### Response Overview
Each item in `data[]` represents a consolidated swap trade:
| Field | Type | Description |
| -------------------------- | ------------ | -------------------------------------------------------------- |
| `id` | string | Unique trade identifier |
| `type` | string | Trade direction: `"buy"` or `"sell"` (relative to base token) |
| `operation` | string | Swap type: `"regular"`, `"mev"`, etc. |
| `baseTokenAmount` | number | Amount of base token traded (formatted with decimals) |
| `baseTokenAmountRaw` | string | Raw amount of base token in smallest units |
| `baseTokenAmountUSD` | number | USD value of the trade |
| `quoteTokenAmount` | number | Amount of quote token traded (formatted) |
| `quoteTokenAmountRaw` | string | Raw amount of quote token in smallest units |
| `quoteTokenAmountUSD` | number | USD value of the quote side |
| `baseTokenPriceUSD` | number | Base token price at trade time |
| `quoteTokenPriceUSD` | number | Quote token price at trade time |
| `date` | number | Trade timestamp in milliseconds |
| `blockchain` | string | Blockchain name (e.g., `"Ethereum"`, `"Solana"`) |
| `transactionHash` | string | Transaction hash |
| `marketAddress` | string | Pool/market contract address |
| `transactionSenderAddress` | string | Wallet that sent the transaction |
| `swapSenderAddress` | string | Address that initiated the swap (may differ for AA wallets) |
| `swapRecipient` | string\|null | Swap beneficiary address (important for Account Abstraction) |
| `baseToken` | object\|null | `{ address, name, symbol, logo, decimals }` |
| `quoteToken` | object\|null | `{ address, name, symbol, logo, decimals }` |
| `labels` | string\[] | Wallet labels (e.g., `"sniper"`, `"insider"`, `"smart-money"`) |
| `platform` | object\|null | `{ id, name, logo }` - Trading platform/aggregator |
| `totalFeesUSD` | number\|null | Total fees paid in USD |
| `gasFeesUSD` | number\|null | Gas fees in USD |
| `platformFeesUSD` | number\|null | Platform/aggregator fees in USD |
| `mevFeesUSD` | number\|null | MEV/priority fees in USD |
| `preBalanceBaseToken` | string\|null | Pre-swap raw balance of base token |
| `preBalanceQuoteToken` | string\|null | Pre-swap raw balance of quote token |
| `postBalanceBaseToken` | string\|null | Post-swap raw balance of base token |
| `postBalanceQuoteToken` | string\|null | Post-swap raw balance of quote token |
***
### Usage Examples
#### Basic: single wallet
```bash theme={null}
curl -X GET "https://api.mobula.io/api/2/wallet/trades?wallet=0xaF88370abD82EC6943cdB3D4ec7b764B92c35B43" \
-H "Authorization: YOUR_API_KEY"
```
#### Solana wallet with limit
```bash theme={null}
curl -X GET "https://api.mobula.io/api/2/wallet/trades?wallet=4tqMHgB8jjbTgefVfqtVFYzyfQz2LQ8T3E922ePmt6kZ&limit=10" \
-H "Authorization: YOUR_API_KEY"
```
#### Filter by token and blockchains
```bash theme={null}
curl -X GET "https://api.mobula.io/api/2/wallet/trades?wallet=0xaF88370abD82EC6943cdB3D4ec7b764B92c35B43&tokenAddress=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2&blockchains=ethereum&limit=20" \
-H "Authorization: YOUR_API_KEY"
```
#### Pagination with offset
```bash theme={null}
curl -X GET "https://api.mobula.io/api/2/wallet/trades?wallet=0xaF88370abD82EC6943cdB3D4ec7b764B92c35B43&limit=10&offset=10&order=desc" \
-H "Authorization: YOUR_API_KEY"
```
#### Date range filter
```bash theme={null}
curl -X GET "https://api.mobula.io/api/2/wallet/trades?wallet=0xaF88370abD82EC6943cdB3D4ec7b764B92c35B43&from=1704067200000&to=1735689600000&order=asc" \
-H "Authorization: YOUR_API_KEY"
```
***
### POST body request (single wallet)
```bash theme={null}
curl -X POST "https://api.mobula.io/api/2/wallet/trades" \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "wallet": "4tqMHgB8jjbTgefVfqtVFYzyfQz2LQ8T3E922ePmt6kZ", "limit": 5 }'
```
***
### Batch requests (multiple wallets)
To fetch trades for several wallets in a single call, send a **`POST`** to `/2/wallet/trades` with a JSON **array** of items (or an object with an `items` array). Each item targets one wallet and accepts the same filters as the GET query (`tokenAddress`, `chainIds`, `limit`, `offset`, `order`, `from`, `to`).
* **Maximum 10 wallets** per request.
* Each wallet is processed independently: if one wallet fails, the others still return — that wallet's entry contains an `error` field instead of `data`.
| Item field | Type | Default | Description |
| -------------- | --------- | ------- | ------------------------------------------------------------------------ |
| `wallet` | string | - | **Required.** Wallet address (EVM or Solana) |
| `tokenAddress` | string | - | Filter trades involving this token contract address |
| `chainIds` | string\[] | - | Array of chain IDs (e.g., `["evm:1","evm:8453"]`). All chains if omitted |
| `limit` | number | 50 | Number of trades per page (min: 1, max: 100) |
| `offset` | number | 0 | Offset for pagination |
| `order` | string | "desc" | Sort order by date: `"asc"` or `"desc"` |
| `from` | number | - | Start timestamp in milliseconds |
| `to` | number | - | End timestamp in milliseconds |
```bash theme={null}
curl -X POST "https://api.mobula.io/api/2/wallet/trades" \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '[
{ "wallet": "0xaF88370abD82EC6943cdB3D4ec7b764B92c35B43", "limit": 20 },
{ "wallet": "4tqMHgB8jjbTgefVfqtVFYzyfQz2LQ8T3E922ePmt6kZ", "chainIds": ["solana:solana"], "limit": 10 }
]'
```
The batch response wraps a per-wallet `payload` array:
```json theme={null}
{
"payload": [
{
"wallet": "0xaF88370abD82EC6943cdB3D4ec7b764B92c35B43",
"data": [ /* trades, same shape as the GET response */ ],
"pagination": { "page": 1, "offset": 0, "limit": 20, "pageEntries": 20 }
},
{
"wallet": "4tqMHgB8jjbTgefVfqtVFYzyfQz2LQ8T3E922ePmt6kZ",
"data": [ /* … */ ],
"pagination": { "page": 1, "offset": 0, "limit": 10, "pageEntries": 10 }
}
],
"hostname": "…"
}
```
***
### Sample Response
```json theme={null}
{
"data": [
{
"id": "22039719729",
"operation": "regular",
"type": "sell",
"baseTokenAmount": 10289426.248783976,
"baseTokenAmountRaw": "10289426248783975872330870",
"baseTokenAmountUSD": 1953.59,
"quoteTokenAmount": 0.6675364467,
"quoteTokenAmountRaw": "667536446729330304",
"quoteTokenAmountUSD": 1953.59,
"preBalanceBaseToken": null,
"preBalanceQuoteToken": null,
"postBalanceBaseToken": null,
"postBalanceQuoteToken": null,
"date": 1768290275000,
"swapSenderAddress": "0xd2b37ade14708bf18904047b1e31f8166d39612b",
"transactionSenderAddress": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
"swapRecipient": "0xd2b37ade14708bf18904047b1e31f8166d39612b",
"blockchain": "Ethereum",
"transactionHash": "0x07dcb584b301f2b8d445e504ff64f27ea8d8a9c9d58329145a0813c9d0f18dd0",
"marketAddress": "0x79786aa97633871f4ea737b3099cf911598d65b7",
"baseTokenPriceUSD": 0.00018986,
"quoteTokenPriceUSD": 3124.15,
"labels": [],
"baseToken": {
"address": "0x9f277edfc463ebaa3d2a6274b01177697e910391",
"name": "Miniature Woolly Mammoth",
"symbol": "WOOLLY",
"logo": "https://metadata.mobula.io/assets/logos/evm_1_0x9f277edfc463ebaa3d2a6274b01177697e910391.webp",
"decimals": 18
},
"quoteToken": {
"address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
"name": "Ethereum",
"symbol": "ETH",
"logo": "https://metadata.mobula.io/assets/logos/evm_1_0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2.webp",
"decimals": 18
},
"platform": null,
"totalFeesUSD": 0.058,
"gasFeesUSD": 0.058,
"platformFeesUSD": 0,
"mevFeesUSD": 0
}
],
"pagination": {
"page": 1,
"offset": 0,
"limit": 50,
"pageEntries": 1
}
}
```
The `tokenAddress` filter uses the raw contract address. Make sure to pass the correct address for the blockchain you're querying (e.g., WETH on Ethereum, SOL on Solana).
Use `order=asc` with `from` to efficiently scan trade history forward from a specific point in time.
## OpenAPI
````yaml get /2/wallet/trades
openapi: 3.0.0
info:
version: 1.0.0
title: Mobula API
description: >-
Documentation of the Mobula API
**Demo API**: The default server (demo-api.mobula.io) is a demo API with
rate limits.
For production use, please use api.mobula.io with an API key from
https://admin.mobula.io
servers:
- url: https://demo-api.mobula.io/api/
description: Demo API (rate limited, for testing only)
- url: https://api.mobula.io/api/
description: Production API (requires API key)
security: []
tags:
- name: V2 - Token
description: Token details, price, security, ATH, and holder data
- name: V2 - Market Data
description: Market details, OHLCV history, and lighthouse metrics
- name: V2 - Trades
description: Token trades, enriched trades, and trade filters
- name: V2 - Wallet
description: Wallet positions, activity, trades, analysis, and labels
- name: V2 - Assets
description: Cross-chain asset details and price history
- name: V2 - Swap
description: Swap quoting and execution
- name: V2 - Perps
description: Perpetual futures quoting, execution, and positions
- name: V2 - Bridge
description: Cross-chain bridge quoting and intent status (Alpha Preview)
- name: V2 - DeFi
description: Bonding pools and pulse data
- name: V2 - Search
description: Universal fast search
- name: V2 - Blockchains
description: System metadata and chain listings
- name: V1 - Market Data
description: Market prices, history, sparklines, pairs, and multi-data
- name: V1 - Wallet
description: Wallet portfolio, transactions, history, and NFTs
- name: V1 - Token
description: First buyers
- name: V1 - Trades
description: Market trades by pair
- name: V1 - Metadata
description: Token metadata, categories, trendings, and news
- name: V1 - Assets
description: List all assets
- name: V1 - Search
description: Search for assets, tokens, and pairs
- name: V1 - DeFi
description: Bonding pool pulse data
- name: V1 - Blockchains
description: Blockchain listings, pairs, and stats
- name: V1 - Webhooks
description: Webhook management
- name: V1 - Feed
description: Custom feed creation
paths:
/2/wallet/trades:
get:
tags:
- V2 - Wallet
summary: Get wallet trades
description: >-
Retrieve swap trades for one or more wallets. Supports filtering by
token, blockchain, and date range. Returns paginated results with
base/quote token metadata, fees breakdown, and wallet labels.
parameters:
- schema:
type: string
description: Wallet address
required: true
description: Wallet address
name: wallet
in: query
- schema:
type: string
description: Filter trades involving this token contract address
required: false
description: Filter trades involving this token contract address
name: tokenAddress
in: query
- schema:
type: string
description: >-
Comma-separated list of chain IDs (e.g.,
"evm:1,evm:8453,solana:solana"). If omitted, all chains.
required: false
description: >-
Comma-separated list of chain IDs (e.g.,
"evm:1,evm:8453,solana:solana"). If omitted, all chains.
name: chainIds
in: query
- schema:
type: number
minimum: 1
maximum: 100
description: 'Number of trades per page (1-100, default: 50)'
required: false
description: 'Number of trades per page (1-100, default: 50)'
name: limit
in: query
- schema:
type: number
nullable: true
minimum: 0
description: 'Offset for pagination (default: 0)'
required: false
description: 'Offset for pagination (default: 0)'
name: offset
in: query
- schema:
type: string
enum:
- asc
- desc
description: 'Sort order: asc or desc (default: desc)'
required: false
description: 'Sort order: asc or desc (default: desc)'
name: order
in: query
- schema:
type: number
nullable: true
description: Start timestamp in milliseconds
required: false
description: Start timestamp in milliseconds
name: from
in: query
- schema:
type: number
nullable: true
description: End timestamp in milliseconds
required: false
description: End timestamp in milliseconds
name: to
in: query
responses:
'200':
description: Wallet trades response
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
operation:
type: string
enum:
- regular
- mev
- mev_sandwiched
- deposit
- withdrawal
- bond
type:
type: string
enum:
- buy
- sell
- deposit
- withdrawal
baseTokenAmount:
type: number
baseTokenAmountRaw:
type: string
baseTokenAmountUSD:
type: number
quoteTokenAmount:
type: number
quoteTokenAmountRaw:
type: string
quoteTokenAmountUSD:
type: number
preBalanceBaseToken:
type: string
nullable: true
preBalanceQuoteToken:
type: string
nullable: true
postBalanceBaseToken:
type: string
nullable: true
postBalanceQuoteToken:
type: string
nullable: true
date:
type: number
swapSenderAddress:
type: string
transactionSenderAddress:
type: string
swapRecipient:
type: string
nullable: true
blockchain:
type: string
transactionHash:
type: string
marketAddress:
type: string
marketAddresses:
type: array
items:
type: string
baseTokenPriceUSD:
type: number
quoteTokenPriceUSD:
type: number
baseTokenMarketCapUSD:
type: number
nullable: true
quoteTokenMarketCapUSD:
type: number
nullable: true
labels:
type: array
nullable: true
items:
type: string
default: []
walletMetadata:
type: object
nullable: true
properties:
entityName:
type: string
nullable: true
entityLogo:
type: string
nullable: true
entityLabels:
type: array
items:
type: string
entityType:
type: string
nullable: true
entityDescription:
type: string
nullable: true
entityTwitter:
type: string
nullable: true
entityWebsite:
type: string
nullable: true
entityGithub:
type: string
nullable: true
entityDiscord:
type: string
nullable: true
entityTelegram:
type: string
nullable: true
extra:
type: object
additionalProperties:
nullable: true
required:
- entityName
- entityLogo
- entityLabels
- entityType
- entityDescription
- entityTwitter
- entityWebsite
- entityGithub
- entityDiscord
- entityTelegram
baseToken:
type: object
nullable: true
properties:
address:
type: string
name:
type: string
nullable: true
symbol:
type: string
nullable: true
logo:
type: string
nullable: true
decimals:
type: number
required:
- address
- name
- symbol
- logo
- decimals
quoteToken:
type: object
nullable: true
properties:
address:
type: string
name:
type: string
nullable: true
symbol:
type: string
nullable: true
logo:
type: string
nullable: true
decimals:
type: number
required:
- address
- name
- symbol
- logo
- decimals
platform:
type: object
nullable: true
properties:
id:
type: string
name:
type: string
logo:
type: string
nullable: true
required:
- id
- name
- logo
totalFeesUSD:
type: number
nullable: true
gasFeesUSD:
type: number
nullable: true
platformFeesUSD:
type: number
nullable: true
mevFeesUSD:
type: number
nullable: true
required:
- id
- operation
- type
- baseTokenAmount
- baseTokenAmountRaw
- baseTokenAmountUSD
- quoteTokenAmount
- quoteTokenAmountRaw
- quoteTokenAmountUSD
- date
- swapSenderAddress
- transactionSenderAddress
- blockchain
- transactionHash
- marketAddress
- baseTokenPriceUSD
- quoteTokenPriceUSD
pagination:
type: object
properties:
page:
type: number
offset:
type: number
limit:
type: number
pageEntries:
type: number
required:
- page
- offset
- limit
- pageEntries
required:
- data
- pagination
````