Solana Historical Account API (Beta)

What is historical account state?

• Check a wallet’s token balances at a point in time, for audits, accounting, or tax reporting
• Debug a transaction by reading the accounts it touched right before and right after it executed
• Read a protocol’s accounts, such as pools, vaults, or oracles, at a past slot without replaying the ledger yourself

Which method should I use?

Availability and pricing

• Plans: Business plans and above.
• Cost: 0 credits per call during beta (pricing subject to change).
• Rate limits: getHistoricalAccountInfo allows 100 requests per second, with a maximum burst of 100. getHistoricalTokenAccountsByOwner allows 10 requests per second, with a maximum burst of 10. These limits are separate from your plan’s RPC rate limit, and requests over them return HTTP 429. See rate limits.
• Network: Mainnet only. Call them on the standard mainnet endpoint, https://mainnet.helius-rpc.com, or the Gatekeeper endpoint, https://beta.helius-rpc.com. Devnet returns error -32601.

Data coverage

Choose a position in history

Read state before and after a transaction

• After the transaction: query its own slot and transactionIndex.
• Before the transaction: query the same slot with transactionIndex minus 1. If the transaction is the first in its slot (index 0), query the previous slot with no transactionIndex.

# State of the account right after the transaction at index 10 in slot 445000000
curl https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "getHistoricalAccountInfo",
    "params": [
      "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      { "slot": 445000000, "transactionIndex": 10 },
      { "encoding": "jsonParsed" }
    ]
  }'

Understand lastUpdatedAt

"lastUpdatedAt": { "slot": 444999837, "transactionIndex": 700 }

• slot and transactionIndex point to the last write at or before the position you queried. In the example above, a query for slot 445,000,000 returned state last written by the transaction at index 700 in slot 444,999,837.
• transactionIndex: null means the write happened outside a transaction, such as epoch rewards.
• slot: 444959999 with transactionIndex: null means the account hasn’t changed since history coverage began. It doesn’t mean the account was written in that slot.

What a null value means

• A null response has no lastUpdatedAt, so it doesn’t tell you when the account was created or closed. To find those transactions, use getTransactionsForAddress.
• An address that never existed also returns null, not an error.
• A slot before history coverage returns error -32018 for every address, whether or not the account existed.

Walk back through account history

const url = `https://mainnet.helius-rpc.com/?api-key=${process.env.HELIUS_API_KEY}`;
const COVERAGE_START_SLOT = 444959999;

type Position = { slot?: number; transactionIndex?: number };

async function getAccountHistory(address: string, start: Position = {}, maxStates = 100) {
  const states = [];
  let position = start;

  while (states.length < maxStates) {
    const response = await fetch(url, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        jsonrpc: "2.0",
        id: "1",
        method: "getHistoricalAccountInfo",
        params: [address, position, { encoding: "base64" }],
      }),
    });
    const { result, error } = await response.json();
    if (error) throw new Error(`${error.code}: ${error.message}`);

    const account = result.value;
    if (!account) break; // The account didn't exist before this write

    states.push(account);
    const { slot, transactionIndex } = account.lastUpdatedAt;
    if (slot <= COVERAGE_START_SLOT) break; // Reached the start of history coverage

    // Step to the position just before this write
    position = transactionIndex ? { slot, transactionIndex: transactionIndex - 1 } : { slot: slot - 1 };
  }

  return states; // Newest first
}

• Accounts that are closed now return null at the latest slot. Pass a start position from when the account still existed.
• Non-transaction writes step to the previous slot. If the same account was also written by a transaction earlier in that slot, the walk skips that state.
• To walk forward in time, list the account’s transactions oldest first with getTransactionsForAddress and sortOrder: "asc". Then read the state at each transaction’s slot and transactionIndex.

Response context

Paginate consistently

• Pass paginationKey back in the configuration object to fetch the next page.
• Stop only when paginationKey is null. A page can be short, or empty, and still have more results behind it.
• Pin slot across every page. If you omit slot, each page reads the latest indexed slot, and your pages can come from different points in time.
• Set limit between 1 and 5,000. It defaults to 5,000.

Encodings and parsed data

• Supported encodings are base64 (the default), base64+zstd, and jsonParsed. base58 and binary aren’t supported.
• jsonParsed token accounts use the mint’s decimals as of the queried position, so amounts are correct even if the mint has since changed. If the mint can’t be read at that position, the account falls back to base64.
• dataSlice works the same way as in getAccountInfo.

Commitment

Errors

Frequently asked questions

How do I get a Solana account’s state at a specific slot?

Can I read an account between two transactions in the same slot?

How far back can I query?

Which plans include historical account methods?

What are the rate limits?

How do I get every past state of an account?

Do I need a new SDK?

Next steps