What is NFT Metadata?
NFT metadata is the structured data that describes what a non-fungible token represents—its name, description, image, attributes (traits), animation URL, and any other properties that make the token meaningful to humans. While the NFT itself is just a unique integer token ID recorded on a blockchain (for example, Bored Ape #8817), the metadata is what tells your wallet or a marketplace that this token depicts a specific ape with golden fur, a sailor hat, and laser eyes. Without metadata, an NFT is an opaque number; with it, the number becomes art, a game item, a membership pass, or a domain name.
The separation between the on-chain token and its off-chain metadata is a deliberate engineering trade-off. Storing a 1024×1024 PNG image directly on Ethereum would cost tens of thousands of dollars in gas (a single kilobyte of contract storage costs roughly 20,000 gas, or ~$0.60–$2.00 at moderate gas prices, meaning a 1MB image would cost over $600,000). So nearly all NFT collections store only a pointer—a tokenURI—on-chain, which resolves to a JSON file hosted elsewhere. That JSON file contains the image URL and attributes. This design is defined by the ERC-721 standard’s tokenURI(uint256 tokenId) function and the OpenSea metadata standard, which together form the de-facto schema the entire NFT ecosystem reads.
The consequence of this architecture is a profound permanence and centralization problem. If the JSON or image is hosted on a private AWS server and that server goes offline (or the project team abandons it), the NFT becomes a broken link—a token with no visible art. This has already happened to numerous 2021-era collections whose centralized metadata servers went dark. The industry’s answer is decentralized storage: IPFS (InterPlanetary File System), Arweave, and on-chain rendering. Understanding where metadata lives, who controls it, and whether it can be changed after mint is essential to evaluating the durability of any NFT.
How It Works
The tokenURI Function and JSON Schema
ERC-721 defines function tokenURI(uint256 tokenId) external view returns (string memory). This returns a URI—typically an HTTPS URL or an ipfs:// CID hash. When a wallet (MetaMask) or marketplace (OpenSea, Blur) loads an NFT, it calls tokenURI, fetches the JSON at that URI, and parses it. The widely adopted OpenSea metadata standard expects this JSON shape:
{
"name": "Bored Ape #8817",
"description": "Bored Ape Yacht Club is a collection of 10,000 unique Bored Ape NFTs.",
"image": "ipfs://QmYx5Aq.../8817.png",
"external_url": "https://boredapeyachtclub.com/#/apes/8817",
"attributes": [
{ "trait_type": "Fur", "value": "Golden Brown" },
{ "trait_type": "Eyes", "value": "Laser Eyes" },
{ "trait_type": "Hat", "value": "Sailor Shirt" },
{ "trait_type": "Background", "value": "Orange" }
]
}The attributes array drives rarity calculations: each trait’s scarcity across the full collection determines how rare a given combination is. A Bored Ape with “Solid Gold” fur (46 of 10,000, or 0.46%) is far rarer than “Brown” fur (1,862 of 10,000, or 18.62%). Rarity tools and marketplaces compute these frequencies to rank tokens.
IPFS and Decentralized Storage
The image field usually points to an IPFS Content Identifier (CID), a cryptographic hash of the file content. A CID like QmYx5Aq... is content-addressed: changing a single pixel changes the CID entirely, so the file is tamper-evident. The NFT contract often stores a base URI like ipfs://QmBaseHash/{id}.json, where {id} is replaced by the token ID to resolve each token’s JSON. IPFS itself is a peer-to-peer network—files are only retrievable while at least one node pins them. Projects use pinning services (Pinata, NFT.Storage, Infura) to guarantee availability, or pin to Filecoin (incentivized storage) or Arweave (permanent, one-time-payment storage). The strongest durability guarantee is to render the image on-chain from the contract itself, which is what generative art platforms like Art Blocks do: the contract stores the generative algorithm and a per-token hash, and the image is computed deterministically by the viewer—no external server required.
Centralized vs. Decentralized vs. On-Chain Metadata
| Storage Method | Example Projects | Immutability | Permanence Risk | Cost |
|---|---|---|---|---|
| Centralized HTTP | Early 2017-2020 collections (e.g., some CryptoKitties assets) | Mutable (team can change) | High—server offline = art gone | Low |
| IPFS (pinned) | BAYC, Cool Cats, World of Women | Immutable (CID fixed) | Medium—depends on pinning | Low–Medium |
| Arweave | Most modern collections | Immutable, permanent | Very low—storage prepaid | One-time fee |
| Fully on-chain | CryptoPunks, Art Blocks, OnChainMonkey | Immutable (in contract) | Zero—lives as long as Ethereum | High (10K–100K+ gas) |
Reveal Mechanics and the Metadata Trap
Many collections use a “lazy reveal” or “pre-reveal” pattern: during mint, tokenURI returns a placeholder image for all tokens, and after mint sells out, the team updates the base URI to the final metadata so traits are revealed simultaneously (preventing the front-running where users peek at metadata and mint only the rarest tokens). This requires the contract to allow the owner to change the base URI—a setBaseURI function. If the team is malicious or the admin key is compromised, they can change metadata after the reveal, swapping a rare token’s art or attributes. This is known as metadata mutability risk. Auditors and collectors favor contracts where, post-reveal, the tokenURI is frozen or points to an immutable IPFS/Arweave hash.
Real-World Examples
CryptoPunks (2017): Larva Labs stored the 10,000 Punk images as a single composite image embedded directly in the contract via a custom image registry. Each Punk’s pixel data is fully on-chain and immutable—no external server can take them down. This is a major reason CryptoPunks trade at a premium (floor prices have ranged from 30–70 ETH, i.e., $90,000–$200,000+). The metadata (attributes like “Alien,” “Ape,” “Zombie”) was originally off-chain in a separate registry but was later mirrored; the core art is permanently on-chain.
Bored Ape Yacht Club (2021): BAYC stores metadata on IPFS via Pinata. Each Ape’s JSON and PNG are content-addressed. The reveal happened 48 hours after mint, with the base URI updated once. Because the final CIDs are pinned and widely replicated, BAYC art is effectively permanent even if Yuga Labs disappeared. Floor prices peaked above 150 ETH ($480,000) in May 2022.
Art Blocks (2020–present): Art Blocks pioneered fully on-chain generative art. Each token stores a script (the artist’s generative code) and a per-token hash in the contract; the viewer renders the image in real time from that code. There is no external image file at all. Collections like Tyler Hobbs’ Fidenza and Dmitri Cherniak’s Ringers have sold for $1M–$7M each. The art is provably permanent for as long as Ethereum exists.
NFT “rug” metadata failures: Numerous 2021 collections (e.g., “Frosties,” which was an $850K rug pulled in March 2022) hosted metadata on centralized servers that went offline after the founders disappeared, leaving holders with tokens that displayed blank images. This is the core lesson: always check where metadata is stored before buying.
Key Risks / Considerations
- Centralization of hosting: If metadata or images live on a single AWS S3 bucket or unpinning service that the team controls, the NFT’s visual existence depends on that team. Prefer IPFS/Arweave with content-addressed CIDs, and ideally on-chain rendering for high-value art.
- Mutable metadata: Contracts with an admin-callable
setBaseURIcan have their art or traits changed post-sale. Check whether the URI is frozen after reveal. Tools like the “How Rare Is” and contract read functions expose this. - Pinning dependency: IPFS files vanish if no node pins them. NFT.Storage and Pinata have changed free-tier policies; some 2021 collections have experienced image rot when pins lapsed. Look for Filecoin or Arweave backing.
- Trait/rarity gaming: If the team mints the rarest tokens to insider wallets before public reveal (by reading the pre-reveal metadata), rarity distribution is unfair. Fair mints either reveal instantly after each mint or commit to a provably random, time-locked reveal.
- Off-chain attribute enrichment: Some marketplaces (OpenSea) store additional metadata (like stats or collection descriptions) on their own servers, separate from the on-chain
tokenURI. If the marketplace changes, that enrichment may not transfer—only the on-chaintokenURIis canonical.
Comparison Table: Metadata Storage Approaches
| Approach | How Image Lives | Can Be Changed? | Survives Project Abandonment? | Notable Examples |
|---|---|---|---|---|
| Centralized server | AWS / project CDN | Yes, freely | No | Many early/low-effort collections |
| IPFS pinned | Content-addressed file | No (CID fixed); URI pointer can change if mutable | Only if pinned by others | BAYC, Azuki, Pudgy Penguins |
| Arweave | Permanent storage | No | Yes (prepaid permanent) | Many 2022+ collections |
| On-chain SVG/Script | Computed in-contract | No (immutable) | Yes (as long as L1 lives) | CryptoPunks, Art Blocks, OnChainMonkey |
Frequently Asked Questions
Q: Where can I find an NFT’s raw metadata?
A: For an ERC-721 token, go to Etherscan, open the contract’s “Read Contract” tab, call tokenURI(tokenId) with the token ID, and you’ll get a URI (often ipfs://Qm...). Paste that into an IPFS gateway like ipfs.io/ipfs/<CID> or use dweb.link to fetch the JSON. The JSON’s image field is the actual artwork URL. For ERC-1155, the function is uri(id).
Q: Can the metadata of an NFT change after I buy it?
A: It depends on the contract. If the contract has a setBaseURI function controlled by an admin and it was never frozen, then yes—the team can change the art or traits. Most reputable collections freeze the URI after reveal or point to an immutable IPFS/Arweave hash. Always verify in the contract source or via a “is the URI frozen?” check before buying high-value NFTs.
Q: What happens if the IPFS pin disappears? A: The on-chain token still exists (your NFT is not lost), but the JSON and image may become unfetchable, leaving you with a token that displays a broken image on marketplaces. If someone else (another holder, a third party) has pinned the same CID, the data remains available. This is why high-value collections get widely pinned. For true permanence, prefer Arweave (prepaid, incentive-aligned) or on-chain storage.
Q: Why is on-chain metadata more valuable? A: Because it is permanent and trustless. If the entire founding team of Art Blocks disappeared tomorrow, every token’s art would still render perfectly from the Ethereum contract. This permanence premium is why on-chain art collections (CryptoPunks, Art Blocks) command higher floor prices than equivalent IPFS-only collections—the buyer is purchasing a provably permanent asset, not a link that could rot.
Q: What is the difference between ERC-721 and ERC-1155 metadata?
A: ERC-721 has a tokenURI per unique token (1:1 art). ERC-1155 is a semi-fungible standard where one token ID can have many copies; it uses a uri(id) function returning a metadata template with {id} as a substitution variable, allowing a single JSON file to serve multiple token IDs. ERC-1155 is common in gaming items (e.g., a “Health Potion” item with 10,000 fungible copies).