Token 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.

Try it now

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 now

Example 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

nftTokenV2​

Example Use Case: NFT Display​

Example Variables​

Example Query​

Example Response​

Example Use Case: Royalty Details​

Variables​

Example Response​

Example Use Case: Holders (used for ERC 1155s)​

Example Query​

Example Response​

Arguments​

Fields​

Enums​

Notes​

`nftTokenV2`

Example Use Case: NFT Display

Example Variables

Example Query

Example Response

Example Use Case: Royalty Details

Variables

Example Response

Example Use Case: Holders (used for ERC 1155s)

Example Query

Example Response

Arguments

Fields

Enums

Notes