Filters

Available Filters for getTransactionsForAddress - Slot Range, Block Time, Status, Signature and Token Accounts

By default, getTransactionsForAddress returns all transactions for an address in reverse chronological order. Filters let you narrow that result set on the server before anything is returned - so you're not pulling down thousands of transactions and discarding most of them on the client.

Following filters are available:

slot - for slot based scans,
blockTime - for time-range scans,
signature - for ledger-position bounds,
status - for filtering by execution outcome, and
tokenAccounts - for expanding or restricting coverage to SPL token accounts owned by the address. All filters are optional and can be combined in a single request.

Filters are passed as a nested filters object inside the options parameter. Comparison-based filters (slot, blockTime, signature) accept a comparison object with one or more operators (gte, gt, lte, lt, eq) so you can express both open-ended bounds and closed ranges.

Available Filters

Filter

Type

Description

slot

comparison object

Filter by slot number. Supports gte, gt, lte, lt.

blockTime

comparison object

Filter by Unix timestamp. Supports gte, gt, lte, lt, eq.

signature

comparison object

Filter by signature position within the ledger. Supports gte, gt, lte, lt. Rarely needed — prefer slot or paginationToken for range scans.

status

any | succeeded | failed

Filter by transaction outcome. any returns both. Corresponds to meta.err === null (succeeded) or non-null (failed).

tokenAccounts

none | balanceChanged | all

Controls token-account fan-out. See Token Account Filtering below.

Comparison object example

{
  "gte": 425214949,
  "lt":  425215949
}

Multiple comparison operators can be combined in a single filter to express a range.

Slot, Block time & Signature Filtering

Slot

Filters by the slot number a transaction was confirmed in. Accepts gte, gt, lte, lt. Use a single operator for an open-ended bound, or combine two to express a closed range:

"slot": { "gte": 425214949, "lt": 425215949}

Blocktime

Filters by the Unix timestamp of the block. Accepts gte, gt, lte, lt, and also eq for an exact match. Works the same way as slot but in wall-clock time:

"blockTime": { "gte": 1780963204, "lt": 1780963600}

Signature

Filters by a transaction's position in the ledger relative to a known signature. Accepts gte, gt, lte, lt - no eq, since you'd just query that signature directly. Works the same way structurally as slot and blockTime:

"signature": { "gt": "5wHu1qwD4E5ZPx..." }

The key difference between the three: slot and signature are ledger-native (always present, always reliable), while blockTime can be null for very old blocks. For deep historical scans, prefer slot.

Token Account Filtering

By default, getTransactionsForAddress only returns transactions where the queried address appears directly in accountKeys. Setting tokenAccounts expands this to include transactions that touched token accounts owned by that address.

Value

Behavior

none

Only transactions where the address appears directly in accountKeys. Default.

all

Also includes transactions that reference any token account owned by the address, regardless of whether a balance change occurred.

balanceChanged

Like all, but only for token accounts where the pre/post token balance metadata shows a change. Useful for filtering to actual transfers and swaps rather than read-only account references.

Token ownership is determined from the meta.preTokenBalances and meta.postTokenBalances fields embedded in the transaction, not from a separate on-chain lookup.

When tokenAccounts is all or balanceChanged, the queried address may not appear in accountKeys at all for some results. The address is the owner of an account that participated — not a signer or fee payer in that transaction.

Signatures mode (transactionDetails: "signatures")

{
  "jsonrpc": "2.0",
  "result": {
    "data": [
      {
        "signature": "TransactionSignatureBase58",
        "slot": 250000001,
        "transactionIndex": 12,
        "err": null,
        "memo": null,
        "blockTime": 1780963600,
        "confirmationStatus": "finalized"
      }
    ],
    "paginationToken": "425214939:34"
  },
  "id": 1
}

Response fields

Field

Type

Description

signature

string

Base58-encoded transaction signature.

slot

u64

The slot this transaction was confirmed in.

transactionIndex

number

The transaction's position within its block. Zero-indexed. Useful for deterministic ordering when multiple transactions share a slot.

err

object | null

null if the transaction succeeded. Otherwise contains the TransactionError object. Mirrors the err field from getSignaturesForAddress.

memo

string | null

Memo program message attached to the transaction, if any.

blockTime

i64 | null

Estimated Unix timestamp of the block. null for very old blocks where this wasn't recorded.

confirmationStatus

string

Confirmation status: processed, confirmed, or finalized.

paginationToken

string | null

Cursor for the next page. null when there are no more results.

Full transaction mode (transactionDetails: "full")

{
  "jsonrpc": "2.0",
  "result": {
    "data": [
      {
        "slot": 250000001,
        "transactionIndex": 12,
        "blockTime": 1700000000,
        "transaction": { ... },
        "meta": { ... }
      }
    ],
    "paginationToken": "250000001:12"
  },
  "id": 1
}

Each item in data corresponds to a single confirmed transaction. The transaction and meta fields are identical in structure to what getTransaction returns for the same signature and encoding. Refer to the getTransaction response structure for full field documentation.

Versioned transactions: If any result in the page is a versioned transaction (version 0 or higher), the request will fail unless maxSupportedTransactionVersion is set. Set it to 0 to handle all current transaction versions - this mirrors the same requirement in getTransaction.

Pagination

When a response includes a non-null paginationToken, there are more results. Pass the token in the next request unchanged to continue scanning from where the previous page ended.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "getTransactionsForAddress",
  "params": [
    "AddressBase58",
    {
      "limit": 100,
      "paginationToken": "425214939:34"
    }
  ]
}

Understanding the token structure

The pagination token is two numbers separated by a colon:

"paginationToken": "425214939:34"

The first number is the slot - the block the last returned transaction was confirmed in. The second number is the transactionIndex - the zero-indexed position of that transaction within that block. So 250000101:5 means the 6th transaction in slot 250000101.

This two-part structure is more precise than a signature-based cursor. A signature alone doesn't tell you where in a block a transaction sat - two transactions in the same slot have different signatures but you can't derive their ordering from those signatures alone. The slot:transactionIndex pair pins the exact position in the ledger, so resumption is always deterministic.

How to Paginate?

A single request only returns up to your limit. When more transactions exist, the response contains a paginationToken you can pass into the next request to continue fetching. It's a "slot:transactionIndex" string pointing to the last result returned.

async function printAllTransactions(address) {
  let paginationToken = null;
  let totalFetched = 0;

  do {
    const response = await fetch("https://rpc.shyft.to?api_key=YOUR-API-KEY", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        jsonrpc: "2.0",
        id: 1,
        method: "getTransactionsForAddress",
        params: [address, { limit: 100, paginationToken }]
      })
    });

    const { result } = await response.json();

    result.data.forEach(tx => console.log(tx));
    totalFetched += result.data.length;
    console.log(`Fetched ${totalFetched} transactions so far...`);

    paginationToken = result.paginationToken;

  } while (paginationToken !== null);

  console.log(`Done. Total transactions fetched: ${totalFetched}`);
}

printAllTransactions("AddressBase58");

use reqwest::Client;
use serde_json::{json, Value};

#[tokio::main]
async fn main() {
    let client = Client::new();
    let address = "AddressBase58";
    let mut pagination_token: Option<String> = None;
    let mut total_fetched = 0;

    loop {
        let response = client
            .post("https://rpc.shyft.to?api_key=YOUR_KEY")
            .json(&json!({
                "jsonrpc": "2.0",
                "id": 1,
                "method": "getTransactionsForAddress",
                "params": [address, { "limit": 100, "paginationToken": pagination_token }]
            }))
            .send()
            .await
            .unwrap()
            .json::<Value>()
            .await
            .unwrap();

        let data = response["result"]["data"].as_array().unwrap();

        for tx in data {
            println!("{:#?}", tx);
        }

        total_fetched += data.len();
        println!("Fetched {} transactions so far...", total_fetched);

        pagination_token = response["result"]["paginationToken"]
            .as_str()
            .map(|s| s.to_string());

        if pagination_token.is_none() {
            break;
        }
    }

    println!("Done. Total transactions fetched: {}", total_fetched);
}

PreviousgetTransactionsForAddress NextCode Examples

Last updated 1 month ago