Skip to main content

Token

The token query retrieves detailed information about a specific NFT or token, including its metadata, ownership history, and blockchain state. This is the primary method to fetch individual token data from collections.

token(
  contract: ID!
  tokenID: ID!
): Token

Arguments​

token.contract ● ID! non-null scalar​

token.tokenID ● ID! non-null scalar​

Type​

Token object​

Argument Descriptions​

ArgumentTypeDescription
contractID!Contract address where the token resides.
tokenIDID!Unique token identifier.

Example​

Basic Token Fetch​

query Token($contract: ID!, $tokenId: ID!) {
  token(contract: $contract, tokenID: $tokenId) {
    tokenID
    name
    description
    image {
      url
    }
    contract {
      name
      symbol
    }
    holders {
      balances {
        owner
      }
    }
  }
}

Variables​

{
  "contract": "0xBd3531dA5CF5857e7CfAA92426877b022e612cf8",
  "tokenId": "2341"
}

Response​

This response is an example only and may not reflect current data.

{
  "data": {
    "token": {
      "tokenID": "2341",
      "name": "Pudgy Penguin #2341",
      "description": "A collection 8888 Cute Chubby Pudgy Penquins sliding around on the freezing ETH blockchain.",
      "image": {
        "url": "QmNf1UsmdGaMbpatQ6toXSkzDpizaGmC9zfunCyoz1enD5/penguin/2341.png"
      },
      "contract": {
        "name": "PudgyPenguins",
        "symbol": "PPG"
      },
      "holders": {
        "balances": [
          {
            "owner": "0x7e7022f8879d88bcc5d288b229737adb4b1f39cb"
          }
        ]
      }
    }
  }
}

Common Use Cases​

  1. NFT Display: Show token details and media in marketplaces or galleries.
  2. Ownership Verification: Confirm current holder of a specific token.
  3. Metadata Analysis: Inspect token attributes and media.
  4. Historical Research: Check creation/burn status.

Best Practices​

  • Error Handling: Returns null for non-existent tokens.
  • Partial Data: Some fields may be null if metadata is unavailable.
  • Combination Query: Pair with contract query for full context.
  • tokens: For fetching multiple tokens from a collection.
  • contract: To verify token standards before querying.