GET /v1/history/balance

Reconstruct the exact balance history of a wallet for either SOL 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.

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 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'

Response

200 OK

{
  "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
  }
}

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 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 request body, wallet address, or Helius URL
401	Missing or invalid API key
429	Rate limit exceeded
502	Upstream Helius RPC error or rate limit

Auth

Requires API key.

Notes

• This endpoint reconstructs history for the exact wallet address provided.
• assetMint: "SOL" returns SOL balance history.
• Any other valid base58 mint returns SPL token balance history for token accounts owned by that wallet that appear in the fetched transaction set.
• 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.