Getting NFTs for an Address
#
Learn how to retrieve NFT data for a specific wallet addressThis guide will cover how to retrieve NFT data for an ownerAddress
and then dive deeper into how to get details for specific NFTs.
The following are starter examples, but there are many different possibilities with the API.
note
GraphiQL Playground: https://api.zora.co/graphql
Demo Address: jacob.eth
or 0x17cd072cBd45031EFc21Da538c783E0ed3b25DCc
*The API is ENS compatible, meaning that ownerAddress
can be an ENS name.
#
NFT BalanceLet's get started by looking at jacob.eth
as our example address.
We can use the tokens
query and set the ownerAddress
.
- Query
- Response
query JacobsNFTs { tokens(networks: [{network: ETHEREUM, chain: MAINNET}], pagination: {limit: 3}, where: {ownerAddresses: "jacob.eth"}) { nodes { token { collectionAddress tokenId name owner image { url } metadata } } }}
{ "data": { "tokens": { "nodes": [ { "token": { "collectionAddress": "0x8d04a8c79ceb0889bdd12acdf3fa9d207ed3ff63", "tokenId": "393", "name": "#393 - Wave Logo", "owner": "0x17cd072cbd45031efc21da538c783e0ed3b25dcc", "image": { "url": "https://api.blitmap.com/v1/png/393" }, "metadata": { "image": "https://api.blitmap.com/v1/png/393", "name": "#393 - Wave Logo", "description": "Blitmap is a community crafted art collection and universe. All data is completely on chain.\n\n[blitmap.com](https://www.blitmap.com)", "attributes": [ { "trait_type": "Type", "value": "Sibling" }, { "trait_type": "Composition", "value": "Wave (#83)" }, { "trait_type": "Palette", "value": "Logo (#84)" }, { "trait_type": "Affinity", "value": "Fire III" }, { "trait_type": "Slabs", "value": "◢ ◥ ◥ ◥" }, { "trait_type": "Attunement", "value": "Attuned" } ] } } }, { "token": { "collectionAddress": "0x8d04a8c79ceb0889bdd12acdf3fa9d207ed3ff63", "tokenId": "400", "name": "#400 - Optimist Logo", "owner": "0x17cd072cbd45031efc21da538c783e0ed3b25dcc", "image": { "url": "https://api.blitmap.com/v1/png/400" }, "metadata": { "image": "https://api.blitmap.com/v1/png/400", "name": "#400 - Optimist Logo", "description": "Blitmap is a community crafted art collection and universe. All data is completely on chain.\n\n[blitmap.com](https://www.blitmap.com)", "attributes": [ { "trait_type": "Type", "value": "Sibling" }, { "trait_type": "Composition", "value": "Optimist (#95)" }, { "trait_type": "Palette", "value": "Logo (#84)" }, { "trait_type": "Affinity", "value": "Fire III" }, { "trait_type": "Slabs", "value": "◢ ◥ ◥ ◥" }, { "trait_type": "Attunement", "value": "Attuned" } ] } } }, { "token": { "collectionAddress": "0x8d04a8c79ceb0889bdd12acdf3fa9d207ed3ff63", "tokenId": "1255", "name": "#1255 - The Guy Say What", "owner": "0x17cd072cbd45031efc21da538c783e0ed3b25dcc", "image": { "url": "https://api.blitmap.com/v1/png/1255" }, "metadata": { "image": "https://api.blitmap.com/v1/png/1255", "name": "#1255 - The Guy Say What", "description": "Blitmap is a community crafted art collection and universe. All data is completely on chain.\n\n[blitmap.com](https://www.blitmap.com)", "attributes": [ { "trait_type": "Type", "value": "Sibling" }, { "trait_type": "Composition", "value": "The Guy (#78)" }, { "trait_type": "Palette", "value": "Say What (#63)" }, { "trait_type": "Affinity", "value": "Fire III" }, { "trait_type": "Slabs", "value": "◢ ◢ ◤ ◥" }, { "trait_type": "Attunement", "value": "Attuned" } ] } } } ] } }}
In this example, we have set the limit
to 3 NFTs, but the max size of the response can be up to 500
.
However, recommend using the pagination
parameters to meter the size of your responses.
Note, that it is possible to grab all the events
with each NFT by specifying it in the query.
#
Total Sales VolumeNow we can look at the total sales volume for this specific address by using aggregateStat
.
We can see that it has sold 42 NFTs for a total of 90 ETH.
- Query
- Response
query TotalAddressSales { aggregateStat { salesVolume(where: {ownerAddresses: "jacob.eth"}) { totalCount chainTokenPrice } }}
{ "data": { "aggregateStat": { "salesVolume": { "totalCount": 42, "chainTokenPrice": 90.2698 } } }}
#
Largest PurchaseLastly, we can get the largest on-chain ETH purchase this address has made using the sales
query and sorting by descending NATIVE_PRICE
.
Native price is sales price in the currency that was used in the sale transaction.
Running the query, we can see that 5 ETH was paid for a LilNoun on May 16th, 2022.
- Query
- Response
query TopPurchaseForAnAddress { sales(where: {buyerAddresses: "jacob.eth"}, sort: {sortKey: NATIVE_PRICE, sortDirection: DESC}, pagination: {limit: 1}) { nodes { sale { price { nativePrice { decimal } } saleType sellerAddress transactionInfo { transactionHash blockTimestamp } } token { collectionAddress tokenId name description } } }}
{ "data": { "sales": { "nodes": [ { "sale": { "price": { "nativePrice": { "decimal": 5 } }, "saleType": "OPENSEA_SINGLE_SALE", "sellerAddress": "0x1aba5d1c1326fd704090bb01b1c12f70ab3a0252", "transactionInfo": { "transactionHash": "0x4fa67eb3963d5c652cd57416064059eae315e65b3bfb844da27de23a1a8908c6", "blockTimestamp": "2022-05-16T22:21:19" } }, "token": { "collectionAddress": "0x4b10701bfd7bfedc47d50562b76b436fbb5bdb3b", "tokenId": "5", "name": "Lil Noun 5", "description": "Noun 5 is a member of the Nouns DAO" } } ] } }}
#
Getting Data for a Specific NFTNow that you have a sense of how to get data for an address, this section will cover how to get detailed data on a specific NFT.
However, this same data can be retrieved in the first tokens
query used in the first example above.
note
Collection Name: Monarchs
Contract Address: 0xc729Ce9bF1030fbb639849a96fA8BBD013680B64
TokenID: 246
#
Token EventsEvery time transaction interacts with an NFT on the blockchain it creates an event. This query will help you view all the historical events for this NFT including:
- Mints
- Transfers
- Approvals
- Sales
- Zora Markets
- Query
- Response
query TokenEvents { token(token: {address: "0xc729Ce9bF1030fbb639849a96fA8BBD013680B64", tokenId: "246"}) { events(sort: {sortKey: CREATED, sortDirection: ASC}) { eventType transactionInfo { blockTimestamp transactionHash } } }}
{ "data": { "token": { "events": [ { "eventType": "TRANSFER_EVENT", "transactionInfo": { "blockTimestamp": "2021-10-06T16:24:31", "transactionHash": "0x29426d81789f92f148a4361fd346c16ade86724081a22166586372787f9ff444" } }, { "eventType": "MINT_EVENT", "transactionInfo": { "blockTimestamp": "2021-10-06T16:24:31", "transactionHash": "0x29426d81789f92f148a4361fd346c16ade86724081a22166586372787f9ff444" } } ] } }}
#
Token SalesThis query will help you get specific data for all sales pertaining to this NFT across all markets:
- Zora
- OpenSea
- LooksRare
- Nouns Auctions
- Foundation
- and more
- Query
- Response
query TokenSale { token(token: {address: "0xc729Ce9bF1030fbb639849a96fA8BBD013680B64", tokenId: "246"}) { sales { saleType saleContractAddress sellerAddress buyerAddress transactionInfo { blockTimestamp transactionHash } price { nativePrice { decimal currency { name } } } } }}
{ "data": { "token": { "sales": [ { "saleType": "OPENSEA_SINGLE_SALE", "saleContractAddress": "0x7f268357a8c2552623316e2562d90e642bb538e5", "sellerAddress": "0x757b4d4bcd7d02d0f2ce81c5acba6c6f7ff05df6", "buyerAddress": "0x912b37e4ad159882f60de59b27882c5daf3d7e5b", "transactionInfo": { "blockTimestamp": "2022-05-16T19:11:30", "transactionHash": "0x0a1bffd24f1aaee5ad7316c984a9e792dea705c957b16d54ed444a7abac1fbf2" }, "price": { "nativePrice": { "decimal": 0.109, "currency": { "name": "ETH" } } } } ] } }}