If you’ve ever wondered why some NFTs display beautiful artwork while others show broken images, or why certain collections have vanished entirely from existence, you’re looking at the difference between what lives on the blockchain itself and what lives elsewhere. That “elsewhere” is metadata, and understanding the distinction between on-chain and off-chain storage is critical before investing in or building anything in this space. Most people assume their NFT is safe as long as the blockchain exists. They’re often wrong.

This guide breaks down exactly what lives inside NFT metadata, how it’s stored, and the critical differences between approaches that make collections permanent versus those that can disappear overnight.

What NFT Metadata Actually Is

NFT metadata is structured data that describes the asset attached to a token. When someone mints an NFT, they’re creating a unique token on a blockchain that points to something—this could be an image, a video, a document, or even a physical item. The token itself only contains a reference to that asset and some basic information about it. That reference and accompanying details are what we call metadata.

The Ethereum standard that governs most NFTs—ERC-721—defines a structure where your token has a tokenURI field. This field contains a URL pointing to a JSON file. That JSON file is the metadata, and it contains everything a marketplace or application needs to display your NFT properly: the name, the description, the image or animation, and any attributes that make the NFT unique.

Here’s the part that trips people up: the token on the blockchain is essentially just a receipt. It says “token ID 37 belongs to address 0xABC… and its metadata lives at this URL.” If that URL stops working, your receipt now points to nothing. The blockchain didn’t delete anything—the blockchain is immutable—but the thing your token points to has vanished.

What’s Inside the Metadata JSON

Every NFT marketplace follows a roughly similar schema, though some add their own extensions. The standard comes from the OpenSea metadata standard, which has become the de facto expectation across the industry.

The required fields are straightforward:

name — A human-readable string identifying the NFT. “Bored Ape #8742” for example.

description — A text description of the asset. This field accepts markdown in some implementations, allowing creators to add clickable links or formatting.

image — A URL pointing to the primary visual asset. This should be a PNG, JPG, GIF, or SVG. The URL can point anywhere: a centralized server, IPFS, or Arweave.

Beyond those three required fields, several optional fields add functionality:

animation_url — Points to a video, audio file, 3D model, or any other rich media. When present, many marketplaces display this instead of the static image.

external_url — A link to the creator’s website or the collection’s main page. OpenSea displays this as a clickable link in their UI.

attributes — An array of trait objects that define the NFT’s characteristics. This is how “rarity” gets calculated. Each attribute has a trait_type (like “Background” or “Eye Color”), a value (like “Blue” or “Laser Eyes”), and optionally a display_type for numeric values.

Here’s a real example from the Bored Ape Yacht Club collection:

{
  "name": "Bored Ape #8742",
  "description": "The Bored Ape Yacht Club is a collection of 10,000 unique Bored Ape NFTs.",
  "image": "ipfs://QmRPkBxn2vPtCifV3W1j5K3qJ3LzP7x5yZGVq8PqVZyU8K/8742.png",
  "external_url": "https://boredapeyachtclub.com/#/ape/8742",
  "attributes": [
    {
      "trait_type": "Background",
      "value": "Orange"
    },
    {
      "trait_type": "Fur",
      "value": "Dark Brown"
    },
    {
      "trait_type": "Eyes",
      "value": "Laser Eyes"
    },
    {
      "trait_type": "Clothes",
      "value": "Lab Coat"
    }
  ],
  "animation_url": "ipfs://QmRPkBxn2vPtCifV3W1j5K3qJ3LzP7x5yZGVq8PqVZyU8K/8742.mp4"
}

Notice the use of IPFS URIs rather than HTTP URLs. This is a deliberate choice by the Bored Ape team, and understanding why leads directly into the storage question.

Where Metadata Gets Stored: The Three Main Approaches

The storage method is where things get interesting—and where most people make assumptions that don’t hold up. There are three primary approaches, each with significant trade-offs.

Centralized server storage is the simplest approach. The metadata lives on an AWS S3 bucket, a traditional web server, or a service like Pinata (which hosts IPFS content but manages it centrally). When you see a metadata URL that looks like https://api.myserver.com/nft/1234, it’s centralized storage.

This approach is cheap and easy to update. Creators can change the metadata whenever they want, which is useful if they need to fix typos or update attributes. However, the blockchain only stores the URL—not the content itself. If the server goes down, the domain expires, or the company behind it shuts down, every NFT pointing to that URL becomes a broken link. The Axie Infinity Ronin bridge hack in 2022 saw significant NFT data loss when centralized infrastructure was compromised, though the tokens themselves remained on-chain.

This is where conventional wisdom gets it wrong: people say “NFTs are permanent” when really, the token is permanent but the metadata usually isn’t. Centralized storage creates a single point of failure that undermines the entire value proposition of blockchain technology.

IPFS (InterPlanetary File System) is a distributed storage protocol that content-addresses files. Instead of https://myserver.com/image.png, you get ipfs://Qmhash... where the hash is derived from the file’s content. If you change even a single pixel in the image, the hash changes completely. If the image stays the same, the hash stays the same forever.

This is powerful because anyone who has the file can serve it. There’s no single server that must stay online. However, IPFS alone doesn’t guarantee permanence—it only guarantees that if the content exists somewhere, anyone can retrieve it. IPFS operates on a “garbage collection” model: if no one is actively storing the file (called “pinning”), the network may eventually drop it from their cache.

The solution is IPFS pinning services. Companies like Pinata, Filecoin (which uses IPFS underneath), and nft.storage will store your content and keep it available on the IPFS network. The Bored Ape Yacht Club uses this approach—they store their images and metadata on IPFS and use pinning services to ensure the content stays available.

Here’s the caveat: pinning services are businesses. They can change their pricing, shut down, or lose data. IPFS solves the “single server” problem but introduces a “need to maintain pinning” problem. True permanence requires either running your own IPFS node or paying for pinning indefinitely. Most projects don’t explain this to buyers.

Arweave takes a different approach. It’s designed specifically for permanent data storage with a one-time payment model. You pay once, and your data is stored forever—the protocol is built around economic incentives that make data retention economically rational for miners.

Arweave uses a different addressing scheme called “permaweb”— URLs look like ar://hash or you can use gateway services like https://arweave.net/hash. Several major NFT collections have adopted Arweave for this reason: the economic model genuinely does support permanent storage without ongoing fees.

The trade-off is that Arweave’s ecosystem is smaller than IPFS, and the technology has been around for less time. IPFS has more tooling, more developers familiar with it, and more pinning infrastructure. But for pure permanence guarantees, Arweave has a structural advantage.

One thing worth noting: Arweave has faced some criticism around data retrieval speeds and the completeness of its economic model over very long time horizons (decades to centuries). The protocol is still relatively young, and we’re essentially taking its creators at their word about long-term incentives. That’s not a reason to avoid it, but it is a reason to understand you’re making a bet on the model working as intended.

On-Chain Metadata: The Permanent Alternative

There’s a third option that addresses the permanence problem directly: storing everything on-chain. This means the JSON metadata lives directly in the smart contract, not in an external file.

This approach is used by collections like CryptoPunks (the original V1 contract) and some generative art projects. The token URI function returns a data URI containing the full JSON, which gets stored in the blockchain’s state.

The advantage is obvious: as long as the blockchain exists, your metadata exists. There’s no URL that can break, no pinning service that needs to be paid, no company that can shut down.

The disadvantage is cost and practicality. Storing data on Ethereum costs gas—significant gas. A full JSON file with attributes can easily run into kilobytes of data. At typical gas prices, storing 5KB of metadata could cost hundreds of dollars in transaction fees at peak congestion, and that’s just for one mint. Most projects find this impractical for large collections.

Additionally, on-chain metadata can’t reference external assets like high-resolution images without enormous cost. Some projects embed tiny SVG images directly in the contract, but this only works for simple graphics.

The middle ground some projects use: store the critical metadata on-chain (name, basic attributes) while keeping the image off-chain on IPFS or Arweave. This way, even if all external infrastructure fails, the basic token data survives. It’s not a common approach, but it demonstrates how the decisions around storage are genuinely architectural choices with real trade-offs.

What Happens When Metadata Goes Offline

This isn’t a theoretical concern. It’s happened multiple times in NFT history, and it typically destroys value for affected holders.

In 2021, a popular collection called “EtherBots” had their centralized metadata server go offline. The NFTs became essentially worthless because no one could view what the bots looked like or access their attributes. The tokens still existed on-chain—you could transfer them, trade them—but the entire value proposition (the visual art and game attributes) disappeared.

More recently, several smaller projects have faced this issue when their creators abandoned the project or ran out of funding for pinning services. The NFTs still technically exist, but marketplaces often don’t display them at all when metadata can’t be retrieved, or they show placeholder images that make the NFTs effectively unsellable.

The lesson: before buying any NFT, check where the metadata lives. If it’s a standard HTTP URL pointing to a single server, you’re trusting that server will stay online indefinitely. If it’s IPFS with active pinning or Arweave, you’re in better shape—but only if you verify that pinning is actually being maintained.

You can check this by pasting the IPFS hash into an IPFS gateway or using an IPFS inspection tool to see if content is available. For Arweave, similar tools exist. If the content is available through these protocols, you can reasonably expect it to stay available assuming the incentives hold.

The Key Distinction: Token vs Asset

Understanding this distinction resolves most confusion about NFT permanence. The token—the blockchain entry saying “address A owns token ID X”—is permanent. That record will exist as long as the blockchain exists.

The asset—the image, video, or metadata that gives the token meaning—is usually stored separately and can disappear. This is not a flaw in NFTs; it’s a fundamental architectural choice. Blockchains are expensive storage, so we use them to store references rather than the full content.

What matters is whether those references are robust. An IPFS content hash is robust because the content is content-addressed—if someone tries to swap the image, the hash changes, and you’d notice. An HTTP URL is fragile because the server can change the content without any verification mechanism.

Before buying any NFT, ask yourself: if this project’s website disappeared tomorrow, would I still know what I’m holding? If the answer is no, you’re taking on storage risk that may not be reflected in the price.

---

The NFT space is still young enough that storage standards continue to evolve. We’re seeing increased adoption of decentralized storage, but also more sophisticated approaches like Layer 2 solutions that try to balance cost, permanence, and flexibility. What won’t change is the fundamental reality: the blockchain stores a pointer, and you need to understand what that pointer is pointing to.

When evaluating any NFT purchase or building any NFT project, treat the metadata storage method as a primary due diligence factor. The visual art might be beautiful and the community might be engaged, but if the underlying infrastructure isn’t permanent, neither is your investment.