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.
| Call | What it answers | Costs | Answered by |
|---|---|---|---|
| blockhash_ | The transfers to or from an address, or of a token | 120 units | The index |
| blockhash_ | An address’s ERC-20 balances, now or at a past block | 20 units | The index |
| blockhash_ | A token’s name, symbol and decimals | 10 units | The index |
| blockhash_ | Every receipt of a block | 20 units | The 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
| Name | Type | What it means | Default |
|---|---|---|---|
category | list of strings | Required. Any of external (a transaction’s own ETH), internal (ETH moved inside a contract), erc20, erc721 and erc1155. | |
fromAddress | address | The sender. | |
toAddress | address | The recipient. With fromAddress, only the transfers from the one to the other. | |
contractAddresses | list of addresses | The tokens to keep, up to 100. | every token |
fromBlock | hex, or "latest" | The first block read. | 0x0 |
toBlock | hex, or "latest" | The last block read. | latest |
order | "asc" or "desc" | Oldest first, or newest first. | asc |
maxCount | hex | The most transfers on a page, from 0x1 to 0x3e8 (1,000). | 0x3e8 |
pageKey | string | The pageKey of the last answer, to read the next page. | |
withMetadata | boolean | Adds each transfer’s block time, as metadata.. | false |
excludeZeroValue | boolean | Leaves 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
uniqueIdis the transaction’s hash and the transfer’s place in it::log:and the log’s index for a token,:externalfor a transaction’s own ETH,:internal:and a number for ETH moved inside a contract.valueis the amount over the token’s decimals, as a JSON number. The exact amount israwContract.value, in hex.assetisETH, or the symbol the token’s contract gives. A contract can claim any symbol: tell tokens apart byrawContract.address.- An NFT has no
valueand noasset. An ERC-721’s id istokenId; an ERC-1155 transfer’s ids and amounts are inerc1155Metadata, a batch as one transfer. toisnullfor a transaction that made a contract.pageKeyis there when the range holds more.
Where it differs from Alchemy
- A call names
fromAddress,toAddressorcontractAddresses. The whole chain’s transfers are not answered. - The
externalandinternalcategories needfromAddressortoAddress. internaltransfers begin on November 11, 2026, when the index began to trace. They are numbered in the index’s own order.pageKeyis an opaque string, not a UUID.- A page can hold fewer transfers than
maxCount, or none, and still give apageKey. This happens most with the ETH an address sent. - A token whose decimals the index could not read has
nullforvalue.
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
| Name | Type | What it means | Default |
|---|---|---|---|
params[0] | address | The 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
tokenBalanceis 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
| Name | Type | What it means | Default |
|---|---|---|---|
params[0] | address | The 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,symbolanddecimalsare 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
nullin those fields. logois alwaysnull.
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
| Name | Type | What it means | Default |
|---|---|---|---|
blockNumber | hex | The block, by its number. | |
blockHash | 32-byte hash | The 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_getTransactionReceiptgives it. - A block the node does not have is answered
{"receipts": null}. - The node call
eth_getBlockReceiptsreturns 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.