metadata

The metadata query retrieves detailed metadata for a specific NFT by its contract address and token ID.

It returns a Metadata object containing the token's name, description, attributes, image URLs, external links, and complete raw metadata.

Schema Definition

metadata(
  contract: String!
  tokenId: UInt256!
): Metadata

Arguments

Argument	Type	Description
contract	String! non-null scalar	The contract address of the NFT.
tokenId	UInt256! non-null scalar	The token ID of the NFT.

Return Type

Metadata object

Common Use Cases

• Display comprehensive NFT details including name, description, and visual assets for marketplace listings, galleries, and portfolio trackers.
• Access token attributes and traits to enable filtering, searching, and rarity analysis in NFT marketplaces.
• Retrieve external URLs and animation URLs to provide rich, interactive NFT experiences with additional content.
• Validate metadata completeness and structure for quality assurance in minting platforms and NFT tools.

Example

Query

Retrieve Complete NFT Metadata

query GetNFTMetadata($contract: String!, $tokenId: UInt256!) {
  metadata(contract: $contract, tokenId: $tokenId) {
    contract
    tokenId
    name
    description
    image
    attributes {
      traitType
      value
      displayType
    }
    externalUrl
    animationUrl
    uri
    createdAt
    updatedAt
  }
}

Variables

{
  "contract": "0x76be3b62873462d2142405439777e971754e8e77",
  "tokenId": "10521"
}

Response

{
  "data": {
    "metadata": {
      "contract": "0x76be3b62873462d2142405439777e971754e8e77",
      "tokenId": "10521",
      "name": "Cool Cat #10521",
      "description": "Cool Cats is a collection of 9,999 randomly generated and stylistically curated NFTs that exist on the Ethereum Blockchain.",
      "image": "ipfs://QmZCbZEqpQZMqSaKYLDQQZzJGvXDqXEEk5J3VQaFqZYZBN",
      "attributes": [
        {
          "traitType": "Body",
          "value": "blue cat skin",
          "displayType": null
        },
        {
          "traitType": "Hat",
          "value": "miners helmet",
          "displayType": null
        },
        {
          "traitType": "Face",
          "value": "star glasses",
          "displayType": null
        }
      ],
      "externalUrl": "https://www.coolcatsnft.com/",
      "animationUrl": null,
      "uri": "ipfs://QmZCbZEqpQZMqSaKYLDQQZzJGvXDqXEEk5J3VQaFqZYZBN",
      "createdAt": 1634567890,
      "updatedAt": 1634567890
    }
  }
}

Implementation Notes

note

• The image field may contain an IPFS hash, HTTP URL, or data URI. Handle all formats appropriately in your application.
• The Attributes object provides trait-based properties crucial for rarity calculations and filtering. The traitType and value fields are most commonly used.
• The raw field contains the complete, unprocessed JSON metadata—useful when standard fields don't capture all information.
• Some fields like animationUrl, youtubeUrl, and externalUrl may be null if not present in the original metadata.
• The uri field shows where the metadata was originally retrieved from (typically an IPFS gateway or HTTP endpoint).
• Use createdAt and updatedAt timestamps to track metadata freshness and detect updates to token metadata.
• Not all NFT projects follow metadata standards perfectly. Be prepared to handle missing or non-standard fields.