Metadata Standards
Providing asset metadata allows applications like OpenSea to pull in rich data for digital assets and easily display them in-app. Digital assets on a given smart contract are typically represented solely by a unique identifier (e.g., the token_id in ERC721), so metadata allows these assets to have additional properties, such as a name, description, and image.
For OpenSea to pull in off-chain metadata for ERC721 and ERC1155 assets, your contract will need to return a URI where we can find the metadata. To find this URI, we use the tokenURI method in ERC721 and the uri method in ERC1155. First, let's look closely at the tokenURI method in the Creature contract.
The tokenURI function in your ERC721 or the uri function in your ERC1155 contract should return an HTTP or IPFS URL. When queried, this URL should in turn return a JSON blob of data with the metadata for your token. You can see an example of a simple Python server for serving metadata in the OpenSea creatures repo here.
See the section on IPFS and Arweave below for how to handle decentralized metadata URIs.
OpenSea supports metadata that is structured according to the official ERC721 metadata standard or the Enjin Metadata suggestions.
Additionally, we support several other properties that allow for multimedia attachments — including audio, video, and 3D models — plus interactive traits for your items, giving you all the sorting and filtering capabilities on the OpenSea marketplace.
Here's an example of metadata for one of the OpenSea creatures:
Here's how each of these properties work:
| image | This is the URL to the image of the item. Can be just about any type of image (including SVGs, which will be cached into PNGs by OpenSea), and can be IPFS URLs or paths. We recommend using a 350 x 350 image. |
| image_data | Raw SVG image data, if you want to generate images on the fly (not recommended). Only use this if you're not including the image parameter. |
| external_url | This is the URL that will appear below the asset's image on OpenSea and will allow users to leave OpenSea and view the item on your site. |
| description | A human readable description of the item. Markdown is supported. |
| name | Name of the item. |
| attributes | These are the attributes for the item, which will show up on the OpenSea page for the item. (see below) |
| background_color | Background color of the item on OpenSea. Must be a six-character hexadecimal without a pre-pended #. |
| animation_url | A URL to a multi-media attachment for the item. The file extensions GLTF, GLB, WEBM, MP4, M4V, OGV, and OGG are supported, along with the audio-only extensions MP3, WAV, and OGA. |
The maximum file size for media supported is 100MB, but we recommend keeping it under 100MB for faster load times.
To give your items a little more pizazz, we also allow you to add custom "attributes" to your metadata that will show up underneath each of your assets. For example, here are the attributes for one of the OpenSea creatures.
To generate those attributes, the following array of attributes was included in the metadata:
Here trait_type is the name of the trait, value is the value of the trait, and display_type is a field indicating how you would like it to be displayed. For string traits, you don't have to worry about display_type .
For numeric traits, OpenSea currently supports three different options, number (lower right in the image below), boost_percentage (lower left in the image above), and boost_number (similar to boost_percentage but doesn't show a percent sign). If you pass in a value that's a number and you don't set a display_type , the trait will appear in the Rankings section (top right in the image above).
Adding an optional max_value sets a ceiling for a numerical trait's possible values. It defaults to the maximum that OpenSea has seen so far on the assets on your contract. If you set a max_value , make sure not to pass in a higher value .
OpenSea also supports a date display_type . Traits of this type will appear in the right column near "Rankings" and "Stats." Pass in a unix timestamp (seconds) as the value.
If you don't want to have a trait_type for a particular trait, you can include just a value in the trait and it will be set as a generic property. For example,
A couple of important notes when coming up with your attributes! You should include string attributes as strings (remember the quotes), and numeric properties as either floats or integers so that OpenSea can display them appropriately. String properties should be human-readable strings.
You're welcome to deploy your metadata API however you see fit: you can host it on IPFS, cloud storage, or your own servers. To get you started, we've created a sample API server in both Python and NodeJS:
We'll create a tutorial on building and deploying your metadata server to Heroku soon! In the meantime, check out Heroku's resource on the subject.
OpenSea supports the storage of NFT metadata in decentralized file networks, so that they can’t be modified by a central party.
If you use IPFS to host your metadata, your URL should be in the format ipfs://<hash> . For example, ipfs://QmTy8w65yBXgyfG2ZBg5TrfB2hPjrDQH3RCQFJGkARStJb . If you plan to store on IPFS, we recommend Pinata for easily storing data. Here's a tutorial by Chainlink for getting started: https://blog.chain.link/build-deploy-and-sell-your-own-dynamic-nft/.
Arweave's equivalent is ar://<hash> . For example, ar://jK9sR4OrYvODj7PD3czIAyNJalub0-vdV_JAg1NqQ-o .
You can indicate to OpenSea that an NFT's metadata is no longer changeable by anyone (in other words, it is "frozen") by emitting this event from the smart contract:
event PermanentURI(string _value, uint256 indexed _id);
Contact us if you'd like to mark an entire smart contract as frozen.
To refresh token metadata on OpenSea, you can emit on-chain events as defined in ERC-4906:
event MetadataUpdate(uint256 _tokenId);
event BatchMetadataUpdate(uint256 _fromTokenId, uint256 _toTokenId);
To refresh a whole collection, emit _toTokenId with type(uint256).max
For ERC1155, metadata updates are supported via the specification for the event URI :
event URI(string _value, uint256 indexed _id);
OpenSea supports events to signal that a token should not be eligible for trading. This helps prevent "execution reverted" errors for your users if transfers are disabled while in a staked or locked state.
These events are:
OpenSea only uses the tokenId event parameter to enable or disable trading and does not use any of the other parameters.
How to Refresh Metadata on OpenSea with Simple Steps
OpenSea can pull data for digital assets and display them in their marketplace thanks to metadata, which is information that is embedded in the smart contract for an NFT. Digital assets such as NFTs contain metadata that shows details like special characteristics, names, descriptions, and images, ultimately allowing OpenSea to display them on their user interface.
Table of Contents
What is OpenSea Metadata?
A set of data called OpenSea metadata is used to describe an NFT’s attributes as well as its name, description, and link to the image asset.
The value of an NFT can occasionally vary by millions of dollars depending on these characteristics, also known as traits in the NFT space.
And while the dictionary definition of metadata is “a set of data that describes and gives information about other data” one important difference with OpenSea metadata is that it can change, which means there might be times when you want to refresh that data.
NFT project creators can effectively make the content dynamic rather than static by updating metadata to reflect trait evolutions of an NFT, cleaning up the metadata information, changing out the image asset, and adding new traits.
This has benefits and drawbacks because you don’t want your million-dollar NFT image asset URL to change, but some projects routinely update metadata to reflect updated characteristics and other crucial information about the asset (Example: if the asset grants access, has that access been used or not).
You might have recently minted an NFT but are unsure of its rarity or other characteristics, which is another reason to update OpenSea metadata. Following these instructions to refresh will add your asset to a queue for updating the metadata because unrevealed NFTs don’t display the asset image.
How to Refresh Metadata on OpenSea
On OpenSea, updating metadata is incredibly simple and can be done on any of the supported networks, including Ethereum, Solana, Polygon, Avalanche, and more. Follow the two steps below to get started:
- Step One: Go to the NFT page in your wallet or any other NFT with OpenSea metadata that you want to update.
- Step Two: Click the ‘Refresh Metadata’ button
The moment you press this button, the Metadata will instantly update and retrieve information from the NFTs smart contract to check if any of the properties have changed.
How Do I View the OpenSea Metadata for Any NFT?
- Navigate to Opensea.io in your web browser
- Click the project name link after typing the name of an NFT project. Be sure to click on the verified collection link which will contain a blue checkmark
- Click on an NFT asset on the project page that you want to see metadata for
- Scroll down and click Details
- Click on the Token ID
Does Refreshing Metadata on OpenSea Charge a Fee?
Metadata updates on OpenSea and alternative NFT Marketplaces like LooksRare, MagicEden, and Gem.XYZ are entirely free. This is so that the marketplace can pull the metadata from an off-chain data compiler since it is not an on-chain transaction.
About OpenSea
On the Ethereum blockchain, there exists a decentralized market called OpenSea for digital assets. Devin Finzer and Alex Atallah established it at the beginning of 2017. With millions of users and a daily trading volume of over $20 billion in digital assets, OpenSea has since developed into one of the biggest and most well-known decentralized marketplaces.
Users can purchase, sell, and discover a wide range of digital assets on OpenSea, including collectibles, gaming gear, and more. One of the distinguishing characteristics of OpenSea is that it enables users to look for assets using metadata, such as category, price, or even custom keywords.
How to refresh metadata on Opensea?
New York-based Opensea is one of the most popular NFT marketplaces out there that has grown significantly in the past year of its four-year-long existence.
Non-fungible tokens are all the rage these days, with people spending hundreds of thousands on a single purchase. Several NFT collections such as the Bored Ape Yacht Club and CryptoPunks have become notoriously popular among enthusiasts, and these two, in particular, have also seen a significant dip (around 50% overall) in their item values.
If you’re looking into the NFT market for short-term or long-term investments or are just out here to have fun riding the wave, you already know that metadata of an NFT is vital.
In the case of NFTs, the metadata contains the actual content and its description as mentioned in the contract stored on the blockchain. NFT metadata includes the item name, media, description, properties, levels and stats.
Here we’ve explained how to quickly refresh the metadata of an NFT on Opensea.
Refresh metadata on Opensea
Refer to the screenshot and follow the steps mentioned below to refresh metadata on Opensea.
- Select your preferred NFT on Opensea.
- On the NFT’s page, tap/click on the refresh button at the top of the page.
- If the action is successful, you’d see the following message: “We’ve queued this item for an update! Check back in a minute…“.
Note, as the message mentioned, it can take some time for the NFT’s metadata to refresh. Also, neither F5 nor Ctrl + R will refresh the NFT metadata, so you’ll have to use the refresh button at the top of the specific NFT page.
You can’t refresh metadata for several NFTs at once or even a collection; you’ll have to refresh them one at a time.
Refresh Metadata on OpenSea
Our mission is to help you make informed decisions. While we adhere to editorial integrity, some posts may feature our partners. Here's how we make money.
Summary: Refreshing metadata on OpenSea, a pioneering NFT marketplace, is a simple process across several networks including Ethereum, Solana, Polygon, and Avalanche. This process involves locating your NFT, clicking 'Refresh Metadata', and verifying the update.
This action is free of charge, unlike on-chain transactions, as it retrieves data off-chain, bypassing any blockchain transaction fees. OpenSea, established in 2017, is a leading platform for trading a wide range of digital assets and is known for its metadata-based search feature.
How to Refresh Metadata on OpenSea
Refreshing or updating Metadata on OpenSea is a straightforward process and can be accomplished promptly across several networks like Ethereum, Solana, Polygon, Avalanche, etc. Here are the easy-to-follow steps to get you started:
- Locate Your NFT: Visit the specific NFT page within your digital wallet or seek out any other NFT whose metadata you are interested in updating on OpenSea.
- Update Metadata: Look for the 'Refresh Metadata' button (as illustrated in the image below) and click on it to initiate the refreshing process.
- Verification: Finally, you'll want to ensure that your action has taken effect. To verify that the metadata has been updated, reload the page and inspect the NFT's details. The refreshed data should be visible, confirming that the metadata update was successful.
Does Refreshing Metadata on OpenSea Charge a Fee?
Rest assured, updating or refreshing metadata on OpenSea, as well as on alternative NFT Marketplaces like LooksRare, MagicEden, or Gem.XYZ, is totally cost-free. This is primarily due to the fact that the metadata update is an off-chain process rather than an on-chain transaction.
This means the marketplace retrieves the metadata from an off-chain data compiler, negating the need for a blockchain transaction fee. Therefore, you can freely perform these updates without worrying about incurring extra costs.
About OpenSea
OpenSea, a pioneering decentralized marketplace on the Ethereum blockchain, was established in 2017 by Devin Finzer and Alex Atallah. Since its inception, OpenSea has evolved into a leading platform with millions of users and over $20 billion traded in digital assets.
The marketplace enables users to buy, sell, and delve into a broad spectrum of digital assets, including collectibles and gaming items. A standout feature is its metadata-based search, allowing users to find assets using filters like category, price, or custom keywords. From beginners purchasing their first crypto kitty to seasoned traders dealing in rare NFTs, OpenSea is a go-to destination. For a deeper insight into its offerings, consider reading our detailed OpenSea Review.
Final Thoughts
In summary, refreshing metadata on OpenSea is a simple, speedy process on networks such as Ethereum, Solana, Polygon, and Avalanche. It involves locating your NFT, updating the metadata, and verifying the change. Importantly, this is a free action on OpenSea and similar platforms, as it's an off-chain operation that bypasses blockchain transaction fees.