Skip to content
Sign inJoin the waitlist

Data API

Transfers, token balances, a token's details and a block's receipts, each in one call.

The four calls

The calls are JSON-RPC, sent to the same endpoint with the same key as a node call, alone or in a batch.

An address is 0x and 40 hex digits in either case. Answers give addresses in lower case.

CallWhat it answersCostsAnswered by
blockhash_getAssetTransfersThe transfers to or from an address, or of a token120 unitsThe index
blockhash_getTokenBalancesAn address’s ERC-20 balances, now or at a past block20 unitsThe index
blockhash_getTokenMetadataA token’s name, symbol and decimals10 unitsThe index
blockhash_getTransactionReceiptsEvery receipt of a block20 unitsThe node

blockhash_getAssetTransfers

Lists the transfers to an address, from an address, or of a token, in the chain’s order.

The parameters are one object. The sample reads the transfers of USDG into the WETH/USDG pool, two to a page.

Costs
120 units
Answered by
The index
Paged
By pageKey
NameTypeWhat it meansDefault
categorylist of stringsRequired. Any of external (a transaction’s own ETH), internal (ETH moved inside a contract), erc20, erc721 and erc1155.
fromAddressaddressThe sender.
toAddressaddressThe recipient. With fromAddress, only the transfers from the one to the other.
contractAddresseslist of addressesThe tokens to keep, up to 100.every token
fromBlockhex, or "latest"The first block read.0x0
toBlockhex, or "latest"The last block read.latest
order"asc" or "desc"Oldest first, or newest first.asc
maxCounthexThe most transfers on a page, from 0x1 to 0x3e8 (1,000).0x3e8
pageKeystringThe pageKey of the last answer, to read the next page.
withMetadatabooleanAdds each transfer’s block time, as metadata.blockTimestamp.false
excludeZeroValuebooleanLeaves out transfers of nothing.true
curl $RPC/$KEY \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"blockhash_getAssetTransfers","params":[
       {"category":["erc20"],
        "contractAddresses":["0x5fc5360d0400a0fd4f2af552add042d716f1d168"],
        "toAddress":"0x52e65b17fb6e5ba00ed806f37afcd2daa50271ca",
        "fromBlock":"0x6eeccc2","toBlock":"0x6eecd63",
        "maxCount":"0x2","withMetadata":true}]}'
{"jsonrpc":"2.0","id":1,"result":{
  "transfers":[
    {"blockNum":"0x6eeccc2",
     "uniqueId":"0xfc94b068a5df32475fb8cb7dfa41046ab7923c7744d6109e08d84336bcfd811d:log:3",
     "hash":"0xfc94b068a5df32475fb8cb7dfa41046ab7923c7744d6109e08d84336bcfd811d",
     "from":"0x5399d94d2cab7c252a6034042e1917a0e5e17a18",
     "to":"0x52e65b17fb6e5ba00ed806f37afcd2daa50271ca",
     "value":8.253177,
     "erc721TokenId":null,"erc1155Metadata":[],"tokenId":null,
     "asset":"USDG","category":"erc20",
     "rawContract":{"value":"0x7deef9",
       "address":"0x5fc5360d0400a0fd4f2af552add042d716f1d168","decimal":"0x6"},
     "metadata":{"blockTimestamp":"2026-11-17T04:37:14.000Z"}},
    {"blockNum":"0x6eecd02",
     "uniqueId":"0xde00db31d81ce896fb3b1ff3b1e6e3febbe3093eb99eb1b9e2f896c335bae68e:log:13",
     "hash":"0xde00db31d81ce896fb3b1ff3b1e6e3febbe3093eb99eb1b9e2f896c335bae68e",
     "from":"0x663dc15d3c1ac63ff12e45ab68fea3f0a883c251",
     "to":"0x52e65b17fb6e5ba00ed806f37afcd2daa50271ca",
     "value":5.513793,
     "erc721TokenId":null,"erc1155Metadata":[],"tokenId":null,
     "asset":"USDG","category":"erc20",
     "rawContract":{"value":"0x542241",
       "address":"0x5fc5360d0400a0fd4f2af552add042d716f1d168","decimal":"0x6"},
     "metadata":{"blockTimestamp":"2026-11-17T04:37:22.000Z"}}],
  "pageKey":"…"}}

The answer

  • uniqueId is the transaction’s hash and the transfer’s place in it: :log: and the log’s index for a token, :external for a transaction’s own ETH, :internal: and a number for ETH moved inside a contract.
  • value is the amount over the token’s decimals, as a JSON number. The exact amount is rawContract.value, in hex.
  • asset is ETH, or the symbol the token’s contract gives. A contract can claim any symbol: tell tokens apart by rawContract.address.
  • An NFT has no value and no asset. An ERC-721’s id is tokenId; an ERC-1155 transfer’s ids and amounts are in erc1155Metadata, a batch as one transfer.
  • to is null for a transaction that made a contract.
  • pageKey is there when the range holds more.

Where it differs from Alchemy

  • A call names fromAddress, toAddress or contractAddresses. The whole chain’s transfers are not answered.
  • The external and internal categories need fromAddress or toAddress.
  • internal transfers begin on November 11, 2026, when the index began to trace. They are numbered in the index’s own order.
  • pageKey is an opaque string, not a UUID.
  • A page can hold fewer transfers than maxCount, or none, and still give a pageKey. This happens most with the ETH an address sent.
  • A token whose decimals the index could not read has null for value.

Paging with pageKey

An answer that has more to give holds a pageKey. Send the same call again with it to read the next page.

Keep category, the addresses, contractAddresses, fromBlock, toBlock, order and excludeZeroValue as they were. A key sent with other parameters is refused with -32602.

maxCount and withMetadata may change from page to page.

A walk that began at latest ends at the block that was the newest when it began.

The walk is over when an answer holds no pageKey.

PAGE_KEY="<the pageKey of the last answer>"

curl $RPC/$KEY \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"blockhash_getAssetTransfers","params":[
       {"category":["erc20"],
        "contractAddresses":["0x5fc5360d0400a0fd4f2af552add042d716f1d168"],
        "toAddress":"0x52e65b17fb6e5ba00ed806f37afcd2daa50271ca",
        "fromBlock":"0x6eeccc2","toBlock":"0x6eecd63",
        "maxCount":"0x2","withMetadata":true,
        "pageKey":"'$PAGE_KEY'"}]}'
{"jsonrpc":"2.0","id":1,"result":{
  "transfers":[
    {"blockNum":"0x6eecd63",
     "uniqueId":"0xb6f85f1476e9e55c36647564b705596225a933e99cb57512e98bb303a0cf7365:log:4",
     "hash":"0xb6f85f1476e9e55c36647564b705596225a933e99cb57512e98bb303a0cf7365",
     "from":"0x204faca1764b154221e35c0d20abb3c525710498",
     "to":"0x52e65b17fb6e5ba00ed806f37afcd2daa50271ca",
     "value":24.61921,
     "erc721TokenId":null,"erc1155Metadata":[],"tokenId":null,
     "asset":"USDG","category":"erc20",
     "rawContract":{"value":"0x177a8ca",
       "address":"0x5fc5360d0400a0fd4f2af552add042d716f1d168","decimal":"0x6"},
     "metadata":{"blockTimestamp":"2026-11-17T04:37:34.000Z"}}]}}

blockhash_getTokenBalances

Gets the ERC-20 balances of an address, now or at a past block.

The sample reads the WETH/USDG pool’s balances of WETH and USDG at a block.

Costs
20 units
Answered by
The index
Paged
No
NameTypeWhat it meansDefault
params[0]addressThe address whose balances are read.
params[1]"erc20", or a list of addresses"erc20" for every token the address has held, or up to 100 tokens by address."erc20"
params[2]object{"blockNumber": "0x…"} reads the balances as they stood at the end of that block.now
curl $RPC/$KEY \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"blockhash_getTokenBalances","params":[
       "0x52e65b17fb6e5ba00ed806f37afcd2daa50271ca",
       ["0x0bd7d308f8e1639fab988df18a8011f41eacad73",
        "0x5fc5360d0400a0fd4f2af552add042d716f1d168"],
       {"blockNumber":"0x6eecd63"}]}'
{"jsonrpc":"2.0","id":1,"result":{
  "address":"0x52e65b17fb6e5ba00ed806f37afcd2daa50271ca",
  "tokenBalances":[
    {"contractAddress":"0x0bd7d308f8e1639fab988df18a8011f41eacad73",
     "tokenBalance":"0x000000000000000000000000000000000000000000000109151bbe21f404e9e6"},
    {"contractAddress":"0x5fc5360d0400a0fd4f2af552add042d716f1d168",
     "tokenBalance":"0x0000000000000000000000000000000000000000000000000000016a99bf982f"}]}}

The answer

  • tokenBalance is the balance in the token’s smallest unit, as a 32-byte hex word.
  • Tokens named in the call are answered in the order they were asked, at zero where the address holds none.
  • With "erc20", a token the address once held and holds no more is listed at zero.

Where it differs from Alchemy

  • The third parameter is Blockhash’s own. It is how a balance at a past block is read from a node that keeps recent state only.
  • A balance is the sum of the token’s transfers to and from the address. A token that changes balances without a transfer, such as a rebasing token, can differ from its balanceOf.

blockhash_getTokenMetadata

Gets a token’s name, symbol and decimals.

Costs
10 units
Answered by
The index
Paged
No
NameTypeWhat it meansDefault
params[0]addressThe token.
curl $RPC/$KEY \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"blockhash_getTokenMetadata","params":["0x5fc5360d0400a0fd4f2af552add042d716f1d168"]}'
{"jsonrpc":"2.0","id":1,"result":{"decimals":6,"logo":null,"name":"Global Dollar","symbol":"USDG"}}
  • name, symbol and decimals are what the token’s contract answered when the index first read it. They are the contract’s own claim: tell tokens apart by address.
  • A token the index does not hold, or whose contract did not answer, has null in those fields.
  • logo is always null.

blockhash_getTransactionReceipts

Gets the receipt of every transaction in a block.

The parameters are one object.

Costs
20 units
Answered by
The node
Paged
No
NameTypeWhat it meansDefault
blockNumberhexThe block, by its number.
blockHash32-byte hashThe block, by its hash. A call names the block one way or the other, not both.
curl $RPC/$KEY \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"blockhash_getTransactionReceipts","params":[{"blockNumber":"0x6eeccc2"}]}'
{"jsonrpc":"2.0","id":1,"result":{"receipts":[
  {"blockHash":"0x059a2e1e3be6967cd782145ac308039919d2037f70472e95c80bae0ca2c0dafd",
   "blockNumber":"0x6eeccc2",
   "contractAddress":null,
   "cumulativeGasUsed":"0x0",
   "effectiveGasPrice":"0x1312d00",
   "from":"0x00000000000000000000000000000000000a4b05",
   "gasUsed":"0x0",
   "gasUsedForL1":"0x0",
   "l1BlockNumber":"0x19353a1",
   "logs":[],
   "logsBloom":"0x…",
   "status":"0x1",
   "to":"0x00000000000000000000000000000000000a4b05",
   "transactionHash":"0x82bea0ad11a2f2071ed6664564337fffee4a5050564913749b3030ae8252a7fc",
   "transactionIndex":"0x0",
   "type":"0x6a"},
  …]}}
  • Each receipt is as eth_getTransactionReceipt gives it.
  • A block the node does not have is answered {"receipts": null}.
  • The node call eth_getBlockReceipts returns the same receipts as a plain list.
  • The two cost the same, 20 units, and take the same 20 units from the speed, because one piece of work has one price.