NFT Metadata
Takes collectionAddress
, chainId
, and tokenId
as input. Returns detailed data about a specific NFT including:
- Traits, rarity, USD valuations, and royalty info
- Current ownership
- Sale and transfer history
- Complete media including multiple sizes, file types, blurHash, and predominant color.
nftTokenV2
Example Use Case: NFT Display
Let's say you want to display a specific NFT. Start by passing the collectionAddress
, chainId
, and tokenId
to identify the NFT. Then return information about the token including its name
, description
, current estimatedValue
, and media assets from mediasV3
. You can also get trait information and current sale data.
Example Variables
{
"collectionAddress": "0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb",
"chainId": 1,
"tokenId": "7495"
}
Example Query
query NFTMetadata($collectionAddress: Address!, $chainId: Int!, $tokenId: String!) {
nftTokenV2(collectionAddress: $collectionAddress, chainId: $chainId, tokenId: $tokenId) {
# Basic token information
id
name
description
tokenId
# Collection information
collection {
name
symbol
address
network
description
nftStandard
supply
circulatingSupply
holdersCount
socialLinks {
name
url
}
# Pricing data
floorPrice {
valueUsd
valueWithDenomination
denomination {
network
symbol
address
}
}
# Collection media assets
medias {
logo {
thumbnail
original
blurhash
}
banner {
original
blurhash
thumbnail
medium
large
width
height
mimeType
}
}
}
# Token media assets
mediasV3 {
images(first: 5) {
edges {
node {
original
thumbnail
medium
large
mimeType
width
height
blurhash
fileSize
}
}
pageInfo {
hasNextPage
endCursor
}
}
animations(first: 1) {
edges {
node {
original
mimeType
fileSize
url
}
}
pageInfo {
hasNextPage
endCursor
}
}
audios(first: 1) {
edges {
node {
original
mimeType
fileSize
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
# Trait/attribute information
traits {
attributeName
attributeValue
supply
supplyPercentage
estimatedValueEth
}
# Ownership information
holdersCount
holders(first: 1) {
totalCount
edges {
node {
holdCount
holdTotalCount
account {
address
displayName {
value
source
}
farcasterProfile {
fid
username
metadata {
imageUrl
}
}
}
}
}
}
# Value and pricing information
estimatedValue {
valueUsd
valueWithDenomination
denomination {
network
address
symbol
}
}
lastSale {
valueUsd
valueWithDenomination
denomination {
network
address
symbol
}
}
# Transaction history
transfers(first: 3, order: { orderBy: TIMESTAMP, orderDirection: DESC }) {
edges {
node {
timestamp
txHash
payments {
tokenValueUSD
tokenValueETH
tokenSymbol
tokenValue
}
}
heldForInSeconds
}
}
}
}
Example Response
{
"data": {
"nftTokenV2": {
"id": "TmZ0VG9rZW5FcmM3MjEtNzE5MTU1NDg=",
"name": "CryptoPunk #7495",
"description": null,
"tokenId": "7495",
"collection": {
"name": "CryptoPunks",
"symbol": "PUNK",
"address": "0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb",
"network": "ETHEREUM_MAINNET",
"description": "CryptoPunks launched as a fixed set of 10,000 items in mid-2017 and became one of the inspirations for the ERC-721 standard. They have been featured in places like The New York Times, Christie’s of London, Art|Basel Miami, and The PBS NewsHour.",
"nftStandard": "ERC_721",
"supply": "10000",
"circulatingSupply": "9998",
"holdersCount": "3898",
"socialLinks": [
{
"name": "opensea",
"url": "https://opensea.io/collection/cryptopunks"
},
{
"name": "website",
"url": "https://cryptopunks.app/"
},
{
"name": "discord",
"url": "https://discord.gg/tQp4pSE"
},
{
"name": "twitter",
"url": "https://twitter.com/cryptopunksnfts"
}
],
"floorPrice": {
"valueUsd": 78690.24,
"valueWithDenomination": 44.5,
"denomination": {
"network": "ethereum",
"symbol": "ETH",
"address": "0x0000000000000000000000000000000000000000"
}
},
"medias": {
"logo": {
"thumbnail": "https://images.zapper.xyz/z/?path=zapper-fi-assets/nfts/collections/ethereum/0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb/logo.png&width=100&checksum=VRfRMhN8zb3wUmkCPQ3STvPy8CFNJ3U_aJ7OF_XPOAE",
"original": "https://images.zapper.xyz/z/?path=zapper-fi-assets/nfts/collections/ethereum/0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb/logo.png&checksum=IQmhCm_mxeHCHUU8bVtI_fvRt1VlVgkf8XLv1gAa6_A",
"blurhash": "UGCZ|rt7GwXnpJbIjDn$X:j[rWbHg3bHoJn$"
},
"banner": {
"original": "https://images.zapper.xyz/z/?path=zapper-fi-assets/nfts/collections/ethereum/0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb/banner.png&checksum=IhNJ4CEIhqnB0I8AN3SdsdZeG4xX1BY_MQ0W0SwrKxM",
"blurhash": "U6CHE4%Nu4D-=tDOk7%%Y7NGngx]Tz.8ohD$",
"thumbnail": "https://images.zapper.xyz/z/?path=zapper-fi-assets/nfts/collections/ethereum/0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb/banner.png&width=100&checksum=IgDm4D5eulrWHufcCvpTO2nAHHXKeuVIiMn7gDE98Po",
"medium": "https://images.zapper.xyz/z/?path=zapper-fi-assets/nfts/collections/ethereum/0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb/banner.png&width=250&checksum=nl0uwagI79H3jBU4aHXk6qPHojwL7xzCdKNnRx7nYSo",
"large": "https://images.zapper.xyz/z/?path=zapper-fi-assets/nfts/collections/ethereum/0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb/banner.png&width=500&checksum=jhT4APqKXdT9N54En0rvfbwTsuTsLLuHtykB33bX-7U",
"width": 1400,
"height": 400,
"mimeType": "image/png"
}
}
},
"mediasV3": {
"images": {
"edges": [
{
"node": {
"original": "https://images.zapper.xyz/z/?path=zapper-fi-assets/nfts/medias/00f8b24c79685e376e42fa775bfeab0eb3fc55e09e77be0ee31c43193e81c71e.png&checksum=pROaf-XTErcC6-X_xfqRLi0E8L05VDU44JTOlPmmYl8",
"thumbnail": "https://images.zapper.xyz/z/?path=zapper-fi-assets/nfts/medias/00f8b24c79685e376e42fa775bfeab0eb3fc55e09e77be0ee31c43193e81c71e.png&width=100&checksum=rLbedBd3LjoWiupW6kS2ydBVtCTyM802KkdQpb_gcYE",
"medium": "https://images.zapper.xyz/z/?path=zapper-fi-assets/nfts/medias/00f8b24c79685e376e42fa775bfeab0eb3fc55e09e77be0ee31c43193e81c71e.png&width=250&checksum=nkjoElh9iatvmiiqUFFtgaLizZLtOKKvmPz9gES3WFM",
"large": "https://images.zapper.xyz/z/?path=zapper-fi-assets/nfts/medias/00f8b24c79685e376e42fa775bfeab0eb3fc55e09e77be0ee31c43193e81c71e.png&width=500&checksum=Z5b5VVwgpzW2WJ4izmp1st5iM5ajC-BXFEkCBDeO28Q",
"mimeType": "image/png",
"width": 312,
"height": 312,
"blurhash": "UIBX7sjFpytmu5kDZ~aKXokCivaxt7f6WAj[",
"fileSize": 2825
}
}
],
"pageInfo": {
"hasNextPage": false,
"endCursor": "MA=="
}
},
"animations": {
"edges": [],
"pageInfo": {
"hasNextPage": false,
"endCursor": null
}
},
"audios": {
"edges": [],
"pageInfo": {
"hasNextPage": false,
"endCursor": null
}
}
},
"traits": [
{
"attributeName": "accessory",
"attributeValue": "Straight Hair",
"supply": "151",
"supplyPercentage": 1.51,
"estimatedValueEth": "30.177248958501348"
},
{
"attributeName": "type",
"attributeValue": "Female",
"supply": "3839",
"supplyPercentage": 38.39,
"estimatedValueEth": "38.53659604740535"
},
{
"attributeName": "accessory",
"attributeValue": "Purple Lipstick",
"supply": "655",
"supplyPercentage": 6.55,
"estimatedValueEth": "33.755566215373456"
},
{
"attributeName": "accessory",
"attributeValue": "Cigarette",
"supply": "961",
"supplyPercentage": 9.61,
"estimatedValueEth": "35.583682494229855"
}
],
"holdersCount": "1",
"holders": {
"totalCount": 1,
"edges": [
{
"node": {
"holdCount": "1",
"holdTotalCount": "1",
"account": {
"address": "0xdfa7777507f7ba68aa42192d714f747f77c07f97",
"displayName": {
"value": "0xdfa7...7f97",
"source": "ADDRESS"
},
"farcasterProfile": null
}
}
}
]
},
"estimatedValue": {
"valueUsd": 78989.5054429068,
"valueWithDenomination": 44.66923715329058,
"denomination": {
"network": "ethereum",
"address": "0x0000000000000000000000000000000000000000",
"symbol": "ETH"
}
},
"lastSale": {
"valueUsd": 104330.88,
"valueWithDenomination": 59,
"denomination": {
"network": "ethereum",
"address": "0x0000000000000000000000000000000000000000",
"symbol": "ETH"
}
},
"transfers": {
"edges": [
{
"node": {
"timestamp": 1705709819,
"txHash": "0x67fb91827d8e5cb71ffc0dc3c8744aed902ee6e0339085c4dda9ca63db89ec0a",
"payments": [
{
"tokenValueUSD": "145559.12",
"tokenValueETH": "59",
"tokenSymbol": null,
"tokenValue": "59"
}
]
},
"heldForInSeconds": 40155531
},
{
"node": {
"timestamp": 1666942439,
"txHash": "0x9bc238c2ca93c8767773b10efcbc4ae7e332fd041e2f94e7f419029c42117198",
"payments": [
{
"tokenValueUSD": "98424.92",
"tokenValueETH": "64.74",
"tokenSymbol": null,
"tokenValue": "64.74"
}
]
},
"heldForInSeconds": 38767380
},
{
"node": {
"timestamp": 1666707455,
"txHash": "0xacb37103082c9a9851dfa712040a459599930887475f004d0b5fc117d157386a",
"payments": [
{
"tokenValueUSD": "84304.01",
"tokenValueETH": "62.69",
"tokenSymbol": null,
"tokenValue": "62.69"
}
]
},
"heldForInSeconds": 234984
}
]
}
}
}
}
Example Use Case: Royalty Details
When available, the API returns royalty data according to ERC-2981. This allows you to find the royalty receipient as well as the amount earned for a given salePrice
.
Variables
{
"collectionAddress": "0x020e6438cdb1b40a6d61ccdb8dba41fafae9bc0d",
"chainId": 8453,
"tokenId": "425"
"salePrice":"10000"
}
Example Response
{
"data": {
"nftTokenV2": {
"royaltyInfo": {
"amount": "1000",
"receiver": "0xf5c019ebbba7a3ab51b2de792b8a50c4af7b7ef7"
}
}
}
}
Example Use Case: Holders (used for ERC 1155s)
Paginated response of all the NFT holders sorted in decending order from most held to least held.
Try it nowExample Query
query ERC1155NFTHolders($collectionAddress: Address!, $chainId: Int!, $tokenId: String!) {
nftTokenV2(collectionAddress: $collectionAddress, chainId: $chainId, tokenId: $tokenId) {
# Basic token information
name
description
tokenId
# Collection information
collection {
name
symbol
address
network
description
nftStandard
}
# Holders
holdersCount
holders(first: 10) {
totalCount
edges {
node {
holdCount
account {
address
displayName {
value
source
}
farcasterProfile {
fid
username
metadata {
imageUrl
}
}
}
}
}
}
}
}
Example Response
{{
"data": {
"nftTokenV2": {
"name": "EMP Shockwave",
"description": "EMP Shockwave",
"tokenId": "10384",
"collection": {
"name": "Parallel Alpha",
"symbol": "LL",
"address": "0x76be3b62873462d2142405439777e971754e8e77",
"network": "ETHEREUM_MAINNET",
"description": "Sci-fi collectable card game with NFTs.",
"nftStandard": "ERC_1155"
},
"holdersCount": "1401",
"holders": {
"totalCount": 1401,
"edges": [
{
"node": {
"holdCount": "7668",
"account": {
"address": "0x39f05c39902a9b265dcb4c59418657cdb9913c23",
"displayName": {
"value": "0x39f0...3c23",
"source": "ADDRESS"
},
"farcasterProfile": null
}
}
},
{
"node": {
"holdCount": "75",
"account": {
"address": "0xcff83df706328a6c0612bf14d6504fd12cc7a79f",
"displayName": {
"value": "0xcff8...a79f",
"source": "ADDRESS"
},
"farcasterProfile": null
}
}
},
{
"node": {
"holdCount": "66",
"account": {
"address": "0x616375b0fda12d872bb1e903f42d22939d16d0dc",
"displayName": {
"value": "toastedvault.eth",
"source": "ENS"
},
"farcasterProfile": null
}
}
}
]
}
}
}
}
Arguments
Argument | Description | Type | Required |
---|---|---|---|
collectionAddress | The contract address of the NFT collection | String! | Yes |
chainId | The blockchain where the NFT exists, see Supported Chains to find the chainId | Network! | Yes |
tokenId | The unique identifier of the NFT within its collection | String! | Yes |
Fields
Field | Description | Type |
---|---|---|
id | Unique identifier for the NFT | ID! |
tokenId | Token ID within the collection | String! |
name | Name of the NFT | String! |
description | Description of the NFT | String |
supply | Total supply of this token | BigDecimal! |
circulatingSupply | Number of tokens in circulation | BigDecimal! |
holdersCount | Number of unique holders (ERC-1155) | BigDecimal! |
socialLinks | Social media links | [SocialLink!]! |
collection | Parent collection information | NftCollection! |
traits | Token traits/attributes | [NftTrait!]! |
mediasV2 | Media assets (legacy format) | [NftMediaV2!]! |
mediasV3 | Media assets (current format) | NftMedias! |
transfers | Transfer history | NftTransferConnection |
holders | Current token holders | NftHolderConnection! |
holdersFollowedByAddress | Holders followed by given address | [NftHolder!]! |
isHidden | Whether token is hidden by owner | Boolean! |
estimatedValue | Current estimated value | NftValueDenomination |
lastSale | Most recent sale details | NftValueDenomination |
rarityRank | Token rarity ranking (deprecated) | Int |
lastSaleEth | Last sale price in ETH (deprecated) | BigDecimal |
estimatedValueEth | Estimated value in ETH (deprecated) | BigDecimal |
Enums
enum NftTransferSort {
TIMESTAMP
}
enum OrderDirectionOption {
DESC
ASC
}
Notes
- Returns comprehensive NFT metadata
- Includes current value estimates and last sale data
- Provides access to high-quality media assets
- Shows detailed trait information
- Includes ownership and transfer history
- Supports both ERC721 and ERC1155 standards