Wallet Balance History

Reconstruct the exact balance history of a wallet for either SOL, a tracked token symbol like USDC, or a caller-supplied SPL token mint using a caller-supplied Helius RPC URL.

This endpoint is intentionally consumer-funded: historical balance recovery is expensive, so the request must include the caller's own Helius RPC endpoint. Venum provides the search algorithm, pagination strategy, and normalized response.

You can get a free Helius RPC at helius.dev.

Requires API key.

GET /v1/history/balance

Use this endpoint when you want the full result as one JSON payload.

Request:

GET /v1/history/balance?walletAddress=<pubkey>&heliusRpcUrl=<urlencoded>&assetMint=SOL
x-api-key: YOUR_API_KEY

Query parameters:

Field	Type	Description
walletAddress	string	Base58 Solana wallet address
heliusRpcUrl	string	Full HTTPS Helius RPC URL including API key
assetMint	string	Optional. SOL, a tracked token symbol like USDC, or a base58 SPL mint address. Defaults to SOL.

Example:

curl 'https://api.venum.dev/v1/history/balance?walletAddress=EbUNi6setNdX7a89j4i1nVF9Cnw6puSFJk7Fjrnnxfe2&heliusRpcUrl=https%3A%2F%2Fmainnet.helius-rpc.com%2F%3Fapi-key%3DYOUR_HELIUS_KEY&assetMint=SOL' \
  -H 'x-api-key: YOUR_API_KEY'

Tracked token symbols are also accepted:

curl 'https://api.venum.dev/v1/history/balance?walletAddress=EbUNi6setNdX7a89j4i1nVF9Cnw6puSFJk7Fjrnnxfe2&heliusRpcUrl=https%3A%2F%2Fmainnet.helius-rpc.com%2F%3Fapi-key%3DYOUR_HELIUS_KEY&assetMint=USDC' \
  -H 'x-api-key: YOUR_API_KEY'

See GET /v1/tokens for the current list of supported tracked token symbols.

Response:

{
  "walletAddress": "EbUNi6setNdX7a89j4i1nVF9Cnw6puSFJk7Fjrnnxfe2",
  "assetMint": "SOL",
  "points": [
    {
      "signature": "4edti9pg4E2Ak4rqJJxKrdWaM9wRVWEoWpXUJ3DmjwxsTT4G958Z3qXv7xVeeoF48p3mozfj2M8CsxVeCDp5poTx",
      "slot": 290348419,
      "transactionIndex": 123,
      "blockTime": 1726578206,
      "assetMint": "SOL",
      "decimals": 9,
      "amountRaw": "400000000",
      "uiAmount": 0.4,
      "failed": false
    }
  ],
  "stats": {
    "rpcPosts": 61,
    "enumeratedSignatures": 5010,
    "points": 5010,
    "elapsedMs": 3302
  }
}

Shared Types

Point object

Field	Type	Description
signature	string	Transaction signature
slot	number	Solana slot
transactionIndex	number	Transaction index within block
blockTime	number | null	Unix timestamp in seconds
assetMint	string	SOL or the resolved SPL mint requested
decimals	number	Asset decimals (9 for SOL)
amountRaw	string	Post-transaction balance in raw base units
uiAmount	number	Post-transaction balance in human-readable units
failed	boolean	Whether the transaction failed

Stats object

Field	Type	Description
rpcPosts	number	Raw JSON-RPC POSTs sent to the supplied Helius endpoint
enumeratedSignatures	number	Number of wallet-touching signatures discovered
points	number	Number of balance points returned
elapsedMs	number	End-to-end runtime in milliseconds

Errors

Status	Description
400	Invalid wallet address, Helius URL, or assetMint value
401	Missing or invalid API key
429	Rate limit exceeded
502	Upstream Helius RPC error or rate limit

Notes

• This endpoint reconstructs history for the exact wallet address provided.
• assetMint: "SOL" returns SOL balance history.
• Tracked token symbols like USDC are resolved to their canonical mint.
• Any other valid base58 mint returns SPL token balance history for token accounts owned by that wallet that appear in the fetched transaction set.
• Supported tracked symbols are listed in GET /v1/tokens.
• It uses Helius getTransactionsForAddress, not a generic Solana RPC flow.
• The requester's Helius key determines upstream rate limits and billable RPC usage.
• rpcPosts is surfaced because historical balance reconstruction cost is a meaningful part of the query.
• The SSE companion lives at GET /v1/stream/balance-history and is documented on the Streams page.