Getting Art Blocks Token Metadata#

Tool: get_token_metadata#

Retrieves a single token's full metadata in one call — traits, media URLs, owner, hash, listing info, and project context. Prefer this over graphql_query when you need rich token details for a known token ID.

Token ID Format#

<contract_address>-<token_number>

Example: 0xa7d8d9ef8d8ce8992df33d8b8cf4aebabd5bd270-78000000

Parameters#

ParamRequiredNotestokenIdyesFull token ID <contract_address>-<token_number>``chainId—Default 1 (Ethereum). 1, 42161 (Arbitrum), 8453 (Base)

Response Shape#

The response has three top-level keys: token, media, and project.

text

token:
  id, tokenId, chainId, contractAddress, projectId
  hash              — 32-byte hex, the source of all randomness
  invocation        — mint number within the project (0-indexed)
  features          — on-chain traits object
  featuresStatus    — "not_defined" | "defined_empty" | "defined"
  mintedAt, mintTransactionHash
  ownerAddress
  listing           — null if not listed, otherwise:
    listing.price      — listing price
    listing.currency   — currency symbol (ETH, WETH, etc.)
    listing.platform   — marketplace name
    listing.url        — listing URL
  artBlocksUrl      — direct link to the token page on artblocks.io

media:
  imageUrl          — primary rendered image
  previewUrl        — preview asset URL
  liveViewUrl       — live interactive generator URL
  hasVideo          — true if a video render exists

project:
  id, name, artistName, slug
  artBlocksUrl      — direct link to the project page on artblocks.io
  description, website, license
  scriptTypeAndVersion
  maxInvocations, invocations, remaining
  active, paused, complete
  aspectRatio, curationStatus, verticalName, verticalDisplay
  renderComplete

When to Use vs GraphQL#

Use get_token_metadata when...Use graphql_query when...You have a specific token ID and want everything about itYou need to query multiple tokens at onceYou need media URLs ( liveViewUrl, imageUrl)You need fields not in this responseYou want features + project context in one callYou're building complex filters or aggregations

Notes#

• liveViewUrl is the canonical way to share or preview a generative token — always include it when presenting a token to a user
• features is the on-chain traits object — same data shown on Art Blocks website
• featuresStatus distinguishes between "artist hasn't defined features" ( not_defined), "features are defined but empty for this token" ( defined_empty), and "features exist" ( defined)
• hash uniquely identifies the token's visual output — same hash always produces the same artwork
• listing is null when the token has no active secondary-market listing; when present it contains price, currency, platform, and url
• Both token.artBlocksUrl and project.artBlocksUrl link to artblocks.io — use these when presenting tokens to users