token

The token query retrieves detailed information about a specific NFT by its contract address and token ID.

It returns a Token object containing all token metadata, media assets, ownership information, and lifecycle events including mint and burn transactions.

Schema Definition

token(
  contract: String!
  tokenId: UInt256!
): Token

Arguments

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

Return Type

Token object

Common Use Cases

• Display NFT detail pages with complete token information, images, and metadata.
• Verify token ownership and authenticity for marketplace listings and wallets.
• Track token lifecycle events including minting and burning for historical analysis.
• Build NFT galleries and collection viewers with optimized media thumbnails.

Example

Query

Display NFT Token Details with Media

query GetTokenDetails($contract: ID!, $tokenID: ID!) {
  token(contract: $contract, tokenID: $tokenID) {
    tokenID
    name
    metadata {
      description
      attributes {
        traitType
        value
      }
      externalUrl
    }
    media {
      status
      mediaType
      thumbnails(where: { preset: MEDIUM }) {
        url
        width
        height
      }
    }
    holders
    mintTransaction {
      hash
      blockNum
      timestamp
    }
    contract {
      id
      name
      symbol
      type
    }
  }
}

Variables

{
  "contract": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d",
  "tokenID": "1234"
}

Response

{
  "data": {
    "token": {
      "tokenID": "1234",
      "name": "Bored Ape #1234",
      "metadata": {
        "description": "The Bored Ape Yacht Club is a collection of 10,000 unique Bored Ape NFTs.",
        "attributes": [
          {
            "traitType": "Background",
            "value": "Blue"
          },
          {
            "traitType": "Eyes",
            "value": "Bored"
          }
        ],
        "externalUrl": "https://boredapeyachtclub.com"
      },
      "media": [
        {
          "status": "COMPLETED",
          "mediaType": "IMAGE",
          "thumbnails": [
            {
              "url": "https://cdn.onesource.io/media/thumb_medium_abc123.png",
              "width": 300,
              "height": 300
            }
          ]
        }
      ],
      "holders": ["0x742d35cc6634c0532925a3b844bc9e7595f0beb2"],
      "mintTransaction": {
        "hash": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef1234567890",
        "blockNum": 12345678,
        "timestamp": 1650000000
      },
      "contract": {
        "id": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d",
        "name": "BoredApeYachtClub",
        "symbol": "BAYC",
        "type": "ERC721"
      }
    }
  }
}

Implementation Notes

note

• Both contract and tokenID arguments are required to uniquely identify a token.
• The holders field returns an array of wallet addresses. For ERC-721 tokens, this typically contains one address; for ERC-1155 tokens, it may contain multiple addresses.
• Use the nested media.thumbnails field with the preset filter to retrieve optimized images in various sizes (SMALL, MEDIUM, LARGE, EXTRA_LARGE) for responsive display.
• The burnTransaction field will be null for tokens that have not been burned. Check this field to verify if a token still exists.
• The mintTransaction.timestamp is a Unix timestamp in seconds. Convert to local time for user-facing applications.