Wallet Token Balance History

Overview

Returns a paginated list of balance changes for a specified Solana wallet address and token. Together, the records form a complete audit trail of portfolio changes, with transaction details, pre/post balances, and timing information for a given time range.

Business Value

• Portfolio Tracking: Track detailed balance changes over time for comprehensive wallet monitoring and analysis
• Compliance Monitoring: Provide complete audit trail of all token balance changes with transaction-level detail
• Transaction Analysis: Analyze balance impact of each transaction with before/after balance states
• Historical Analysis: Access complete historical balance data for research and backtesting purposes
• Risk Management: Monitor wallet activity patterns and balance fluctuations for risk assessment

Endpoint Details

URL:

https://api.cambrian.org/solana/wallet-balance-history

Method: GET
Authentication: Required via X-API-Key header

Query Parameters

Response Field Descriptions

Examples

1. Query Wallet Balance History for a Token Over a Time Range

Retrieve balance change history for a specific wallet's holdings of a specific token (SOL) within a defined Unix timestamp range, limited to 10 results.

curl -X GET "https://api.cambrian.org/solana/wallet-balance-history?wallet_address=DKxRinQQhKnZcfdaSnKov5v4ja95pEncjBYU8ajzVgsW&token_address=So11111111111111111111111111111111111111112&after_time=1735689600&before_time=1735776000&limit=10" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

[
  {
    "columns": [],
    "data": [],
    "rows": 0
  }
]

Result collections are limited to 10 items. In this case, no balance-change records were found for the specified wallet, token, and time range, so the response returns an empty column/data set with rows: 0.

x402 Payment Option

This endpoint supports pay-per-use access via the x402 payment protocol (v2): pay $0.05 USDC per request using blockchain micropayments. No API key required.

Quick Start (TypeScript)

npm install @x402/fetch @x402/evm viem

import { x402Client } from "@x402/core/client";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { wrapFetchWithPayment } from "@x402/fetch";
import { privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
const client = new x402Client();
client.register("eip155:*", new ExactEvmScheme(signer));

const fetchWithPayment = wrapFetchWithPayment(fetch, client);
const response = await fetchWithPayment(
  "https://x402.cambrian.org/solana/wallet-balance-history"
);
const data = await response.json();

Quick Start (Python)

pip install "x402[httpx]"

import asyncio, os
from eth_account import Account
from x402 import x402Client
from x402.http.clients import x402HttpxClient
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client

async def main():
    client = x402Client()
    account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
    register_exact_evm_client(client, EthAccountSigner(account))

    async with x402HttpxClient(client) as http:
        response = await http.get("https://x402.cambrian.org/solana/wallet-balance-history")
        print(response.json())

asyncio.run(main())

Payment Flow

1. Send a normal request to the endpoint (no API key needed)
2. Server returns 402 Payment Required with payment details
3. The x402 SDK automatically signs a payment authorization with your wallet
4. The SDK resubmits the request with the signed payment
5. Server verifies payment and returns the API response

The x402 SDK handles steps 2 to 5 automatically.

Network: Base (chain ID 8453) | Currency: USDC | Price: $0.05 per request