Skip to main content
POST
getHistoricalTokenAccountsByOwner
getHistoricalTokenAccountsByOwner is in Beta. Parameters, pricing, response formats, and data coverage may change.

Overview

getHistoricalTokenAccountsByOwner returns the SPL Token and Token-2022 accounts a wallet owned at a past slot, or immediately after a specific transaction in that slot. It’s a Helius-exclusive RPC method. Standard getTokenAccountsByOwner only returns current state. With jsonParsed encoding, token amounts use each mint’s decimals as of the requested position, so balances reflect what the wallet held at that point in time. History is available from slot 444,959,999 (September 7, 2026) onward, which is the state at the start of epoch 1030. getHistoricalTokenAccountsByOwner is available on mainnet for Business plans and above, and costs 0 credits per call during the beta period. Pricing is subject to change.

How it differs from getTokenAccountsByOwner

  • The mint or program filter is optional. With no filter, you get every token account the wallet owned. To narrow results, set either mint or programId in the configuration object (the third parameter), not both.
  • The second parameter is the query object that selects the position in history, not a mint or program filter.
  • result.value is an object with accounts and paginationKey, not an array.

Choose a position in history

The second parameter is a query object:
  • Omitted or {}: the latest indexed slot, capped at the requested commitment.
  • { "slot": 445000000 }: the end of slot 445,000,000.
  • { "slot": 445000000, "transactionIndex": 10 }: immediately after the transaction at index 10 in that slot executed.
See the Historical Accounts Guide for how positions work.

Example request

This request returns the wallet’s USDC token accounts at the end of slot 445,000,000:

Paginate through all token accounts

Results are ordered by mint, then by token account address. Each response returns value.accounts and value.paginationKey, a cursor in the form <mint>:<tokenAccount>. Pass it back in the next request until it’s null.
A page can be short, or even empty, and still include a paginationKey. Only a null paginationKey means you’ve reached the end.
Always pass an explicit slot when you paginate. If you omit it, each page reads the latest indexed slot, so pages can come from different points in time.

Read the response

Each entry in value.accounts has the token account’s pubkey and an account object. The account object has the same fields as getAccountInfo, plus lastUpdatedAt:
  • lastUpdatedAt.slot and lastUpdatedAt.transactionIndex identify the write that produced this state.
  • lastUpdatedAt.slot of 444,959,999 with a null transactionIndex means the token account hasn’t changed since history coverage began.
  • context.slot is the latest slot Helius had indexed when it served the request, not the slot you queried.

Errors

Historical Accounts Guide

How positions, coverage, and lastUpdatedAt work for historical account methods

getHistoricalAccountInfo

Read a single account at a past slot

getTransactionsForAddress

Find the slot and transactionIndex of the transactions you want to inspect

getTokenAccountsByOwnerV2

Paginate through a wallet’s current token accounts

Request Parameters

string
required
Base-58 encoded address of the wallet that owned the token accounts. Pass the owner wallet, not a token account.
number
Slot to read state at. Returns the account as of the end of this slot. The earliest supported slot is 444959999, the state at the start of epoch 1030. When omitted, reads the latest indexed slot, capped at the requested commitment.
number
Position of a transaction within the slot. Returns the account state immediately after that transaction executed, instead of at the end of the slot. Requires slot.
string
Return only token accounts for this mint. Can’t be combined with programId.
string
Return only token accounts owned by this token program. Can’t be combined with mint.
  • TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
  • TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb
string
default:"base64"
Encoding format for account data. With jsonParsed, token amounts use the mint’s decimals as of the requested position. base58 and binary are not supported.
  • base64
  • base64+zstd
  • jsonParsed
object
Return only a slice of each account’s data. Applies to base64 and base64+zstd encodings.
number
required
Byte offset from which to start reading.
number
required
Number of bytes to return.
number
default:"5000"
Maximum number of token accounts to return (1-5,000).
string
Cursor from the previous response’s paginationKey, in the form &lt;mint&gt;:&lt;tokenAccount&gt;. When you also set mint, the cursor’s mint must match it.
string
default:"finalized"
Commitment level. processed is not supported.
  • finalized
  • confirmed
number
The minimum slot that the request can be evaluated at.

Authorizations

api-key
string
query
required

Your Helius API key. You can get one for free in the dashboard.

Body

application/json
jsonrpc
enum<string>
default:2.0
required

The JSON-RPC protocol version.

Available options:
2.0
Example:

"2.0"

id
string
default:1
required

A unique identifier for the request.

Example:

"1"

method
enum<string>
default:getHistoricalTokenAccountsByOwner
required

The name of the RPC method to invoke.

Available options:
getHistoricalTokenAccountsByOwner
Example:

"getHistoricalTokenAccountsByOwner"

params
(string | Query · object | Configuration · object)[]
required

Array containing the owner wallet address, an optional query object that selects the position in history, and an optional configuration object.

Required array length: 1 - 3 elements

Base-58 encoded address of the wallet that owned the token accounts. Pass the owner wallet, not a token account.

Example:

"86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY"

Response

Successfully retrieved a page of historical token accounts.

jsonrpc
enum<string>

The JSON-RPC protocol version.

Available options:
2.0
Example:

"2.0"

id
string

Identifier matching the request.

Example:

"1"

result
object