🛠️ Alchemy SDKSDK Core Methods

getAssetTransfers - SDK

The Transfers API allows you to easily fetch historical transactions for any address across Ethereum and supported L2s including Polygon, Arbitrum, and Optimism. See the web documentation for the full details.

The Transfers API allows you to easily fetch historical transactions for any address across Ethereum and supported L2s including Polygon, Arbitrum, and Optimism. See the web documentation for the full details.

Don’t have an API key?

Start using this method in your app today. Get started for free

Description

The Transfers API allows you to fetch historical transactions for any address across Ethereum easily and supported L2s including Polygon, Arbitrum, and Optimism.

See the web documentation for the full details.

Parameters

ParameterTypeDescription
paramsobjectAn object containing fields for the asset transfer query

params object parameters

ParamTypeDescription
fromBlockstringThe starting block to check for transfers. This value is inclusive and defaults to 0x0 if omitted.
toBlockstringInclusive to block (hex string, int, or latest). Defaults to latest if omitted.
order?stringWhether to return results in ascending or descending order by block number. Defaults to ascending if omitted.
fromAddress?stringThe from address to filter transfers by. This value defaults to a wildcard for all addresses if omitted.
toAddress?stringThe to address to filter transfers by. This value defaults to a wildcard for all addresses if omitted.
contractAddressesarray of stringsList of contract addresses to filter for - only applies to erc20, erc721, erc1155 transfers. Defaults to all addresses if omitted.
excludeZeroValuebooleanWhether to exclude transfers with zero value. Note that zero value is different from null value. Defaults to true if omitted.
categoryarrayAn array of categories to get transfers for. Available categories include: [ EXTERNAL = external, INTERNAL = internal, ERC20 = erc20, ERC721 = erc721, ERC1155 = erc1155, SPECIALNFT = specialnft]
maxCountnumberThe maximum number of results to return per page. Defaults to 1000 if omitted.
pageKey?stringOptional page key from an existing one to use for pagination.
withMetadatabooleanWhether to include additional metadata about each transfer event. Defaults to false if omitted.

Response

PropertyTypeDescription
Promise<AssetTransfersResponse | AssetTransfersWithMetadataResponse>objectThis returns the object response depending on whether withMetadata was set to trueor not.

AssetTransfersResponse response object parameters

ParameterTypeDescription
uniqueIdstringThe unique ID of the transfer.
categorystringThe category of the transfer.
blockNumstringThe block number where the transfer occurred.
fromstringThe from address of the transfer.
tostring | nullThe to address of the transfer.
valuenumber | nullConverted asset transfer value as a number (raw value divided by contract decimal). null if ERC721 transfer or contract decimal is not available.
erc721TokenIdstring | nullThe raw ERC721 token id of the transfer as a hex string. null if not an ERC721 transfer.
erc1155MetadataERC1155Metadata[] | nullA list of ERC1155 metadata objects, if the asset transferred, is an ERC1155 token. null if not an ERC1155 transfer.
tokenIdstring | nullThe token id of the token transferred.
assetstring | nullReturns the token’s symbol or ETH for other transfers. null if the information was not available.
hashstringThe transaction hash of the transfer transaction.
rawContractRawContractInformation about the raw contract of the asset transferred.

AssetTransfersWithMetadataResponse object parameters

ParameterTypeDescription
uniqueIdstringThe unique ID of the transfer.
categorystringThe category of the transfer.
blockNumstringThe block number where the transfer occurred.
fromstringThe from address of the transfer.
tostring | nullThe to address of the transfer.
valuenumber | nullConverted asset transfer value as a number (raw value divided by contract decimal). null if ERC721 transfer or contract decimal not available.
erc721TokenIdstring | nullThe raw ERC721 token id of the transfer as a hex string. null if not an ERC721 transfer.
erc1155MetadataERC1155Metadata[] | nullA list of ERC1155 metadata objects, if the asset transferred, is an ERC1155 token. null if not an ERC1155 transfer.
tokenIdstring | nullThe token id of the token transferred.
assetstring | nullReturns the token’s symbol or ETH for other transfers. null if the information was not available.
hashstringThe transaction hash of the transfer transaction.
rawContractRawContractInformation about the raw contract of the asset transferred.
metadataobjectAdditional metadata about the transfer event. The additional metadata object includes: 1. blockTimestamp: string Timestamp of the block from which the transaction event originated.

Example Request and Response

Prerequisite: You will need to install the Alchemy SDK before making requests with it.

The commands for installing it using npm or yarn are given below:

$npm install alchemy-sdk@latest

Request

Here is an example of how to make a getAssetTransfers request using the Alchemy SDK:

getAssetTransfers.js
1// Imports the Alchemy SDK
2const { Alchemy, Network } = require("alchemy-sdk");
3
4// Configures the Alchemy SDK
5const config = {
6    apiKey: "alchemy-replit", // Replace with your API key
7    network: Network.ETH_MAINNET, // Replace with your network
8};
9
10// Creates an Alchemy object instance with the config to use for making requests
11const alchemy = new Alchemy(config);
12
13const main = async () => {
14    //Assign the contract address to a variable
15    let toAddress = "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152";
16
17  //The response fetches the transactions the specified addresses.
18    let response = await alchemy.core.getAssetTransfers({
19        fromBlock: "0x0",
20        fromAddress: "0x0000000000000000000000000000000000000000",
21        toAddress: toAddress,
22        excludeZeroValue: true,
23        category: ["erc721", "erc1155"],
24      })
25
26    //Logging the response to the console
27    console.log(response)
28};
29
30main();

Response

json
1{
2    "transfers": [
3        {
4            "blockNum": "0xd2113f",
5            "uniqueId": "0xb8ad1138a22a0dcc5eddca1db9aa0c731891fe60041ed6f4d9ceb737c9f1b06d:log:165",
6            "hash": "0xb8ad1138a22a0dcc5eddca1db9aa0c731891fe60041ed6f4d9ceb737c9f1b06d",
7            "from": "0x0000000000000000000000000000000000000000",
8            "to": "0x1e6e8695fab3eb382534915ea8d7cc1d1994b152",
9            "value": null,
10            "erc721TokenId": "0x0000000000000000000000000000000000000000000000000000000000001acb",
11            "erc1155Metadata": null,
12            "tokenId": "0x0000000000000000000000000000000000000000000000000000000000001acb",
13            "asset": "DUSK",
14            "category": "erc721",
15            "rawContract": {
16                "value": null,
17                "address": "0x0beed7099af7514ccedf642cfea435731176fb02",
18                "decimal": null
19            }
20        },
21        {
22            "blockNum": "0xd2113f",
23            "uniqueId": "0xb8ad1138a22a0dcc5eddca1db9aa0c731891fe60041ed6f4d9ceb737c9f1b06d:log:166",
24            "hash": "0xb8ad1138a22a0dcc5eddca1db9aa0c731891fe60041ed6f4d9ceb737c9f1b06d",
25            "from": "0x0000000000000000000000000000000000000000",
26            "to": "0x1e6e8695fab3eb382534915ea8d7cc1d1994b152",
27            "value": null,
28            "erc721TokenId": "0x0000000000000000000000000000000000000000000000000000000000001acc",
29            "erc1155Metadata": null,
30            "tokenId": "0x0000000000000000000000000000000000000000000000000000000000001acc",
31            "asset": "DUSK",
32            "category": "erc721",
33            "rawContract": {
34                "value": null,
35                "address": "0x0beed7099af7514ccedf642cfea435731176fb02",
36                "decimal": null
37            }
38        },
39        {
40            "blockNum": "0xe4284a",
41            "uniqueId": "0x04573492a1ecb47102a2a70af190fa47f605a71f54ea62d94a1da1e225b7e157:log:345",
42            "hash": "0x04573492a1ecb47102a2a70af190fa47f605a71f54ea62d94a1da1e225b7e157",
43            "from": "0x0000000000000000000000000000000000000000",
44            "to": "0x1e6e8695fab3eb382534915ea8d7cc1d1994b152",
45            "value": null,
46            "erc721TokenId": "0x0000000000000000000000000000000000000000000000000000000000000bc0",
47            "erc1155Metadata": null,
48            "tokenId": "0x0000000000000000000000000000000000000000000000000000000000000bc0",
49            "asset": "NC",
50            "category": "erc721",
51            "rawContract": {
52                "value": null,
53                "address": "0xe9fca552b9eb110c2d170962af740725f71f5644",
54                "decimal": null
55            }
56        },
57        {
58            "blockNum": "0xe4284a",
59            "uniqueId": "0x04573492a1ecb47102a2a70af190fa47f605a71f54ea62d94a1da1e225b7e157:log:346",
60            "hash": "0x04573492a1ecb47102a2a70af190fa47f605a71f54ea62d94a1da1e225b7e157",
61            "from": "0x0000000000000000000000000000000000000000",
62            "to": "0x1e6e8695fab3eb382534915ea8d7cc1d1994b152",
63            "value": null,
64            "erc721TokenId": "0x0000000000000000000000000000000000000000000000000000000000000bc1",
65            "erc1155Metadata": null,
66            "tokenId": "0x0000000000000000000000000000000000000000000000000000000000000bc1",
67            "asset": "NC",
68            "category": "erc721",
69            "rawContract": {
70                "value": null,
71                "address": "0xe9fca552b9eb110c2d170962af740725f71f5644",
72                "decimal": null
73            }
74        }
75    ]
76}

Use Cases

Here are some common use cases for the getAssetTransfers method:

  • Asset tracking: One of the most common use cases for getAssetTransfers is to track the movement of a particular asset on the blockchain. This can be useful for businesses and organizations that need to keep track of their assets as they move on-chain.

  • Audit trails: By using getAssetTransfers to retrieve a history of all transfers of a particular asset, auditors can verify the authenticity and provenance of the asset. This can help to prevent fraud and ensure compliance with regulations.

  • Payment verification: getAssetTransfers can also be used to verify that a payment has been made or received. For example, if a company expects a payment in a particular asset, it can use this function to confirm that the payment has been transferred to its account.

Related Methods

Here are the methods related to getAssetTransfers:

  • call: Returns the result of executing the transaction using call.