🛠️ Alchemy SDKSDK V2 Methods

getTransfersForOwner - SDK

The getTransfersForOwner method gets all NFT transfers for a given owner address.

The getTransfersForOwner method gets all NFT transfers for a given owner address.

Don’t have an API key?

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

Description

getTransfersForOwner gets all NFT transfers for a given owner’s address.

Parameters

NameTypeDescriptionExample
Owner AddressstringThe owner address to get transfers for."0xe5cB067E90D5Cd1F8052B83562Ae670bA4A211a8"
Category (Optional)stringWhether to get transfers TO or FROM the owner address.TO, FROM
Options (Optional)ObjectAn optional object with the following properties: 1. contractAddresses: An array of NFT contract addresses to filter mints by. If omitted, defaults to all contract addresses. 2. tokenType: Filter mints by ERC721 vs ERC1155 contracts. If omitted, defaults to all NFTs. 3. pageKey: Optional page key from an existing response to use for pagination.{ contractAddresses: ["0x1F02bF9dDe7C79137a08B2Dd4FC964BfD2499734"], tokenType: "ERC721" }

Response

The getTransfersForOwner method returns a Promise<TransfersNftResponse> object that contains the NFT transfers for the given owner address.

The returned object has the following fields:

Property (Field)Description
nftsAn array of the transfer objects. Each transfer object contains information about the transferred NFT.
pageKey?Optional page key to use to fetch the next group of NFTs. undefined if all the transfers are already included in the response.

Each transfer object has the following fields:

Property (Field)Description
contractThe address of the NFT contract
tokenIdThe unique identifier of the NFT being transferred.
tokenTypeThe type of NFT being transferred (ERC721 or ERC1155)
titleTitle or name of the NFT.
descriptionA brief description of the NFT.
timeLastUpdatedWhen the NFT was last updated in the blockchain. Represented in ISO-8601 format.
metadataError?Holds an error message if there was an issue fetching metadata.
rawMetadata?The raw metadata fetched from the metadata URL specified by the NFT. The field is undefined if Alchemy was unable to fetch metadata.
tokenUri?URIs for accessing the NFT’s metadata blob.
mediaURIs for accessing the NFT’s media assets.
spamInfo?Detailed information on why an NFT was classified as spam. undefined if the NFT is not classified as spam.
fromThe address the NFT was sent from. For minted NFTs, this field is set to 0x0000000000000000000000000000000000000000.
toThe address the NFT was sent or minted to.
transactionHashThe transaction hash where the transfer or mint occurred.
blockNumberThe block number as a hex string of when the transfer or mint occurred.

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

Request

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

getTransfersForOwner.js
1// Imports the Alchemy SDK
2const { Alchemy, Network } = require("alchemy-sdk");
3
4// Configures the Alchemy SDK
5const config = {
6  apiKey: "demo", // 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
13// Example of using the new getTransfersForOwner method
14const main = async () => {
15  // The owner address to get transfers for
16  let address = "0xe5cB067E90D5Cd1F8052B83562Ae670bA4A211a8";
17
18  // Whether to get transfers TO or FROM the owner address. (Optional)
19  let category = "FROM";
20
21  // Additional options for the request. (Optional)
22  let options = {
23    /**
24     * List of NFT contract addresses to filter mints by. If omitted, defaults to
25     * all contract addresses.
26     */
27    contractAddresses: ["0x1F02bF9dDe7C79137a08B2Dd4FC964BfD2499734"],
28    /**
29     * Filter mints by ERC721 vs ERC1155 contracts. If omitted, defaults to all
30     * NFTs.
31     */
32    tokenType: "ERC721",
33  };
34
35  // Calling the getTransfersForOwner method
36  let transfers = await alchemy.nft.getTransfersForOwner(
37    address,
38    category,
39    options
40  );
41
42  // Logging the response to the console
43  console.log(transfers);
44};
45
46main();

Response

And here is an example of what a successful response to this request might look like:

getTransfersForOwner response
1{
2  "nfts": [
3    {
4      "contract": {
5        "address": "0x1f02bf9dde7c79137a08b2dd4fc964bfd2499734",
6        "name": "Elephants",
7        "symbol": "ELENFT",
8        "totalSupply": "7778",
9        "tokenType": "ERC721",
10        "openSea": {
11          "floorPrice": 0.022,
12          "collectionName": "3L3Phants Official",
13          "safelistRequestStatus": "verified",
14          "imageUrl": "https://i.seadn.io/gcs/files/71dfb6cacb894a713d91f493917fa1b5.png?w=500&auto=format",
15          "description": "3L3Phants NFT is a collection of 7,777 Elephants stampeding on the Ethereum blockchain. From the mind of Ic3cream and designed by World Renowned Artist Tornado Toad. Join the Herd today!\n\nEarn $NUT token in our discord now!\n\nhttps://discord.gg/3l3phantsnft",
16          "externalUrl": "http://3l3phants.io",
17          "twitterUsername": "3L3NFT",
18          "discordUrl": "https://discord.gg/3L3phantsnft",
19          "lastIngestedAt": "2023-02-02T08:11:43.000Z"
20        },
21        "contractDeployer": "0xe5cb067e90d5cd1f8052b83562ae670ba4a211a8",
22        "deployedBlockNumber": 15140845
23      },
24      "tokenId": "890",
25      "tokenType": "ERC721",
26      "title": "3L3PHANTS #890",
27      "description": "3L3Phants NFT is a collection of 7,777 Elephants stampeding on the Ethereum blockchain. Saving 3L3Phants & Wildlife one NFT at a time",
28      "timeLastUpdated": "2023-02-04T23:45:33.795Z",
29      "rawMetadata": {
30        "name": "3L3PHANTS #890",
31        "description": "3L3Phants NFT is a collection of 7,777 Elephants stampeding on the Ethereum blockchain. Saving 3L3Phants & Wildlife one NFT at a time",
32        "image": "ipfs://QmTvmGSL6cFxRyoam2vBRgVL8vjcLrzdum14K9qMQ7MP2b",
33        "attributes": [
34          {
35            "value": "Red",
36            "trait_type": "Background"
37          },
38          {
39            "value": "Glowing",
40            "trait_type": "Body"
41          },
42          {
43            "value": "Clubmasters",
44            "trait_type": "Eyes"
45          },
46          {
47            "value": "Shocked",
48            "trait_type": "Mouth"
49          },
50          {
51            "value": "Tie Dye",
52            "trait_type": "Outfit"
53          },
54          {
55            "value": "Double",
56            "trait_type": "Tusks"
57          }
58        ]
59      },
60      "tokenUri": {
61        "raw": "ipfs://QmcpMnvcmUvn3EsQ6QmV1J7QwouBKimrhbHpEV5Db9gFgy/890",
62        "gateway": "https://ipfs.io/ipfs/QmcpMnvcmUvn3EsQ6QmV1J7QwouBKimrhbHpEV5Db9gFgy/890"
63      },
64      "media": [
65        {
66          "raw": "ipfs://QmTvmGSL6cFxRyoam2vBRgVL8vjcLrzdum14K9qMQ7MP2b",
67          "gateway": "https://nft-cdn.alchemy.com/eth-mainnet/121fdb0563b1917179c9ad7d97ae081f",
68          "thumbnail": "https://res.cloudinary.com/alchemyapi/image/upload/thumbnailv2/eth-mainnet/121fdb0563b1917179c9ad7d97ae081f",
69          "format": "png",
70          "bytes": 199542
71        }
72      ],
73      "from": "0xe5cb067e90d5cd1f8052b83562ae670ba4a211a8",
74      "to": "0x84561625814e1c7e882c1ae20a9d722a8c301f04",
75      "transactionHash": "0x43ff4418ca88d94857f3b687e8ac7450e107c2a36517e8d59a5308dba4acec94",
76      "blockNumber": "0xec8125"
77    },
78    {
79      "contract": {
80        "address": "0x1f02bf9dde7c79137a08b2dd4fc964bfd2499734",
81        "name": "Elephants",
82        "symbol": "ELENFT",
83        "totalSupply": "7778",
84        "tokenType": "ERC721",
85        "openSea": {
86          "floorPrice": 0.022,
87          "collectionName": "3L3Phants Official",
88          "safelistRequestStatus": "verified",
89          "imageUrl": "https://i.seadn.io/gcs/files/71dfb6cacb894a713d91f493917fa1b5.png?w=500&auto=format",
90          "description": "3L3Phants NFT is a collection of 7,777 Elephants stampeding on the Ethereum blockchain. From the mind of Ic3cream and designed by World Renowned Artist Tornado Toad. Join the Herd today!\n\nEarn $NUT token in our discord now!\n\nhttps://discord.gg/3l3phantsnft",
91          "externalUrl": "http://3l3phants.io",
92          "twitterUsername": "3L3NFT",
93          "discordUrl": "https://discord.gg/3L3phantsnft",
94          "lastIngestedAt": "2023-02-02T08:11:43.000Z"
95        },
96        "contractDeployer": "0xe5cb067e90d5cd1f8052b83562ae670ba4a211a8",
97        "deployedBlockNumber": 15140845
98      },
99      "tokenId": "3990",
100      "tokenType": "ERC721",
101      "title": "3L3PHANTS #3990",
102      "description": "3L3Phants NFT is a collection of 7,777 Elephants stampeding on the Ethereum blockchain. Saving 3L3Phants & Wildlife one NFT at a time",
103      "timeLastUpdated": "2023-01-07T22:53:31.448Z",
104      "rawMetadata": {
105        "name": "3L3PHANTS #3990",
106        "description": "3L3Phants NFT is a collection of 7,777 Elephants stampeding on the Ethereum blockchain. Saving 3L3Phants & Wildlife one NFT at a time",
107        "image": "ipfs://QmaL3UbrR8T1tz7j8SuYmQxkQJoPXYZeU49YC5DCHphKDg",
108        "attributes": [
109          {
110            "value": "Pink Checkerboard",
111            "trait_type": "Background"
112          },
113          {
114            "value": "Mammoth",
115            "trait_type": "Body"
116          },
117          {
118            "value": "Mad",
119            "trait_type": "Eyes"
120          },
121          {
122            "value": "Tennis Ball",
123            "trait_type": "Item"
124          },
125          {
126            "value": "Lips Open",
127            "trait_type": "Mouth"
128          },
129          {
130            "value": "Green Doctor",
131            "trait_type": "Outfit"
132          },
133          {
134            "value": "Nubs",
135            "trait_type": "Tusks"
136          }
137        ]
138      },
139      "tokenUri": {
140        "raw": "ipfs://QmcpMnvcmUvn3EsQ6QmV1J7QwouBKimrhbHpEV5Db9gFgy/3990",
141        "gateway": "https://ipfs.io/ipfs/QmcpMnvcmUvn3EsQ6QmV1J7QwouBKimrhbHpEV5Db9gFgy/3990"
142      },
143      "media": [
144        {
145          "raw": "ipfs://QmaL3UbrR8T1tz7j8SuYmQxkQJoPXYZeU49YC5DCHphKDg",
146          "gateway": "https://nft-cdn.alchemy.com/eth-mainnet/8e8706cbd7f6f2b46576dd386410b805",
147          "thumbnail": "https://res.cloudinary.com/alchemyapi/image/upload/thumbnailv2/eth-mainnet/8e8706cbd7f6f2b46576dd386410b805",
148          "format": "png",
149          "bytes": 198447
150        }
151      ],
152      "from": "0xe5cb067e90d5cd1f8052b83562ae670ba4a211a8",
153      "to": "0x6a3623db71c1b3442a94e3fd4655334b48114693",
154      "transactionHash": "0x13f33287ac95893e06cda2cd30c08003808ac46867382d8c92e1c864e4895ec6",
155      "blockNumber": "0xec8131"
156    }
157  ]
158}

Use Cases

Some of the use cases for getTransfersForOwner are:

  • NFT Marketplace: An NFT marketplace could use the API to retrieve all the NFT transfers for a particular owner and display them on their website for the owner to see their NFT collection and transactions history.

  • NFT Portfolio Tracking: An individual or a company could use the API to track all the NFT transfers to and from their address, and keep a record of their NFT portfolio.

  • NFT Analytics: An NFT analytics platform could use the API to gather data on NFT transfers, and analyze the NFT market trends and patterns.

Related Methods

Here are the methods related to getTransfersForOwner: