Historical Wallet Trades API

What you'll learn

• How to fetch historical trading data for specific wallets
• Query trade history with pagination
• Analyze trading patterns and metrics
• Track wallet trading activity over time

Introduction

The Historical Wallet Trades API enables you to retrieve and analyze past trading activity for any wallet address. This API is specifically designed for historical analysis of trading patterns, price movements, and trading behavior at the wallet level.

Access Requirements

• Valid API key (visit https://app.callstatic.com for tier information)
• Rate limits and data access vary by subscription tier

Authentication

All requests require a Bearer token in UUID format:

Authorization: Bearer your-api-key-here

Base URL

https://api.callstaticrpc.com/pumpfun/v1

Data Structure

The API returns detailed information about wallet trades:

Response Structure

{
    "success": true,
    "data": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "hash": "CcC5cC2cC8cC1cC7cC3cC9cC4cC6cC2cC8cC5cC1cC7cC4c",
            "timestamp": 1679616000000,
            "sol_amount": 1000000000,
            "token_amount": 50000000000,
            "token": "BbB3bB7bB2bB9bB4bB8bB1bBb5bB2bB6bB3bB9bB4bB",
            "price": 0.02,
            "dex": 1,
            "buyer": "AaA2aA5aA8aA4aA7aA1aA9aAa3aA6aA2aA8aA5aA1a",
            "virtual_sol_reserves": 100000000000,
            "virtual_token_reserves": 5000000000000,
            "real_sol_reserves": 98000000000,
            "real_token_reserves": 5100000000000,
            "is_buy": true
        }
    ],
    "has_more": false,
    "total": 1
}

TypeScript

import axios from 'axios';

interface Trade {
id: string;
hash: string;
timestamp: number;
sol_amount: number;
token_amount: number;
token: string;
price: number;
dex: 1 | 2; // 1 for PumpFun, 2 for Raydium
buyer: string;
virtual_sol_reserves: number;
virtual_token_reserves: number;
real_sol_reserves: number;
real_token_reserves: number;
is_buy: boolean;
}

interface PaginatedResponse {
success: boolean;
data: Trade[];
has_more: boolean;
total: number;
}

class WalletTradesClient {
private readonly baseUrl = 'https://api.callstaticrpc.com/pumpfun/v1';

    constructor(private readonly apiKey: string) {}

    async getWalletTrades(params: {
        wallet: string;
        limit?: number;
        offset?: number;
    }): Promise<PaginatedResponse> {
        const response = await axios.get(`${this.baseUrl}/historical/trades/byWallet`, {
            headers: {
                Authorization: `Bearer ${this.apiKey}`,
                'Content-Type': 'application/json'
            },
            params
        });

        return response.data;
    }

    async getAllWalletTrades(wallet: string): Promise<Trade[]> {
        let allTrades: Trade[] = [];
        let offset = 0;
        const limit = 100;

        while (true) {
            const response = await this.getWalletTrades({
                wallet,
                limit,
                offset
            });

            allTrades = [...allTrades, ...response.data];

            if (!response.has_more) break;
            offset += limit;
        }

        return allTrades;
    }

}

Python

from typing import List, Dict, Any
import requests

class WalletTradesClient:
    def __init__(self, api_key: str):
        self.base_url = "https://api.callstaticrpc.com/pumpfun/v1"
        self.api_key = api_key

    def get_wallet_trades(
        self,
        wallet: str,
        limit: int = None,
        offset: int = None
    ) -> Dict[str, Any]:
        response = requests.get(
            f"{self.base_url}/historical/trades/byWallet",
            headers={
                "Authorization": f"Bearer {self.api_key}",
                "Content-Type": "application/json"
            },
            params={
                "wallet": wallet,
                "limit": limit,
                "offset": offset
            }
        )
        response.raise_for_status()
        return response.json()

    def get_all_wallet_trades(self, wallet: str) -> List[Dict[str, Any]]:
        all_trades = []
        offset = 0
        limit = 100

        while True:
            response = self.get_wallet_trades(
                wallet=wallet,
                limit=limit,
                offset=offset
            )

            all_trades.extend(response["data"])

            if not response["has_more"]:
                break

            offset += limit

        return all_trades

Analysis Examples

Here are some common analysis scenarios using the wallet trades data:

TypeScript

async function analyzeWalletActivity(wallet: string) {
    const client = new WalletTradesClient('your-api-key');
    const trades = await client.getAllWalletTrades(wallet);
    
    return {
        totalTrades: trades.length,
        totalVolume: trades.reduce((sum, trade) => sum + trade.sol_amount, 0),
        tokenInteractions: new Set(trades.map(t => t.token)).size,
        tradingFrequency: {
            buys: trades.filter(t => t.is_buy).length,
            sells: trades.filter(t => !t.is_buy).length
        },
        dexUsage: {
            pumpfun: trades.filter(t => t.dex === 1).length,
            raydium: trades.filter(t => t.dex === 2).length
        }
    };
}

async function analyzeTokenPreferences(wallet: string) {
const client = new WalletTradesClient('your-api-key');
const trades = await client.getAllWalletTrades(wallet);

    const tokenStats = trades.reduce((acc, trade) => {
        if (!acc[trade.token]) {
            acc[trade.token] = {
                totalVolume: 0,
                tradeCount: 0,
                avgPrice: 0
            };
        }

        acc[trade.token].totalVolume += trade.sol_amount;
        acc[trade.token].tradeCount++;
        acc[trade.token].avgPrice =
            (acc[trade.token].avgPrice * (acc[trade.token].tradeCount - 1) + trade.price)
            / acc[trade.token].tradeCount;

        return acc;
    }, {});

    return tokenStats;

}

Error Handling

The API returns standard HTTP status codes:

Status Code	Description
200	Successful response
400	Bad request
401	Unauthorized - Invalid or missing bearer token
500	Internal server error

Best Practices

1. Implement Pagination

   • Use the limit and offset parameters for large datasets
   • Default to reasonable page sizes (e.g., 100 records)
   • Handle the has_more flag to determine if more data is available

2. Error Handling

try {
    const trades = await client.getWalletTrades({
        wallet: "AaA2...",
    });
} catch (error) {
    if (error.response?.status === 401) {
        console.error("Invalid API key");
    } else if (error.response?.status === 400) {
        console.error("Invalid parameters");
    }
}

3. Rate Limiting
   • Implement exponential backoff for retry logic
   • Monitor your API usage through the dashboard
   • Consider caching frequently accessed data

Next Steps

Now that you understand how to analyze wallet trading data, you can:

1. 📊 Build wallet activity dashboards
2. 🔍 Track trading patterns and preferences
3. 📈 Monitor trading frequency and volume
4. 🏷️ Analyze token interactions

Real-time Data

For real-time trade notifications, check out our WebSocket Streams API documentation.

Need Help?

For additional support:

• Email us at [email protected]
• Visit our Support Portal