How to get transaction history for an address on Ethereum

Covalent TeamUpdated 14 min read

Get the full transaction history of any Ethereum address: recent and paginated history, the first transaction, time windows, counts and cross-chain history.

To list every transaction an Ethereum address has sent or received, you need an indexed API: Ethereum nodes don't keep transactions by address. The GoldRush Wallet Transaction History API and the endpoints around it, part of the GoldRush Foundational API, return an address's history with decoded logs and fiat values, and the same requests work on other chains by changing the chain name.

This guide covers each way to read that history: the latest page, every page, the first transactions, a time window, a one-call summary with the transaction count, several chains at once, and a single transaction by hash.

Why you can't get address history from an RPC node

An Ethereum node answers JSON-RPC calls such as eth_getTransactionByHash, eth_getBlockByNumber and eth_getTransactionReceipt. Each one looks data up by hash or block number. There is no "transactions by address" method, because the node doesn't index transactions by the addresses involved.

To rebuild one address's history from a node you would read every block from genesis, check each transaction's from and to, fetch receipts for the logs, and run traces to catch internal ETH transfers made by contracts. eth_getLogs can filter token Transfer events by an address topic, but a plain ETH transfer emits no log at all. That is why wallets and explorers run an indexer. What is an RPC node and how does it work? explains what a node does serve.

JSON-RPC node Indexed transactions API
Lookup by address No method: scan every block and receipt yourself One request per page, by address
Decoding Raw hex input and logs; you decode them with each contract ABI Decoded log events, with token metadata and fiat quotes
Several chains One endpoint and client setup per chain Same request, change the chain name (eth-mainnet, base-mainnet)
Pagination You build it over your own database Stable pages with links.prev / links.next, or time buckets
Internal transfers Trace calls (debug_ / trace_ methods) on an archive node with-internal=true on chains with trace support

Which endpoint to use

All of these take a chain name such as eth-mainnet, and most accept an ENS name in place of the address.

You want Endpoint Path
The latest transactions, for a wallet screen Wallet Transaction History /v1/{chain}/address/{address}/transactions_v3/
Any page of the full history Paginated Wallet Transactions /v1/{chain}/address/{address}/transactions_v3/page/{page}/
The first transactions an address made Earliest Wallet Transactions /v1/{chain}/bulk/transactions/{address}/
Transactions in a 15-minute window Time Bucket Transactions /v1/{chain}/bulk/transactions/{address}/{timeBucket}/
Count, first and last transaction, in one call Wallet Transaction Summary /v1/{chain}/address/{address}/transactions_summary/
One feed for up to 10 addresses on up to 10 chains Cross-Chain Transaction History /v1/allchains/transactions/
Which chains an address has used Address Activity /v1/address/{address}/activity/
One transaction by hash Transaction /v1/{chain}/transaction_v2/{txHash}/
Every transaction in a block Block Transactions see the block guide

Set up

You need a GoldRush API key: sign up and copy it from the dashboard. The examples use Node.js 18 or later (for the built-in fetch) and TypeScript; run them with npx tsx file.ts, or drop the type annotations and use plain JavaScript.

One helper sends the key as a Bearer token and returns the response's data object. It accepts either a path or a full URL, because the API's links.prev and links.next fields are full URLs you can call directly:

const API = "https://api.covalenthq.com/v1";const KEY = process.env.GOLDRUSH_API_KEY; type Params = Record<string, string | number | boolean>; async function goldrush(pathOrUrl: string, params: Params = {}) {    const url = new URL(pathOrUrl.startsWith("http") ? pathOrUrl : API + pathOrUrl);    for (const [k, v] of Object.entries(params)) url.searchParams.set(k, String(v));    const res = await fetch(url, { headers: { Authorization: `Bearer ${KEY}` } });    const body = await res.json();    if (!res.ok || body.error) throw new Error(`${res.status} ${body.error_message ?? ""} (${url.pathname})`);    return body.data;} type Tx = {    block_signed_at: string;    block_height: number;    tx_offset: number;    tx_hash: string;    successful: boolean;    from_address: string;    to_address: string | null;    value: string; // wei, as a string    value_quote: number | null;    pretty_value_quote: string | null;    gas_spent: number;    gas_price: number;    fees_paid: string; // wei, as a string    gas_quote: number | null;}; const CHAIN = "eth-mainnet";const ADDRESS = "0xdc2f48410033d18c5cce2c11135fd0d40fc19aaa";

Add "no-logs": true to any transactions request when you don't need the decoded log events: the response is smaller and each item costs less.

Get the most recent transactions

The Wallet Transaction History endpoint, transactions_v3/ with no page number, returns the newest page of an address's history: up to 100 transactions, newest first.

const recent = await goldrush(`/${CHAIN}/address/${ADDRESS}/transactions_v3/`, { "no-logs": true }); console.log(`page ${recent.current_page}, ${recent.items.length} transactions`);for (const tx of recent.items.slice(0, 5) as Tx[]) {    console.log(tx.block_signed_at, tx.tx_hash, tx.from_address, "->", tx.to_address, tx.pretty_value_quote);}

Each item carries the block time and height, tx_hash, from_address and to_address, successful, value in wei with value_quote in your quote currency, and the fee as gas_spent, gas_price, fees_paid (wei) and gas_quote. With logs on, log_events holds each decoded event, such as an ERC-20 Transfer with its token name and decimals.

The response also has current_page, the number of this page, and links. On the newest page links.next is null and links.prev points to the page before it.

Get the full history, page by page

The Paginated Wallet Transactions endpoint, transactions_v3/page/{page}/, returns any page of the history. Pages are zero-indexed and page 0 holds the oldest transactions: new transactions are appended to the last page, so the page an older transaction sits on never changes. That makes the pagination stable. A page you have already downloaded stays valid, and you can fetch pages in parallel.

For an address with 335 transactions there are four pages: pages 0 to 2 hold 100 each and page 3, the newest, holds 35. So the newest page's current_page tells you how many pages exist:

async function getAllTransactions(chain: string, address: string, params: Params = {}, concurrency = 4) {    const base = `/${chain}/address/${address}/transactions_v3/`;    const newest = await goldrush(base, params);    const pages: Tx[][] = [];    pages[newest.current_page] = newest.items;     // Fetch the older pages a few at a time, to stay inside your rate limit    const older = [...Array(newest.current_page).keys()];    for (let i = 0; i < older.length; i += concurrency) {        const batch = older.slice(i, i + concurrency);        const results = await Promise.all(batch.map((p) => goldrush(`${base}page/${p}/`, params)));        batch.forEach((p, j) => (pages[p] = results[j].items));    }     // Oldest first: by block, then by position in the block    return pages.flat().sort((a, b) => a.block_height - b.block_height || a.tx_offset - b.tx_offset);} const history = await getAllTransactions(CHAIN, ADDRESS, { "no-logs": true });console.log(history.length, "transactions, first on", history[0].block_signed_at);

Within a page, transactions come newest first by default; pass block-signed-at-asc=true to reverse that.

To keep a copy up to date, store the number of the newest page you downloaded. Next time, fetch that page again (it may have filled up) and follow links.next until it is null:

async function getNewTransactions(chain: string, address: string, lastPage: number, params: Params = {}) {    let data = await goldrush(`/${chain}/address/${address}/transactions_v3/page/${lastPage}/`, params);    const items: Tx[] = [...data.items];    while (data.links?.next) {        data = await goldrush(data.links.next, params);        items.push(...data.items);    }    return { items, lastPage: data.current_page as number };}

Replace the stored copy of lastPage with the new items (match on tx_hash) rather than appending, since you fetched it whole again.

Example: export every transaction of a large contract

Busy contracts have millions of transactions, such as the Uniswap V3 USDC/WETH pool 0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640. The same approach works: start from the newest page and follow links.prev back to page 0, writing each page out as you go so a crash loses at most one page.

import { appendFileSync } from "node:fs"; const POOL = "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640"; let page = await goldrush(`/${CHAIN}/address/${POOL}/transactions_v3/`, { "no-logs": true });while (true) {    appendFileSync("pool-transactions.jsonl", page.items.map((tx: Tx) => JSON.stringify(tx) + "\n").join(""));    console.log("saved page", page.current_page);    if (!page.links?.prev) break;    page = await goldrush(page.links.prev, { "no-logs": true });}

At this size, cost matters: each item is billed, so a full page of 100 transactions costs 10 credits. Use no-logs if you only need the transactions, run the pages in parallel as above if you need speed, or use time buckets (below) if you only need part of the history.

Get the earliest transactions for an address

The Earliest Wallet Transactions endpoint returns the first transactions involving an address. Use it to find when a wallet was first seen on a chain, to measure its age, or to show "member since" in an app, without paging through the whole history.

const earliest = await goldrush(`/${CHAIN}/bulk/transactions/${ADDRESS}/`, { "no-logs": true }); const [first] = (earliest.items as Tx[]).sort((a, b) => a.block_height - b.block_height || a.tx_offset - b.tx_offset);console.log("first seen", first.block_signed_at, "in", first.tx_hash);console.log("from", first.from_address, "value", first.value, "wei", first.pretty_value_quote);console.log(    "fee",    first.fees_paid,    "wei =",    first.gas_spent,    "gas x",    first.gas_price,    "wei/gas",    `($${first.gas_quote?.toFixed(2)})`);

For the example address the first transaction is an incoming ETH transfer on 23 October 2023: value is 59580000000000000 wei (0.05958 ETH), with value_quote in USD at that day's price, and the sender paid fees_paid of 783902207760000 wei, which is gas_spent (21,000) times gas_price. value and fees_paid are strings because they can exceed JavaScript's safe integer range; convert them with BigInt or a decimals helper, not Number.

The earliest transactions are the first non-empty time bucket for the address, so the response has current_bucket and links.next, which points to the next bucket with transactions. Follow it to keep reading forward in time.

Fetch transactions by time window (time buckets)

The Time Bucket Transactions endpoint splits time into 15-minute buckets counted from the Unix epoch. Bucket 0 runs from 1970-01-01 00:00:00 to 00:14:59 UTC, and the bucket for any moment is its Unix time in seconds divided by 900, rounded down. A request returns every transaction the address made in that bucket, unpaginated.

Worked example: for transactions between 02:35 and 03:58 UTC on 8 March 2023, start with 02:35:00, which is Unix time 1678242900. 1678242900 / 900 = 1864714.33, so the bucket is 1864714, covering 02:30:00 to 02:44:59. The next bucket, 1864715, covers 02:45:00 to 02:59:59, and 03:58 falls in bucket 1864719.

const BUCKET_SECONDS = 15 * 60;const toBucket = (when: string | Date) => Math.floor(new Date(when).getTime() / 1000 / BUCKET_SECONDS); console.log(toBucket("2023-03-08T02:35:00Z")); // 1864714console.log(toBucket("2023-03-08T03:58:00Z")); // 1864719

Unlike pages, buckets can be empty. The response's links.next points to the next bucket that has transactions, so you can skip the empty ones, and complete is true once a bucket is in the past and fully filled. A complete bucket never changes, so cache it per address and bucket and never request it twice:

const cache = new Map<string, { items: Tx[]; links?: { next?: string | null } }>(); async function getBucket(chain: string, address: string, bucket: number, params: Params = {}) {    const key = `${chain}:${address.toLowerCase()}:${bucket}`;    const hit = cache.get(key);    if (hit) return hit;    const data = await goldrush(`/${chain}/bulk/transactions/${address}/${bucket}/`, params);    if (data.complete) cache.set(key, data); // an incomplete bucket can still gain transactions    return data;} const bucketOf = (link?: string | null) =>    link ? Number(new URL(link).pathname.split("/").filter(Boolean).pop()) : null; async function getTransactionsBetween(chain: string, address: string, from: string, to: string, params: Params = {}) {    const start = new Date(from).getTime();    const end = new Date(to).getTime();    const last = toBucket(to);    const items: Tx[] = [];    for (let bucket: number | null = toBucket(from); bucket !== null && bucket <= last; ) {        const data = await getBucket(chain, address, bucket, params);        items.push(...data.items);        bucket = bucketOf(data.links?.next);    }    // Buckets are 15-minute aligned: trim to the exact window    return items.filter((tx) => {        const t = new Date(tx.block_signed_at).getTime();        return t >= start && t <= end;    });} const march8 = await getTransactionsBetween(CHAIN, ADDRESS, "2023-03-08T02:35:00Z", "2023-03-08T03:58:00Z");

Time buckets are how you read the history of a wallet or contract with millions of transactions without long-running requests: each call covers a fixed slice of time, slices can be fetched in any order, and completed slices are cached for good. They are also the natural fit for "everything after a point in time", such as resuming an export from the last bucket you saved.

Get a wallet's transaction count, first and last transaction

To show how active a wallet is, you don't need its history. The Wallet Transaction Summary endpoint returns, in one call per chain, total_count (the number of transactions), earliest_transaction and latest_transaction (each with block_signed_at and tx_hash). with-gas=true adds a gas_summary with the number of transactions the address sent and the total fees it paid, in wei and in your quote currency. with-transfer-count=true adds transfer_count, the number of ERC-20 Transfer, Deposit and Withdraw events. Both options add credits and can slow the response for very busy wallets.

Combine it with the Address Activity endpoint, which lists every chain the address has used with its first and last activity, and you get a multi-chain activity summary:

async function activitySummary(address: string) {    const activity = await goldrush(`/address/${address}/activity/`);    const chains: string[] = activity.items.map((c: { name: string }) => c.name);     return Promise.all(        chains.map(async (chain) => {            const { items } = await goldrush(`/${chain}/address/${address}/transactions_summary/`);            const s = items[0];            return {                chain,                transactions: s?.total_count ?? 0,                first: s?.earliest_transaction?.block_signed_at ?? null,                last: s?.latest_transaction?.block_signed_at ?? null,            };        })    );} console.table(await activitySummary(ADDRESS));

When this was written, the example address had 152 transactions on Ethereum, the first on 23 October 2023, and Address Activity listed it on more than a dozen chains. Address Activity also returns each chain's label (such as "Ethereum Mainnet") and logo, for display.

Get transaction history across chains in one call

The Cross-Chain Transaction History endpoint returns one feed, newest first, for up to 10 EVM addresses on up to 10 EVM chains. Each item has chain_name and chain_id, so you can tell the chains apart. Leave out chains and it uses the Foundational chains. It pages with cursors rather than page numbers: pass the response's cursor_before as before to get the next, older page. It takes plain 0x addresses only, not ENS names.

async function* crossChainHistory(addresses: string[], chains: string[], limit = 100) {    let before: string | undefined;    while (true) {        const params: Params = { addresses: addresses.join(","), chains: chains.join(","), limit };        if (before) params.before = before;        const data = await goldrush("/allchains/transactions/", params);        if (!data.items.length) return;        yield data.items as (Tx & { chain_name: string })[];        if (!data.cursor_before) return;        before = data.cursor_before;    }} for await (const page of crossChainHistory([ADDRESS], ["eth-mainnet", "base-mainnet", "optimism-mainnet"])) {    for (const tx of page) console.log(tx.chain_name, tx.block_signed_at, tx.tx_hash);    break; // first page only}

By default items come without logs; with-logs=true adds raw logs and with-decoded-logs=true decoded ones, at a higher price per item.

Look up a single transaction

When you have a hash, the Transaction endpoint returns that one transaction with its decoded log events:

const HASH = "0x6777840dae5d445f4c0b83f0916edf6302662ff9554a7d9f7beb7dcf46213782";const { items } = await goldrush(`/${CHAIN}/transaction_v2/${HASH}/`);const tx = items[0];console.log(tx.successful, tx.from_address, "->", tx.to_address, tx.value, tx.log_events?.length ?? 0, "events");

On chains with trace support, with-internal=true adds the internal transactions, transfers made by contracts during the transaction, and with-input-data=true adds the method ID (input_data.method_id, on fewer chains). The recent, paginated and earliest address endpoints accept with-internal too. Traces support lists the chains.

What each call costs

Transactions endpoints are billed per item returned; the summary, address activity and single-transaction calls per call. Figures are the base costs from the API reference:

Endpoint Base cost
Wallet Transaction History 0.1 per item
Paginated Wallet Transactions 0.1 per item
Earliest Wallet Transactions 0.1 per item
Time Bucket Transactions 0.1 per item
Wallet Transaction Summary 1 per call
Address Activity 0.5 per call
Cross-Chain Transaction History 0.25 per item
Transaction 0.1 per call
Block Transactions 0.1 per item

no-logs lowers the per-item cost, and with-internal, with-classification, with-gas and with-transfer-count add to it; each endpoint's reference page gives the exact figures, and the pricing calculator estimates a monthly bill.

Frequently asked questions

How do I get the transaction history of an Ethereum address?

Call the GoldRush Wallet Transaction History endpoint, /v1/eth-mainnet/address/{address}/transactions_v3/, with your API key. It returns the newest 100 or fewer transactions with decoded logs and fiat values. For the full history, request pages 0 up to the newest page's current_page from /transactions_v3/page/{page}/, or follow links.prev.

How do I find the first transaction of an Ethereum address?

Call the Earliest Wallet Transactions endpoint, /v1/eth-mainnet/bulk/transactions/{address}/, and take the item with the lowest block height. If you only need the date and hash, the Wallet Transaction Summary endpoint returns earliest_transaction in one call. Page 0 of the paginated endpoint also holds the oldest transactions.

How do I get the number of transactions for an address?

Use the Wallet Transaction Summary endpoint, /v1/{chain}/address/{address}/transactions_summary/. Its total_count is the number of transactions on that chain, returned with the first and last transaction, so you don't have to download and count the history. Call it once per chain for a multi-chain total.

Can I get an address's transaction history from an RPC node?

Not directly. JSON-RPC has no method that returns transactions by address, so you would have to scan every block and receipt, and trace contracts for internal transfers. An indexed API such as GoldRush has already done that work and returns the history by address.

How do I get the transactions of an address in a date range?

Convert the start and end times to 15-minute time buckets (Unix seconds divided by 900, rounded down), call the Time Bucket Transactions endpoint from the first bucket, follow links.next to skip empty buckets until you pass the last one, then trim the results to the exact times.

Does this work on chains other than Ethereum?

Yes. Every request takes the chain name, so the same code works on Base, Polygon, Arbitrum and the other chains GoldRush supports by changing eth-mainnet. For Bitcoin, see the Bitcoin wallet lookup guide.

Next steps

Get new guides by email

New tutorials and best practices for building with blockchain data, sent as they're published.