Alchemy Login

getTransfersForOwner - SDK

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
ownerstringThe owner address to get transfers for."0xe5cB067E90D5Cd1F8052B83562Ae670bA4A211a8"
category?stringWhether to get transfers TO or FROM the owner address.TO, FROM
optionsObjectAn 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:

PropertyTypeDescription
nftsarray of objectsAn array of the transfer objects. Each transfer object contains information about the transferred NFT.
pageKey?stringOptional 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:

PropertyTypeDescription
contractobjectThe 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?: numberThe 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.
tokenIdstringThe unique identifier of the token. This could be in hexadecimal or decimal format.
tokenTypestringThe type of NFT, e.g.,ERC721, ERC1155, UNKNOWN
namestringThe NFT name.
descriptionstringThe NFT description.
timeLastUpdatedstringWhen the NFT was last updated in the blockchain. Represented in ISO-8601 format.
rawobjectThe 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.
tokenUristringURIs for accessing the NFT's metadata blob.
imageobjectMedia 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.
acquiredAtobjectTime 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.
collectionobjectCollection 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.
mintobjectMint 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.
fromstringThe address the NFT was sent from. For minted NFTs, this field is set to 0x0000000000000000000000000000000000000000.
tostringThe address the NFT was sent or minted to.
transactionHashstringThe transaction hash where the transfer or mint occurred.
blockNumberstringThe 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

yarn add alchemy-sdk@latest

Request

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

// Imports the Alchemy SDK
const { Alchemy, Network } = require("alchemy-sdk");

// Configures the Alchemy SDK
const config = {
  apiKey: "demo", // Replace with your API key
  network: Network.ETH_MAINNET, // Replace with your network
};

// Creates an Alchemy object instance with the config to use for making requests
const alchemy = new Alchemy(config);

// Example of using the new getTransfersForOwner method
const main = async () => {
  // The owner address to get transfers for
  let address = "0xe5cB067E90D5Cd1F8052B83562Ae670bA4A211a8";

  // Whether to get transfers TO or FROM the owner address. (Optional)
  let category = "FROM";

  // Additional options for the request. (Optional)
  let options = {
    /**
     * List of NFT contract addresses to filter mints by. If omitted, defaults to
     * all contract addresses.
     */
    contractAddresses: ["0x1F02bF9dDe7C79137a08B2Dd4FC964BfD2499734"],
    /**
     * Filter mints by ERC721 vs ERC1155 contracts. If omitted, defaults to all
     * NFTs.
     */
    tokenType: "ERC721",
  };

  // Calling the getTransfersForOwner method
  let transfers = await alchemy.nft.getTransfersForOwner(
    address,
    category,
    options
  );

  // Logging the response to the console
  console.log(transfers);
};

main();

Response

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

{
    "nfts": [
        {
            "contract": {
                "address": "0x1F02bF9dDe7C79137a08B2Dd4FC964BfD2499734",
                "name": "Elephants",
                "symbol": "ELENFT",
                "totalSupply": "7778",
                "tokenType": "ERC721",
                "contractDeployer": "0xe5cB067E90D5Cd1F8052B83562Ae670bA4A211a8",
                "deployedBlockNumber": 15140845,
                "openSeaMetadata": {
                    "floorPrice": 0.0032,
                    "collectionName": "3L3Phants Official",
                    "collectionSlug": "3l3phants-official",
                    "safelistRequestStatus": "verified",
                    "imageUrl": "https://i.seadn.io/gcs/files/71dfb6cacb894a713d91f493917fa1b5.png?w=500&auto=format",
                    "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",
                    "externalUrl": "http://3l3phants.io",
                    "twitterUsername": "3L3NFT",
                    "discordUrl": "https://discord.gg/3L3phantsnft",
                    "bannerImageUrl": "https://i.seadn.io/gcs/files/1667bbb67e548917820271ee2430bb35.png?w=500&auto=format",
                    "lastIngestedAt": "2023-09-19T22:06:03.000Z"
                },
                "spamClassifications": []
            },
            "tokenId": "890",
            "tokenType": "ERC721",
            "name": "3L3PHANTS #890",
            "description": "3L3Phants NFT is a collection of 7,777 Elephants stampeding on the Ethereum blockchain. Saving 3L3Phants & Wildlife one NFT at a time",
            "tokenUri": "https://ipfs.io/ipfs/QmcpMnvcmUvn3EsQ6QmV1J7QwouBKimrhbHpEV5Db9gFgy/890",
            "image": {
                "cachedUrl": "https://nft-cdn.alchemy.com/eth-mainnet/121fdb0563b1917179c9ad7d97ae081f",
                "thumbnailUrl": "https://res.cloudinary.com/alchemyapi/image/upload/thumbnailv2/eth-mainnet/121fdb0563b1917179c9ad7d97ae081f",
                "pngUrl": "https://res.cloudinary.com/alchemyapi/image/upload/convert-png/eth-mainnet/121fdb0563b1917179c9ad7d97ae081f",
                "contentType": "image/png",
                "size": 199542,
                "originalUrl": "https://ipfs.io/ipfs/QmTvmGSL6cFxRyoam2vBRgVL8vjcLrzdum14K9qMQ7MP2b"
            },
            "raw": {
                "tokenUri": "ipfs://QmcpMnvcmUvn3EsQ6QmV1J7QwouBKimrhbHpEV5Db9gFgy/890",
                "metadata": {
                    "name": "3L3PHANTS #890",
                    "description": "3L3Phants NFT is a collection of 7,777 Elephants stampeding on the Ethereum blockchain. Saving 3L3Phants & Wildlife one NFT at a time",
                    "image": "ipfs://QmTvmGSL6cFxRyoam2vBRgVL8vjcLrzdum14K9qMQ7MP2b",
                    "attributes": [
                        {
                            "value": "Red",
                            "trait_type": "Background"
                        },
                        {
                            "value": "Double",
                            "trait_type": "Tusks"
                        }
                    ]
                }
            },
            "collection": {
                "name": "3L3Phants Official",
                "slug": "3l3phants-official",
                "externalUrl": "http://3l3phants.io",
                "bannerImageUrl": "https://i.seadn.io/gcs/files/1667bbb67e548917820271ee2430bb35.png?w=500&auto=format"
            },
            "mint": {
                "mintAddress": "0xe5cb067e90d5cd1f8052b83562ae670ba4a211a8",
                "blockNumber": 15143441,
                "timestamp": "2022-07-14T22:17:44Z",
                "transactionHash": "0x317dfdacec0ae4cbe0a1f7ee394f9cc7c6d4ae9985a5202fcfef28b3a19ce899"
            },
            "timeLastUpdated": "2023-08-13T03:40:39.232Z",
            "from": "0xe5cb067e90d5cd1f8052b83562ae670ba4a211a8",
            "to": "0x84561625814e1c7e882c1ae20a9d722a8c301f04",
            "transactionHash": "0x43ff4418ca88d94857f3b687e8ac7450e107c2a36517e8d59a5308dba4acec94",
            "blockNumber": "0xec8125"
        },
        {
            "contract": {
                "address": "0x1F02bF9dDe7C79137a08B2Dd4FC964BfD2499734",
                "name": "Elephants",
                "symbol": "ELENFT",
                "totalSupply": "7778",
                "tokenType": "ERC721",
                "contractDeployer": "0xe5cB067E90D5Cd1F8052B83562Ae670bA4A211a8",
                "deployedBlockNumber": 15140845,
                "openSeaMetadata": {
                    "floorPrice": 0.0032,
                    "collectionName": "3L3Phants Official",
                    "collectionSlug": "3l3phants-official",
                    "safelistRequestStatus": "verified",
                    "imageUrl": "https://i.seadn.io/gcs/files/71dfb6cacb894a713d91f493917fa1b5.png?w=500&auto=format",
                    "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",
                    "externalUrl": "http://3l3phants.io",
                    "twitterUsername": "3L3NFT",
                    "discordUrl": "https://discord.gg/3L3phantsnft",
                    "bannerImageUrl": "https://i.seadn.io/gcs/files/1667bbb67e548917820271ee2430bb35.png?w=500&auto=format",
                    "lastIngestedAt": "2023-09-19T22:06:03.000Z"
                },
                "spamClassifications": []
            },
            "tokenId": "3990",
            "tokenType": "ERC721",
            "name": "3L3PHANTS #3990",
            "description": "3L3Phants NFT is a collection of 7,777 Elephants stampeding on the Ethereum blockchain. Saving 3L3Phants & Wildlife one NFT at a time",
            "tokenUri": "https://alchemy.mypinata.cloud/ipfs/QmcpMnvcmUvn3EsQ6QmV1J7QwouBKimrhbHpEV5Db9gFgy/3990",
            "image": {
                "cachedUrl": "https://nft-cdn.alchemy.com/eth-mainnet/8e8706cbd7f6f2b46576dd386410b805",
                "thumbnailUrl": "https://res.cloudinary.com/alchemyapi/image/upload/thumbnailv2/eth-mainnet/8e8706cbd7f6f2b46576dd386410b805",
                "pngUrl": "https://res.cloudinary.com/alchemyapi/image/upload/convert-png/eth-mainnet/8e8706cbd7f6f2b46576dd386410b805",
                "contentType": "image/png",
                "size": 198447,
                "originalUrl": "https://ipfs.io/ipfs/QmaL3UbrR8T1tz7j8SuYmQxkQJoPXYZeU49YC5DCHphKDg"
            },
            "raw": {
                "tokenUri": "ipfs://QmcpMnvcmUvn3EsQ6QmV1J7QwouBKimrhbHpEV5Db9gFgy/3990",
                "metadata": {
                    "name": "3L3PHANTS #3990",
                    "description": "3L3Phants NFT is a collection of 7,777 Elephants stampeding on the Ethereum blockchain. Saving 3L3Phants & Wildlife one NFT at a time",
                    "image": "ipfs://QmaL3UbrR8T1tz7j8SuYmQxkQJoPXYZeU49YC5DCHphKDg",
                    "attributes": [
                        {
                            "value": "Pink Checkerboard",
                            "trait_type": "Background"
                        },
                        {
                            "value": "Nubs",
                            "trait_type": "Tusks"
                        }
                    ]
                }
            },
            "collection": {
                "name": "3L3Phants Official",
                "slug": "3l3phants-official",
                "externalUrl": "http://3l3phants.io",
                "bannerImageUrl": "https://i.seadn.io/gcs/files/1667bbb67e548917820271ee2430bb35.png?w=500&auto=format"
            },
            "mint": {
                "mintAddress": "0xe5cb067e90d5cd1f8052b83562ae670ba4a211a8",
                "blockNumber": 15214264,
                "timestamp": "2022-07-25T22:02:43Z",
                "transactionHash": "0x343e4697e0e834acb61c23268a63ddddb29e29ce6bcaf652b08430f7c0fdc934"
            },
            "timeLastUpdated": "2023-02-28T17:51:29.181Z",
            "from": "0xe5cb067e90d5cd1f8052b83562ae670ba4a211a8",
            "to": "0x6a3623db71c1b3442a94e3fd4655334b48114693",
            "transactionHash": "0x13f33287ac95893e06cda2cd30c08003808ac46867382d8c92e1c864e4895ec6",
            "blockNumber": "0xec8131"
        }
    ]
}

Code Sandbox

You can test the getTransfersForOwner method using the code sandbox below:

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:

ReadMe