Token URI

Overview

A token URI tells wallets, marketplaces, and applications where to retrieve metadata associated with a token. For an NFT, that metadata can include a name, description, image, attributes, animation, or external link. The contract may return one URI per token, apply an ID substitution rule, or embed the metadata directly in an on-chain data URI.

The storage scheme defines important behavior. HTTPS content depends on a server and domain owner. IPFS or Arweave identifiers can support content-addressed or persistent retrieval, although gateways still affect availability. On-chain data avoids an external host but increases storage cost and remains subject to the contract’s rules. A URI can also be mutable if an administrator may change the base path or token-specific value.

The URI is only a pointer. Applications should retrieve content with strict size, timeout, redirect, and media-type limits; parse the expected schema; and treat HTML, SVG, scripts, and external URLs as untrusted input. Metadata should never be allowed to execute with wallet or marketplace privileges. Privacy review is also necessary when retrieval exposes user addresses or tracking information.

For authenticity, systems should retain the network, token contract, token ID, returned URI, resolved content hash, retrieval time, and update authority. A marketplace cache can differ from current contract state, so users should be told whether displayed content is cached, mutable, or permanently bound.

ERC-721 commonly exposes tokenURI, while ERC-1155 defines a URI pattern that can substitute the token ID. These interfaces standardize discovery but do not guarantee that content exists or remains unchanged. The same image can also be referenced by unrelated tokens, so metadata similarity is not proof of ownership or collection authenticity.

Production support for non-fungible tokens should include safe fetch infrastructure, schema validation, content hashing, gateway fallback, cache invalidation, and clear handling when metadata disappears or changes.