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
Name | Type | Description | Example |
---|---|---|---|
owner | string | The owner address to get transfers for. | "0xe5cB067E90D5Cd1F8052B83562Ae670bA4A211a8" |
category? | string | Whether to get transfers TO or FROM the owner address. | TO , FROM |
options | Object | An 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 | Type | Description |
---|---|---|
nfts | array of objects | An array of the transfer objects. Each transfer object contains information about the transferred NFT. |
pageKey? | string | Optional page key to use to fetch the next group of NFTs. undefined if all the transfers are already included in the response. |
nfts
properties
Each nfts
transfer object has the following fields:
Property | Type | Description |
---|---|---|
contract | object | The NFT’s underlying contract and relevant contract metadata. Parameters in the contract include: 1. address : string The address of the NFT contract. 2. tokenType : object The type of the token in the contract 3. name : string The name of the contract. 4. symbol : string The symbol of the contract. 5. totalSupply?: string The number of NFTs in the contract as an integer string. This field is only available on ERC-721 contracts. 6. openSeaMetadata: object OpenSea’s metadata for the contract. 7. contractDeployer?: string The address that deployed the NFT contract. 8. deployedBlockNumber?: number The block number the NFT contract deployed in. 9. isSpam : boolean Whether the NFT contract is marked as spam. 10. spamClassifications : array Potential reasons why an NFT Contract was classified as spam. |
tokenId | string | The unique identifier of the token. This could be in hexadecimal or decimal format. |
tokenType | string | The type of NFT, e.g.,ERC721 , ERC1155 , UNKNOWN |
name | string | The NFT name. |
description | string | The NFT description. |
timeLastUpdated | string | When the NFT was last updated in the blockchain. Represented in ISO-8601 format. |
raw | object | The raw metadata for the NFT based on the metadata URI on the NFT contract. 1. tokenUri?: string : The raw token URI on the NFT contract. 2. metadata: string : The raw metadata parsed from the raw token URI. 3. error?: string : Error message if the raw metadata could not be fetched. |
tokenUri | string | URIs for accessing the NFT’s metadata blob. |
image | object | Media URLs and information for the NFT. Parameters in this object include: 1. cachedUrl: string : URL of the image stored in Alchemy’s cache. 2. thumbnailUrl: string : URL of a thumbnail-sized image. 3. pngUrl: string : URL of the image in png format. 4. contentType: string : The type of the media image. |
acquiredAt | object | Time at which the user most recently acquired the NFT. Only available when specifying orderBy: NftOrdering.TRANSFERTIME in the request. 1. blockTimestamp?: string : Timestamp of the block at which an NFT was last acquired. 2. blockNumber?: number : Block number of the block at which an NFT was last acquired. |
collection | object | Collection metadata for the NFT, if available. Parameters include: 1. name: string : The name of the collection. 2. slug?: string : The OpenSea human-readable slug of the collection. 3. externalUrl?: string : The external URL for the collection. 4. bannerImageUrl?: string : The banner image URL for the collection. |
mint | object | Mint information for the NFT. Parameters include: 1. mintAddress?: string : The address that the NFT was minted to. 2. blockNumber?: number : The block number that the NFT was minted on. 3. timestamp?: string : The timestamp the NFT was minted on. 4. transactionHash?: string : The transaction hash of the transaction that minted the NFT. |
from | string | The address the NFT was sent from. For minted NFTs, this field is set to 0x0000000000000000000000000000000000000000 . |
to | string | The address the NFT was sent or minted to. |
transactionHash | string | The transaction hash where the transfer or mint occurred. |
blockNumber | string | The block number as a hex string of when the transfer or mint occurred. |
Example Request and Response
Prerequisite: You must 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 getTransfersForOwner
request using the Alchemy SDK:
1 // Imports the Alchemy SDK 2 const { Alchemy, Network } = require("alchemy-sdk"); 3 4 // Configures the Alchemy SDK 5 const 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 11 const alchemy = new Alchemy(config); 12 13 // Example of using the new getTransfersForOwner method 14 const 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 46 main();
Response
And here is an example of what a successful response to this request might look like:
1 { 2 "nfts": [ 3 { 4 "contract": { 5 "address": "0x1F02bF9dDe7C79137a08B2Dd4FC964BfD2499734", 6 "name": "Elephants", 7 "symbol": "ELENFT", 8 "totalSupply": "7778", 9 "tokenType": "ERC721", 10 "contractDeployer": "0xe5cB067E90D5Cd1F8052B83562Ae670bA4A211a8", 11 "deployedBlockNumber": 15140845, 12 "openSeaMetadata": { 13 "floorPrice": 0.0032, 14 "collectionName": "3L3Phants Official", 15 "collectionSlug": "3l3phants-official", 16 "safelistRequestStatus": "verified", 17 "imageUrl": "https://i.seadn.io/gcs/files/71dfb6cacb894a713d91f493917fa1b5.png?w=500&auto=format", 18 "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", 19 "externalUrl": "http://3l3phants.io", 20 "twitterUsername": "3L3NFT", 21 "discordUrl": "https://discord.gg/3L3phantsnft", 22 "bannerImageUrl": "https://i.seadn.io/gcs/files/1667bbb67e548917820271ee2430bb35.png?w=500&auto=format", 23 "lastIngestedAt": "2023-09-19T22:06:03.000Z" 24 }, 25 "spamClassifications": [] 26 }, 27 "tokenId": "890", 28 "tokenType": "ERC721", 29 "name": "3L3PHANTS #890", 30 "description": "3L3Phants NFT is a collection of 7,777 Elephants stampeding on the Ethereum blockchain. Saving 3L3Phants & Wildlife one NFT at a time", 31 "tokenUri": "https://ipfs.io/ipfs/QmcpMnvcmUvn3EsQ6QmV1J7QwouBKimrhbHpEV5Db9gFgy/890", 32 "image": { 33 "cachedUrl": "https://nft-cdn.alchemy.com/eth-mainnet/121fdb0563b1917179c9ad7d97ae081f", 34 "thumbnailUrl": "https://res.cloudinary.com/alchemyapi/image/upload/thumbnailv2/eth-mainnet/121fdb0563b1917179c9ad7d97ae081f", 35 "pngUrl": "https://res.cloudinary.com/alchemyapi/image/upload/convert-png/eth-mainnet/121fdb0563b1917179c9ad7d97ae081f", 36 "contentType": "image/png", 37 "size": 199542, 38 "originalUrl": "https://ipfs.io/ipfs/QmTvmGSL6cFxRyoam2vBRgVL8vjcLrzdum14K9qMQ7MP2b" 39 }, 40 "raw": { 41 "tokenUri": "ipfs://QmcpMnvcmUvn3EsQ6QmV1J7QwouBKimrhbHpEV5Db9gFgy/890", 42 "metadata": { 43 "name": "3L3PHANTS #890", 44 "description": "3L3Phants NFT is a collection of 7,777 Elephants stampeding on the Ethereum blockchain. Saving 3L3Phants & Wildlife one NFT at a time", 45 "image": "ipfs://QmTvmGSL6cFxRyoam2vBRgVL8vjcLrzdum14K9qMQ7MP2b", 46 "attributes": [ 47 { 48 "value": "Red", 49 "trait_type": "Background" 50 }, 51 { 52 "value": "Double", 53 "trait_type": "Tusks" 54 } 55 ] 56 } 57 }, 58 "collection": { 59 "name": "3L3Phants Official", 60 "slug": "3l3phants-official", 61 "externalUrl": "http://3l3phants.io", 62 "bannerImageUrl": "https://i.seadn.io/gcs/files/1667bbb67e548917820271ee2430bb35.png?w=500&auto=format" 63 }, 64 "mint": { 65 "mintAddress": "0xe5cb067e90d5cd1f8052b83562ae670ba4a211a8", 66 "blockNumber": 15143441, 67 "timestamp": "2022-07-14T22:17:44Z", 68 "transactionHash": "0x317dfdacec0ae4cbe0a1f7ee394f9cc7c6d4ae9985a5202fcfef28b3a19ce899" 69 }, 70 "timeLastUpdated": "2023-08-13T03:40:39.232Z", 71 "from": "0xe5cb067e90d5cd1f8052b83562ae670ba4a211a8", 72 "to": "0x84561625814e1c7e882c1ae20a9d722a8c301f04", 73 "transactionHash": "0x43ff4418ca88d94857f3b687e8ac7450e107c2a36517e8d59a5308dba4acec94", 74 "blockNumber": "0xec8125" 75 }, 76 { 77 "contract": { 78 "address": "0x1F02bF9dDe7C79137a08B2Dd4FC964BfD2499734", 79 "name": "Elephants", 80 "symbol": "ELENFT", 81 "totalSupply": "7778", 82 "tokenType": "ERC721", 83 "contractDeployer": "0xe5cB067E90D5Cd1F8052B83562Ae670bA4A211a8", 84 "deployedBlockNumber": 15140845, 85 "openSeaMetadata": { 86 "floorPrice": 0.0032, 87 "collectionName": "3L3Phants Official", 88 "collectionSlug": "3l3phants-official", 89 "safelistRequestStatus": "verified", 90 "imageUrl": "https://i.seadn.io/gcs/files/71dfb6cacb894a713d91f493917fa1b5.png?w=500&auto=format", 91 "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", 92 "externalUrl": "http://3l3phants.io", 93 "twitterUsername": "3L3NFT", 94 "discordUrl": "https://discord.gg/3L3phantsnft", 95 "bannerImageUrl": "https://i.seadn.io/gcs/files/1667bbb67e548917820271ee2430bb35.png?w=500&auto=format", 96 "lastIngestedAt": "2023-09-19T22:06:03.000Z" 97 }, 98 "spamClassifications": [] 99 }, 100 "tokenId": "3990", 101 "tokenType": "ERC721", 102 "name": "3L3PHANTS #3990", 103 "description": "3L3Phants NFT is a collection of 7,777 Elephants stampeding on the Ethereum blockchain. Saving 3L3Phants & Wildlife one NFT at a time", 104 "tokenUri": "https://alchemy.mypinata.cloud/ipfs/QmcpMnvcmUvn3EsQ6QmV1J7QwouBKimrhbHpEV5Db9gFgy/3990", 105 "image": { 106 "cachedUrl": "https://nft-cdn.alchemy.com/eth-mainnet/8e8706cbd7f6f2b46576dd386410b805", 107 "thumbnailUrl": "https://res.cloudinary.com/alchemyapi/image/upload/thumbnailv2/eth-mainnet/8e8706cbd7f6f2b46576dd386410b805", 108 "pngUrl": "https://res.cloudinary.com/alchemyapi/image/upload/convert-png/eth-mainnet/8e8706cbd7f6f2b46576dd386410b805", 109 "contentType": "image/png", 110 "size": 198447, 111 "originalUrl": "https://ipfs.io/ipfs/QmaL3UbrR8T1tz7j8SuYmQxkQJoPXYZeU49YC5DCHphKDg" 112 }, 113 "raw": { 114 "tokenUri": "ipfs://QmcpMnvcmUvn3EsQ6QmV1J7QwouBKimrhbHpEV5Db9gFgy/3990", 115 "metadata": { 116 "name": "3L3PHANTS #3990", 117 "description": "3L3Phants NFT is a collection of 7,777 Elephants stampeding on the Ethereum blockchain. Saving 3L3Phants & Wildlife one NFT at a time", 118 "image": "ipfs://QmaL3UbrR8T1tz7j8SuYmQxkQJoPXYZeU49YC5DCHphKDg", 119 "attributes": [ 120 { 121 "value": "Pink Checkerboard", 122 "trait_type": "Background" 123 }, 124 { 125 "value": "Nubs", 126 "trait_type": "Tusks" 127 } 128 ] 129 } 130 }, 131 "collection": { 132 "name": "3L3Phants Official", 133 "slug": "3l3phants-official", 134 "externalUrl": "http://3l3phants.io", 135 "bannerImageUrl": "https://i.seadn.io/gcs/files/1667bbb67e548917820271ee2430bb35.png?w=500&auto=format" 136 }, 137 "mint": { 138 "mintAddress": "0xe5cb067e90d5cd1f8052b83562ae670ba4a211a8", 139 "blockNumber": 15214264, 140 "timestamp": "2022-07-25T22:02:43Z", 141 "transactionHash": "0x343e4697e0e834acb61c23268a63ddddb29e29ce6bcaf652b08430f7c0fdc934" 142 }, 143 "timeLastUpdated": "2023-02-28T17:51:29.181Z", 144 "from": "0xe5cb067e90d5cd1f8052b83562ae670ba4a211a8", 145 "to": "0x6a3623db71c1b3442a94e3fd4655334b48114693", 146 "transactionHash": "0x13f33287ac95893e06cda2cd30c08003808ac46867382d8c92e1c864e4895ec6", 147 "blockNumber": "0xec8131" 148 } 149 ] 150 }
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 transaction 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
:
-
getMintedNfts
: Returns all the NFTs minted by a specified owner address. -
getTransfersForContract
: Returns all NFT transfers for a given NFT contract address.