How to Get all NFT Transactions by an Address

A few quick reasons why you’d want to get NFT transfer history by an address:

• Building an NFT activity page for all transfers/sales.
• Calculating the volume of NFTs traded by an address.

While this type of data cannot be easily queried via the Ethereum API Quickstart um API], Alchemy builds higher-level Enhanced APIs Overview to make Web3 interactions much easier.

In this tutorial, we’ll be leveraging Alchemy’s Transfers API(alchemy_getAssetTransfers) to query all NFT transfers by an address.

What happens when NFTs are transacted?

Behind the scenes, whenever an NFT undergoes an on-chain sale or swap, any associated smart contract calls will emit a standard transfer event since the asset is ultimately being transferred from one account to another.

Since we can specifically filter for transfer events using the Transfers API, we can easily fetch NFT transactions with the right combination of filter parameters!

How to get NFT Transaction History

In order to fetch NFT transaction history by a given address, we’ll need to specify a few things in our alchemy_getAssetTransfers request:

• fromAddress: where the NFT transaction originated from when fetching NFT transaction history originating from an address we use this
• toAddress: the NFT recipient’s address when fetching NFT transaction history by recipient address we use this
• fromBlock: the starting time range we want to fetch NFT transactions over (defaults to latest)
• toBlock: the ending time range we want to fetch NFT transactions over (defaults to latest)
• category: the type of transfer events we care about, in our case we want to see NFTs which are ERC721 and ERC1155 events

Once we’ve specified these inputs we can send the request!

Example: How to get NFT Transaction History Originating From An Address

To demonstrate how to get the NFT transaction history from an address we’re going to walk through an example using the address 0x5c43B1eD97e52d009611D89b74fA829FE4ac56b1 and getting all NFT transaction events from it spanning block 0 to the latest.

Follow along with the code examples below to make the request.

1
// nft-tx-history.js
2
3
const main = async () => {
4
  // Address we want to get NFT transaction history from
5
  const fromAddress = "0x5c43B1eD97e52d009611D89b74fA829FE4ac56b1";
6
7
  // Replace with your Alchemy API key:
8
  const apiKey = "<-- ALCHEMY APP API KEY -->";
9
10
  const requestBody = {
11
    jsonrpc: "2.0",
12
    id: 0,
13
    method: "alchemy_getAssetTransfers",
14
    params: [
15
      {
16
        fromBlock: "0x0",
17
        fromAddress: fromAddress,
18
        excludeZeroValue: true,
19
        category: ["erc721", "erc1155"]
20
      }
21
    ]
22
  };
23
24
  try {
25
    const response = await fetch(`https://eth-mainnet.g.alchemy.com/v2/${apiKey}`, {
26
      method: 'POST',
27
      headers: { 'Content-Type': 'application/json' },
28
      body: JSON.stringify(requestBody)
29
    });
30
31
    const data = await response.json();
32
33
    // Print contract address and tokenId for each NFT transaction:
34
    for (const events of data.result.transfers) {
35
      if (events.erc1155Metadata == null) {
36
        console.log("ERC-721 Token Transferred: ID-", events.tokenId, "Contract-", events.rawContract.address);
37
      } else {
38
        for (const erc1155 of events.erc1155Metadata) {
39
          console.log("ERC-1155 Token Transferred: ID-", erc1155.tokenId, "Contract-", events.rawContract.address);
40
        }
41
      }
42
    }
43
  } catch (error) {
44
    console.error('Error:', error);
45
  }
46
};
47
48
main();

Run this script by calling:

$
node nft-tx-history.js

How to process the API response

Now that we have made a query and can see the response, let’s learn how to handle the returned data.

Raw API Response:

Without parsing the response, we have a command-line print-out that looks like this:

1
{
2
  [
3
    {
4
      "blockNum": "0xc75329",
5
      "hash": "0xd89b54cb5aca6f501d43ee3363dcc892d31d1c185c9059c22d686ca0a1b93314",
6
      "from": "0x0000000000000000000000000000000000000000",
7
      "to": "0x5c43b1ed97e52d009611d89b74fa829fe4ac56b1",
8
      "value": null,
9
      "erc721TokenId": "0x0000000000000000000000000000000000000000000000000000000000000012",
10
      "erc1155Metadata": null,
11
      "tokenId": "0x0000000000000000000000000000000000000000000000000000000000000012",
12
      "asset": "BURN",
13
      "category": "erc721",
14
      "rawContract": {
15
        "value": null,
16
        "address": "0x18a808dd312736fc75eb967fc61990af726f04e4",
17
        "decimal": null
18
      }
19
    },
20
    ...
21
    {
22
      "blockNum": "0xd8315a",
23
      "hash": "0x270aa9026d69b0924341e0ce60b24182f1f2af8a4bcc752b8e65595bdeca565f",
24
      "from": "0x0000000000000000000000000000000000000000",
25
      "to": "0x5c43b1ed97e52d009611d89b74fa829fe4ac56b1",
26
      "value": null,
27
      "erc721TokenId": "0x00000000000000000000000000000000000000000000000000000000000000fb",
28
      "erc1155Metadata": null,
29
      "tokenId": "0x00000000000000000000000000000000000000000000000000000000000000fb",
30
      "asset": null,
31
      "category": "erc721",
32
      "rawContract": {
33
        "value": null,
34
        "address": "0x947600ad1ad2fadf88faf7d30193d363208fc76d",
35
        "decimal": null
36
      }
37
    }
38
  ]
39
}

Understanding API Response:

Below are each of the components in our response.

• blockNum: the block number where an NFT transaction occurred, in hex

• hash: the transaction hash of NFT transaction

• from: where the transaction originated from

• to: where the NFT was received

• value: the amount of ETH transferred, should always be null in our case since we’re only looking at NFT transfer events which typically only transfer the NFT and not ETH

• erc721TokenId: the ERC721 token ID. null if not an ERC721 token transfer.

• erc1155Metadata: a list of objects containing the ERC1155 tokenId and value. null if not an ERC1155 transfer

• tokenId: the token ID for ERC721 tokens or other NFT token standards

• asset: ETH or the token’s symbol. null if not defined in the contract and not available from other sources.

• rawContract

  • value: null since we’re looking at ERC721 & ERC1155 transfer
  • address: NFT contract address
  • decimal: null

Printing out the token type, tokenId and contract address

There’s lots of information we can pull from this response. One example you may be interested in displaying are: NFT contract standard (ERC721 or ERC1155), contractAddress, and tokenId

With our queried response saved as a JSON object, we can index through the transfers. In particular, we first access the transfers list and then iterate across a few key parameters: erc1155Metadata , tokenId, and rawContract.

The steps we want to take are:

1. Loop through all transfers in the result

2. Check whether the returned transfer is ERC1155 or not

   1. If so, loop through tokens within ERC1155
      1. print tokenId and address for each
   2. If not, assume transfer is ERC721
      1. print tokenID of contract and address

1
for (const events of data.result.transfers) {
2
      if (events.erc1155Metadata == null) {
3
        console.log("ERC-721 Token Transferred: ID-", events.tokenId, "Contract-", events.rawContract.address);
4
      }
5
      else{
6
        for (const erc1155 of events.erc1155Metadata) {
7
        console.log("ERC-1155 Token Transferred: ID-", erc1155.tokenId, "Contract-", events.rawContract.address);
8
        }
9
      }
10
  }

If you followed along thus far, your response should look like the following:

1
ERC-721 Token Transferred: ID- 0x000000000000000000000000000000000000000000000000000000000000034a Contract- 0x7ecb204fed7e386386cab46a1fcb823ec5067ad5
2
ERC-721 Token Transferred: ID- 0x0000000000000000000000000000000000000000000000000000000000000349 Contract- 0x7ecb204fed7e386386cab46a1fcb823ec5067ad5
3
ERC-721 Token Transferred: ID- 0x0000000000000000000000000000000000000000000000000000000000000348 Contract- 0x7ecb204fed7e386386cab46a1fcb823ec5067ad5
4
ERC-721 Token Transferred: ID- 0x0000000000000000000000000000000000000000000000000000000000000b6e Contract- 0x72d47d4d24018ec9048a9b0ae226f1c525b7e794

And that’s it! You’ve now learned how to fetch NFT transaction history given an address on Ethereum! If you enjoyed this tutorial, give us a tweet @Alchemy! (Or give the author @crypt0zeke some love!)

Also, join our Discord server to meet other blockchain devs, builders, and entrepreneurs!