NFT Metadata Explained: How It Works and Where It Lives

One of the biggest misconceptions about NFTs is that the image, video, or collectible itself always lives on the blockchain. In most cases, that is not true.

What usually lives on-chain is the token contract, the token ID, and the ownership record. The visual asset people associate with the NFT often sits elsewhere, and the bridge between the token and that content is metadata. If you understand NFT metadata, you understand what an NFT really points to, how marketplaces display it, and why some collections are more durable than others.

That distinction matters more than most newcomers realize. A token can remain valid on-chain while its image fails to load, its traits disappear, or its external media breaks. That is why metadata is not a technical afterthought. It is a core part of how NFTs function in the real world.

If you need a broader overview of why NFTs matter in the first place, this CryptoRobotics guide to digital ownership and NFTs is a useful starting point. But once you move past the basics, the real question becomes more specific: how does an NFT know what it is supposed to represent?

Why NFT Metadata Exists

An NFT token by itself is too minimal to create a rich user experience. A blockchain can track ownership and transfer history, but it does not automatically tell a marketplace what to display as the token’s name, description, image, traits, or external link.

That extra layer comes from metadata.

In the ERC-721 standard, NFTs are defined as unique tokens with separate ownership tracking, and in practice, marketplaces rely on a metadata URI to understand what each token represents. The ERC-1155 standard follows a similar approach, but its metadata model is designed for multi-token contracts and uses a URI() pattern that can support ID substitution.

Without metadata, an NFT would often look like a contract address plus a token number. It would still exist, but it would not be meaningful to most users.

What Metadata Usually Contains

At the marketplace level, metadata is what turns a token into something recognizable.

According to the OpenSea metadata standards, metadata commonly includes fields such as name, description, image, and trait information, while richer implementations may also support animation_url, external_url, background styling, and other display-specific properties.

A simplified metadata file often looks like this:

{

  “name”: “Solar Cat #142”,

  “description”: “A unique NFT from the Solar Cat collection.”,

  “image”: “ipfs://bafy…/142.png”,

  “attributes”: [

    { “trait_type”: “Background”, “value”: “Blue” },

    { “trait_type”: “Eyes”, “value”: “Laser” },

    { “trait_type”: “Accessory”, “value”: “Gold Chain” }

  ]

}

That JSON file is what a marketplace reads after resolving the token’s metadata URI. The contract itself may only expose a pointer, while the metadata file supplies the presentation layer.

This is also why collectors care so much about traits and rarity. In many collections, value is driven not just by ownership, but by metadata-defined attributes. You can see that logic clearly in this CryptoRobotics overview of CryptoPunks, which notes how attributes become central to sorting, rarity, and perceived desirability.

How the Retrieval Process Works

From the outside, viewing an NFT looks simple. You open a marketplace page, and the image and traits appear. Under the hood, the process is more layered.

In most Ethereum-style NFT setups, the marketplace first reads the token contract. For ERC-721, it calls tokenURI(tokenId). For ERC-1155, it calls uri(id). That call returns a URI pointing to the metadata location. The marketplace then fetches the metadata file, parses it, and finally loads the media referenced inside it.

So the chain usually looks like this:

smart contract → token URI / uri → metadata JSON → image or media file

That structure is important because the metadata is often not the media itself. The metadata may contain an image field that points to a PNG, SVG, MP4, GIF, or another asset stored elsewhere.

This is the part many people miss. An NFT is often not “the JPEG on-chain.” It is a token that points to metadata, and that metadata points to media.

Where NFT Metadata Is Actually Stored

The short answer is: it depends on the project.

NFT metadata can be stored in three broad ways:

• fully on-chain
• off-chain on decentralized storage
• off-chain on centralized servers

The most common setup is off-chain metadata with on-chain ownership. That is largely because blockchain storage is expensive. As the Alchemy explanation of NFTs in practice points out, storing large files directly on Ethereum is impractical, which is why many projects keep ownership data on-chain while storing metadata and media elsewhere.

That design is not inherently bad. The real question is where “elsewhere” actually is.

Centralized Storage: Simple, Cheap, and Risky

Some NFT projects store metadata or media on ordinary web servers using standard HTTPS links. This is easy to implement and cheap to maintain, especially for teams moving fast.

The problem is durability.

If the server owner removes the file, changes the file, misconfigures the endpoint, or lets the hosting lapse, the NFT can stop rendering correctly even though the token still exists on-chain. In plain terms, ownership remains intact, but the collectible experience breaks.

This is not just a theoretical risk. The Alchemy NFT API FAQ documents real-world cases where metadata fetches fail because the contract returns an empty, malformed, or broken URI, or because the target endpoint responds incorrectly.

That is one reason serious collectors increasingly look beyond the token itself and ask where the metadata actually lives.

IPFS: The Most Common Decentralized Option

The most widely used alternative is IPFS.

The IPFS best practices guide for NFT data explains why IPFS fits NFT storage so well: it uses content addressing rather than location addressing. Instead of pointing to “a file on this server,” it points to content identified by a CID, a hash tied to the file itself.

That changes the trust model.

With a normal URL, the same link can serve different content later. With IPFS, if the content changes, the CID changes too. That gives NFT metadata and media stronger integrity guarantees, because the reference is tied to the actual file content rather than a mutable server path.

This is why so many NFT projects use ipfs:// links for metadata and media. It is not only about decentralization as branding. It is about reducing the chance that a token keeps the same pointer while the underlying content gets swapped out.

Why Pinning and Persistence Still Matter

IPFS is a strong solution, but it is not magic.

A file on IPFS does not remain universally available just because it has a CID. Someone still needs to keep that content pinned and retrievable. If no one persists it, availability can degrade even if the address remains valid.

That is why persistence is such a big part of NFT storage design. The Pinata explanation of how IPFS works with NFTs makes this practical point especially well: IPFS helps prevent tampering because the content address is immutable, but long-term availability still depends on pinning and continued network persistence.

So when people say “my NFT is on IPFS,” that is only part of the story. A better question is whether the content is pinned reliably, by whom, and for how long.

Fully On-Chain Metadata

At the other end of the spectrum is fully on-chain storage.

In this model, the metadata — and sometimes even the media itself — is generated or stored directly inside the smart contract. This is much more expensive, but it gives the NFT a stronger permanence profile because the token and its descriptive content live together on-chain.

The Chainlink NFT tutorial illustrates this clearly by showing how developers can generate an NFT with metadata and even SVG-based art stored on-chain rather than relying on an external storage layer.

Fully on-chain NFTs tend to work best when the media is lightweight or programmatic. Text-based, SVG-based, or generative projects are better candidates than large video files or heavy image sets.

This approach is often treated as the gold standard for permanence, but it comes with real trade-offs:

• higher minting costs
• more complex contract design
• tighter limits on asset size and format

So while on-chain metadata sounds ideal, it is not automatically the best solution for every project.

ERC-721 vs ERC-1155 Metadata Logic

From a collector’s perspective, ERC-721 and ERC-1155 may look similar. From a metadata standpoint, they differ in how the URI is structured.

ERC-721 typically resolves metadata on a per-token basis through tokenURI(tokenId). That works well for one-of-one assets or collections where each token has its own metadata file.

ERC-1155 often uses a template-based URI approach. Instead of defining a completely separate URI structure for every item manually, the metadata system can substitute {id} in a URI pattern to resolve the correct JSON file for each token ID.

That makes ERC-1155 especially efficient for game assets, semi-fungible items, or large collections where many token types live under one contract.

The practical point is simple: both standards support metadata, but they structure retrieval differently.

Why Metadata Choices Affect Value

Collectors often talk about rarity, art quality, floor price, and community. But metadata architecture matters too.

If a project stores metadata carelessly, it creates long-term risk:

• traits can disappear
• images can break
• marketplaces may fail to display the asset
• the token may become harder to verify or interpret

That does not always kill value, but it changes how much confidence buyers can place in the asset’s longevity.

For serious NFT projects, storage is part of credibility. A team that clearly communicates whether metadata is on-chain, on IPFS, or on a centralized server is usually giving collectors a much better signal than one that treats metadata as an invisible backend detail.

In other words, metadata is not just “how the NFT looks.” It is part of the NFT’s trust model.

The Most Common Mistake Beginners Make

Beginners often ask, “Where is the NFT stored?” as if there must be one single answer.

In reality, different layers are stored in different places:

• ownership is usually on-chain
• metadata may be on-chain or off-chain
• media may be separate from metadata
• marketplace previews may be cached again by third parties

So if you want to understand an NFT properly, you should ask three questions:

1. Where is the token contract?
2. Where is the metadata file?
3. Where is the media file referenced by that metadata?

That framing is much more useful than assuming the NFT is one indivisible object.

Conclusion

NFT metadata is the layer that gives a token meaning. It tells marketplaces what to display, tells collectors what traits exist, and tells applications which media to load.

That is why the question “where is the NFT stored?” usually has a more nuanced answer than people expect. Ownership is typically on-chain. Metadata may be on-chain, on IPFS, or on centralized infrastructure. The media may sit somewhere else.

Once you understand that structure, NFTs stop looking mysterious. They start looking like a stack: contract logic, metadata pointers, and media delivery.

And that is exactly why metadata design matters. It affects durability, portability, display quality, and ultimately trust. In the NFT world, the token may prove ownership — but metadata is what makes that ownership intelligible.

FAQs

What is NFT metadata?

NFT metadata is the descriptive information tied to a token. It usually includes the NFT’s name, description, image, and attributes, along with links or additional display fields.

Is NFT metadata stored on the blockchain?

Sometimes, but not always. Metadata can be stored fully on-chain, on decentralized storage such as IPFS, or on centralized web servers.

What is a token URI in NFTs?

Token URI is the function many ERC-721 contracts use to return the location of an NFT’s metadata file. In ERC-1155, the equivalent logic is typically handled through uri().

Are NFT images always on-chain?

No. In many projects, the image is stored off-chain and only referenced inside the metadata file.

Why do so many NFT projects use IPFS?

Because IPFS uses content-addressed storage, which makes it harder to tamper with metadata or media without changing the underlying address.

What happens if NFT metadata is stored on a normal server?

The token may still exist, but the metadata or media can break, disappear, or be changed if the server owner removes or alters the file.

Is fully on-chain metadata better?

It is usually stronger for permanence, but it is more expensive and not always practical for large files or media-heavy collections.