Decentralizing NFT metadata on OpenSea

An NFT is a unique token with decentralized ownership. The answer to the question “who owns this token?” is stored and tracked on many different computers simultaneously, preventing unauthorized changes to its possession.

But the media attachments and properties associated with NFTs (collectively called “NFT metadata”) have not been consistently decentralized due to the gas costs associated with storing and modifying data directly on smart contracts. Without decentralization, collectors can’t count on the integrity and immutability of a token’s metadata.

OpenSea has supported NFTs with decentralized metadata since we launched in 2017. Today, we’re announcing the ability for creators to decentralize their metadata using the Interplanetary File System (IPFS) and Filecoin when creating on the platform. We’re also providing a way for collectors to see when the metadata for an NFT is immutable or not, further augmenting the toolkit that OpenSea collectors have at their disposal when valuing NFTs.

Keep reading for info on how it all works and why decentralizing metadata matters, and check out our help center tutorial if you want to learn how to decentralize your OpenSea-made NFTs.

Decentralized vs frozen metadata

If you aren’t familiar with NFT metadata, the overview in our ever-popular NFT Bible is worth a read; otherwise, here’s a look at the technical details.

For Ethereum-based tokens, the smart contract that governs an NFT usually specifies the location of the metadata using a function:

  • For the ERC721 standard: function tokenURI(uint256 _tokenId) external view returns (string memory)

  • For the ERC1155 standard:  function uri(uint256 _id) external view returns (string memory)

The value returned by this function is often a URL in Google Cloud, Amazon Web Services, or some other form of centralized storage that can go offline or be mutated by the developer.

This is in contrast with decentralized storage solutions like IPFS, Filecoin and Arweave, which replicate metadata across storage nodes in a decentralized network.

Centralized storage is subject to two weaknesses:

  1. Impermanence: The server can go down or offline, making it hard to find the image (unless it was mirrored by an NFT index like OpenSea).

  2. Mutability: The developer can modify the image to something a collector does not expect.

There are four types of metadata storage for NFTs. Here’s a handy grid:

The concept of “frozenness” is distinct from centralization. Even when they are stored in a decentralized manner, it’s often still possible for the creator to make a transaction and change the metadata associated with an NFT. We call NFTs that have unchangeable metadata “frozen”.

Without better visibility on which NFTs are frozen and which are not, collectors can’t know if what they’re buying will be the same in 1, 10, or 100 years.

Not all NFTs fit cleanly into just one quadrant. Let’s go through them with some examples:

  1. Centralized: Most NFTs have a function on their smart contract to return the metadata associated with a particular token identifier. The result is often a URL on a web server run by the developer (e.g. When the properties and media of an NFT are all controlled by a server like this, the NFT is centralized, and will be subject to impermanence and mutability problems.

  2. Centralized and verifiable: One of the earliest NFTs, CryptoPunks by Larva Labs, stores its images in a centralized server. However, the smart contract stores the hash of this image in the smart contract. This means that while CryptoPunks may be subject to impermanence, any modification to its images can be checked against this hash, so we can “verify” if a CryptoPunk image is original or modified.

    Other projects, like CrypoKitties (API docs), have variations of this system, such as storing NFT traits on-chain but renderings of the traits in a centralized server. In this variation, the images can be modified, but the kitty “genes” and rarity information cannot.

  3. Decentralized: Instead of storing metadata in a central server, developers have the option to store it directly in the smart contract or in a file-friendly decentralized network. Two of the best options are IPFS with Filecoin and Arweave.

    Arweave requires miners to refer to data that was previously stored, similar to a blockchain (called their “blockweave”). IPFS allows peers to store, request, and transfer verifiable data with each other, and can be used with Filecoin to incentivize miners to continue storing data persistently with verifiable proofs.

    An example of this kind of project is Bored Ape Yacht Club. The metadata is stored in IPFS, though the root URI used for IPFS is changeable by the contract owner.

  4. Decentralized and frozen: It’s tricky to know when an NFT’s metadata is frozen or not, as there are usually multiple ways of changing it. This is a manual process, but OpenSea now shows when NFTs made on OpenSea have been frozen and when many NFTs outside of OpenSea are immutable as well:

    Clicking “Frozen” above takes you to the decentralized URI for the item if it’s on a file storage network, supporting IPFS and Arweave (including `ipfs://` and `ar://` URLs).

    Some examples of decentralized and frozen projects include:
    SuperRare (IPFS)
    Sandbox (IPFS)
    Uniswap (on-chain)
    1111 by Kevin Abosch (Arweave)

Note: some projects store their metadata directly in the smart contract. For example, a different project by Larva Labs, Autoglyphs, returns character art directly from the contract, and was the first NFT to do so. It does not depend on any other system aside from Ethereum to render the image, so we call it decentralized, on-chain, and (in this case) frozen.

There are benefits and drawbacks to all four approaches. But it’s helpful for collectors to know more about NFT implementation when making value-based decisions. That’s why we’re introducing a new event type to augment the ERC1155 and ERC721 standards so that developers can tell platforms like OpenSea when they intend to mark a specific NFT as “frozen”.

Permanent URIs

To solve the tension between frozen and unfrozen metadata, this new event will tell OpenSea to register a URI change as a “permanent” one, called PermanentURI. Here’s the event signature:

event PermanentURI(string _value, uint256 indexed _id);

After a PermanentURI event is emitted by an NFT smart contract, no one should be allowed to change the URI for the specific token ID again. More information is available in our docs. Like most standards in crypto, this is an ongoing development and subject to change based on community feedback.

Freezing NFTs on OpenSea

In December 2020, we launched a gas-free NFT creator to drastically reduce the barriers to entry for artists looking to sell their work on the blockchain. At the time, we added pre-emptive support for metadata freezing to the smart contract, meaning creators can now freeze the metadata for any unsold tokens in collections they’ve made over the last six months.

To get started, head to your collection’s “Edit” page and press the pencil icon in the top right corner of one of your NFTs (you can find them under the search bar below the “Add New Item” button). Click the Freeze Metadata toggle, and you’ll see a window pop up, as shown below. Tick the box if you’re happy to proceed, then click Submit Transaction. While OpenSea doesn’t charge anything, you’ll need to pay a gas fee to save the new metadata URL to the smart contract:

Once you freeze an NFT, you cannot unfreeze it or change its metadata. It will be available for as long as Ethereum and Filecoin exist.

After you’ve frozen an NFT, you can view its IPFS URL directly from its OpenSea page. You can also view more information about how many Filecoin deals have been made for it using the NFT.Storage API in combination with your NFT’s IPFS content hash. For example:

The Future of Decentralized Metadata

One of OpenSea’s missions is to provide a source of truth for any NFT, regardless of the blockchain, metadata format, or decentralized storage solution used to implement it. The future is going to be chaotic, and there will be many ways to create NFTs. We’re excited to bring more transparency to it.

Gas-Free Freezing

For the last six months, we’ve been excitedly launching support for the Polygon sidechain to provide users with a gas-free experience on OpenSea. For those with access to the private beta NFT minter, you can now freeze your Polygon NFTs to IPFS and Filecoin as well.

Just like with Polygon trading, there is no associated gas cost to save the IPFS URI to the NFT’s smart contract – OpenSea will pay it for you. Stay tuned for the larger release soon, and let us know what you think on Discord!

P.S. If you’re passionate about the nuances in NFT metadata, we’re hiring. Be sure to check out our open positions:

The featured image used for this article is part of the Art Blocks collection and is called Subscapes #638. It was created by Matt DesLauriers

12 curated works for CADAF Online

We’re excited to feature 12 independent artists for CADAF Paris’ virtual gallery, CADAF Online! From June 17 – 23, head to the CADAF | Artfair website to view work from some of OpenSea’s finest creators, as well as over 100 other participants from around the globe.

CADAF’s art fair will focus on NFT and blockchain art and will be deployed through a virtual and interactive platform that encourages and promotes communication between artists, collectors, and NFT enthusiasts. Visitors access individual booths via the 3D floor plan and utilize smart networking tools to engage with artists and one another. A variety of diverse cultural programming including 40+ artist talks, panel discussions, and screenings will be streamed during the fair.

Tickets | CADAF

The artists

Alex Alpert: NYC Goes Pink


I’m a stream of consciousness artist. My pieces are created in a free-form style – meant to express the various emotions and thoughts I am experiencing while I draw. I don’t consider anything that results in a mistake, I simply build off of what I have drawn and try to create a balance across the canvas.

Alex Alpert

NFN Kalyan: Far Wells Mill Valley


Kalyan was born in the United States to an Indian father and American mother and grew up between Wisconsin and his father’s native country.

Each one of Kalyan’s works is about the destructive nature of the human condition. He is hard but empathetic with the message. He says, “The great men we have killed, the environment we have destroyed and the lies we tell ourselves are terrible things. But we are supposed to hate the sin and love the sinner. And the sinner is everyone who looks at my work. And the sinner is me. Because we are all human.”

Jessica Perlstein: Sowing the Fabric of Reality


Jessica Perlstein is a visionary artist based out of San Francisco, CA.  Her biggest inspirations involve music, travel, and observing and working closely with nature.  She carries a strong message of taking action towards respecting a thriving planet and the resulting reality we can create when we choose to be aware of our symbiotic relationship with nature.  Her latest work emphasizes a movement toward environmental sustainability, merging ecological technologies and innovations within our current society to illustrate a thriving community. 

Schweenix: Papa November Whisky


Schweenix is a multidisciplinary artist based out of NYC, primarily engaged in art as a healing modality. They like drawing on their iPad, and sometimes go outside. They’re also part of the OpenSea community team.

Carlos Fama: Isolation

I am mixed media digital artist from Spain, I have been creating art since 2016. Part of my inspiration comes from artists like Basquiat, Salvador Dali and the world around us. I love combining black women with nature trying to represent the beginning of our existence on this planet.

Carlos Fama

Min Guen: Ape Mobile


Hi, my name is Min. I am a Senior Concept Artist with over 8 years of experience in the entertainment industry, successfully shipping numerous AAA titles/ feature films/ TV shows and games.

Min Guen

Cecil Touchon: Kaleidoscope #311


Internationally renowned and widely exhibited and published artist Cecil Touchon (b.1956 Austin, Texas) is known for his typographic abstractions, visual poetry, conceptual art, and collage art. His art has been seen in magazines, movies and television and even the Paris fashion runways via Japanese fashion designer Rei Kawakubo of Comme des Garçons fame.

Daniel Greenwood: Simulation


I’ve expressed myself through art and music as long as I’ve been alive. I do mixed media, physical and digital work that resembles the random thoughts and pictures I used to scrawl in notebooks when I was a kid. I’ve never grown out of that sense of excitement at creating something new and different. My experience as a human and my fascination with all of the darkness and beauty in this world are the overall themes of my work.

Daniel Greenwood

Zack Williams: The MediTaters


Zack is a Director, Animator, and Illustrator based out of New York.

Russ Morland: Fancy Protector Redux


Born and raised in England’s cold North, I found a passion for creatures of the night and rad skateboard vibes. I mixed all my 80s inspiration together in a chaotic melting pot in college and university through the 90s and by the time the 2000s were upon us I was doing some pretty weird art, what you see today is a culmination of these things… also mushrooms.

Russ Moorland

The Lightclinic: Horseshoe Crab #1


David Lobser specializes in aesthetic therapeutics. Visuals and sound can be combined to directly affect human physiology. Such works can be described as “digitceuticals” or “cyberdelics”. Art, like medicine, can alter perspective and expand awareness so as to create a vessel for healing and deepening connections to one’s interior landscapes. “Visitations” is a VR gallery which uses auditory and visual strobing with form constants and breathing rhythms to create hypnotic states in the viewer. “Cosmic Sugar” is a creative VR sandbox that helps produce states of flow via sculpting stardust with powerful forces. David Lobser is a research fellow at Johns Hopkins and adjunct professor of digital art at Harvard and Colorado University. A purchase of an NFT from this collection will help support ongoing research in the nascent field of digital therapeutics.

Mirage Gallery: Collector


Mirage Gallery is creating entirely AI-generated artists. Everything from their headshots to their artwork is created by artificial intelligence. These artists will continue to train and improve over time and will only ever create around 100 works of art.