Cambrian Wallet Token Balance History API

By Cambrian Network solana

GET /api/v1/solana/wallet-balance-history

Wallet Token Balance History

Returns paginated list of balance changes for a specified wallet address, providing complete audit trail of portfolio changes with transaction details, pre/post balances, and timing information. Essential for portfolio tracking and compliance monitoring.

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://opabinia.cambrian.network/api/v1/solana/wallet-balance-history

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

Query Parameters

Parameter Type Required Default Description
wallet_address String Yes - Solana wallet address (base58 format, 32-44 characters)
token_address String Yes - Filter by specific token address (base58 format)
after_time Integer Yes - Unix timestamp - start time for data range
before_time Integer Yes - Unix timestamp - end time for data range
limit Integer No 100 Limit the number of results (1-1000)
offset Integer No 0 Offset the results, allows you to skip a number of rows before starting to return rows (0-100000)
order_asc Array No - List of column names to order by in ascending order
order_desc Array No - List of column names to order by in descending order

Response Field Descriptions

Response Field Type Description
txHash String Transaction hash (signature)
slot Number Solana slot number where the transaction occurred
blockTime Number Unix timestamp of the block
blockHumanTime String Human-readable timestamp in ISO format
tokenAddress String Token mint address (44-character base58)
tokenSymbol String Token symbol (e.g., SOL)
tokenDecimals Number Number of decimal places for the token
preBalance Number Token balance before the transaction (raw units)
postBalance Number Token balance after the transaction (raw units)
changeAmount Number Change in balance (postBalance - preBalance, raw units)
uiPreBalance Number Pre-transaction balance in human-readable format
uiPostBalance Number Post-transaction balance in human-readable format
uiChangeAmount Number Balance change in human-readable format

Examples

1. Basic Wallet Balance History Query

This example demonstrates retrieving SOL balance history for a specific wallet over a 24-hour period.

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

Response:

[
  {
    "columns": [
      {
        "name": "txHash",
        "type": "FixedString(88)"
      },
      {
        "name": "slot",
        "type": "UInt64"
      },
      {
        "name": "blockTime",
        "type": "UInt32"
      },
      {
        "name": "blockHumanTime",
        "type": "String"
      },
      {
        "name": "tokenAddress",
        "type": "FixedString(44)"
      },
      {
        "name": "tokenSymbol",
        "type": "String"
      },
      {
        "name": "tokenDecimals",
        "type": "UInt8"
      },
      {
        "name": "preBalance",
        "type": "UInt64"
      },
      {
        "name": "postBalance",
        "type": "UInt64"
      },
      {
        "name": "changeAmount",
        "type": "Int64"
      },
      {
        "name": "uiPreBalance",
        "type": "Float64"
      },
      {
        "name": "uiPostBalance",
        "type": "Float64"
      },
      {
        "name": "uiChangeAmount",
        "type": "Float64"
      }
    ],
    "data": [
      [
        "5ka8cDRSyuk2htLLyzU8yRZEJ2Nu7XANEaqJD8qK9i53WPC7UbEHdiBLCh99QEQj44g51VaJnXeDxcjemGyG4XWH",
        311111849,
        1735702200,
        "2025-01-01T03:30:00Z",
        "So11111111111111111111111111111111111111112",
        "SOL",
        9,
        41949517781,
        41978232196,
        28714415,
        41.949517781,
        41.978232196,
        0.028714415
      ],
      [
        "4BHFZZahgc28MbLNHhbv4TEBLqNjhb2HG51cPp9qSPPPrXRh4d24Ne8cdNEwC92KtoP5cHoLYL7XDxWjhP1tMX9q",
        311111849,
        1735702200,
        "2025-01-01T03:30:00Z",
        "So11111111111111111111111111111111111111112",
        "SOL",
        9,
        41914786696,
        41949517781,
        34731085,
        41.914786696,
        41.949517781,
        0.034731085
      ],
      [
        "mizx16g3DfdpzWzwmUR3LjWLh9175xM1aLH4nSmsgzzA1ADBqUpGiED8FheEv3YsPy3hhq8zxpYKpr3efJdSwCq",
        311187140,
        1735732800,
        "2025-01-01T12:00:00Z",
        "So11111111111111111111111111111111111111112",
        "SOL",
        9,
        42030430752,
        41955631794,
        -74798958,
        42.030430752,
        41.955631794,
        -0.074798958
      ],
      [
        "4D2vmKXg5bbEjDEKQb4ofUXacvvzz8qeR3bP83UEXcWM9cqqBHdGRKx9qYpouKGrgKXenK4Dux675otSR4wT1dfu",
        311107452,
        1735700400,
        "2025-01-01T03:00:00Z",
        "So11111111111111111111111111111111111111112",
        "SOL",
        9,
        41912731005,
        41945464581,
        32733576,
        41.912731005,
        41.945464581,
        0.032733576
      ],
      [
        "4sCotkN5Vq1XcEvEi2J4hTugGWhm6Q1LB5k2LhEgYQxHht7u95HLcAZVDL9vbbKwT47UDPGhU4a5eVwWHzZcg9BY",
        311107452,
        1735700400,
        "2025-01-01T03:00:00Z",
        "So11111111111111111111111111111111111111112",
        "SOL",
        9,
        41972880805,
        41914786696,
        -58094109,
        41.972880805,
        41.914786696,
        -0.058094109
      ]
    ],
    "rows": 5
  }
]

The response shows 5 balance change records for the specified wallet's SOL token between January 1, 2025 00:00:00 and 23:59:59. Each record includes the transaction hash, timing information, and detailed before/after balance states, allowing for complete transaction-level audit trails.

2. Paginated Results with Ordering

This example demonstrates retrieving balance history with custom ordering and pagination.

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

Response:

[
  {
    "columns": [
      {
        "name": "txHash",
        "type": "FixedString(88)"
      },
      {
        "name": "slot",
        "type": "UInt64"
      },
      {
        "name": "blockTime",
        "type": "UInt32"
      },
      {
        "name": "blockHumanTime",
        "type": "String"
      },
      {
        "name": "tokenAddress",
        "type": "FixedString(44)"
      },
      {
        "name": "tokenSymbol",
        "type": "String"
      },
      {
        "name": "tokenDecimals",
        "type": "UInt8"
      },
      {
        "name": "preBalance",
        "type": "UInt64"
      },
      {
        "name": "postBalance",
        "type": "UInt64"
      },
      {
        "name": "changeAmount",
        "type": "Int64"
      },
      {
        "name": "uiPreBalance",
        "type": "Float64"
      },
      {
        "name": "uiPostBalance",
        "type": "Float64"
      },
      {
        "name": "uiChangeAmount",
        "type": "Float64"
      }
    ],
    "data": [
      [
        "5ka8cDRSyuk2htLLyzU8yRZEJ2Nu7XANEaqJD8qK9i53WPC7UbEHdiBLCh99QEQj44g51VaJnXeDxcjemGyG4XWH",
        311111849,
        1735702200,
        "2025-01-01T03:30:00Z",
        "So11111111111111111111111111111111111111112",
        "SOL",
        9,
        41949517781,
        41978232196,
        28714415,
        41.949517781,
        41.978232196,
        0.028714415
      ]
    ],
    "rows": 1
    // ... additional rows omitted for brevity
  }
]

The response returns balance history ordered by block time in descending order (most recent first), with pagination support for processing large result sets.

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://deep42.cambrian.network/api/v1/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://deep42.cambrian.network/api/v1/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–5 automatically.

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

Related Endpoints

  • /api/v1/solana/holder-token-balances - Returns token balances in USD for a specific user wallet, sorted by balance descending
  • /api/v1/solana/token-details - Get detailed information about a specific token including metadata and statistics
  • /api/v1/solana/token-details-multi - Get detailed information about multiple tokens in a single request
  • /api/v1/solana/token-mint-burn-transactions - Track minting and burning transactions for specific tokens
  • /api/v1/solana/ohlcv/token - Get OHLCV (price) data for tokens over time