December 20, 2022

Ultimate Guide to Token Metadata

Table of Contents

Whether you’re an NFT collector or a dapp developer, it’s important to understand what token metadata is and how it works. After all, this data expands the functionality of fungible and non-fungible tokens (NFTs). If you’d like to explore this topic further, then follow along in this article. Not only will you learn what it is and the various functionalities token metadata brings, but you’ll also learn more about metadata for different types of tokens. Additionally, we’ll explore some of the most popular token standards.

It’s worth pointing out that mastering token metadata is not essential if you don’t plan to mint tokens. However, knowing the basics of this subject will help you make the most out of the tools helping you fetch on-chain data and metadata, such as Moralis’ NFT API. With the basics under your belt and the best tools on your side, you’ll be able to create all sorts of dapps. After all, you have to work with token metadata sooner or later regardless of what type of project you’re planning to develop, whether that be a portfolio tracker, an NFT marketplace, or even a Web3 game. 

While tackling those challenges, it’s crucial to avoid reinventing the wheel. Ultimately, no competent dapp developer wants to spend time and money on building the infrastructure that already exists. So, if you want to start building killer dapps without breaking a sweat or the bank, make sure to create your free Moralis account.     

graph exploring the sequence of how token metadata works

What is Token Metadata?

Token metadata are pieces of information (data) focusing on what a particular fungible or non-fungible token represents. Moreover, metadata plays a vital role regarding NFTs. Thus, we’ll primarily focus on NFT metadata in today’s guide. However, you’ll also have an opportunity to learn the essentials about fungible token metadata herein. With that said, let’s look at the following image:     

code structure outlined of an nft token metadata contract

The above structural example shows the gist of non-fungible token metadata (for ERC-721 tokens). It’s worth pointing out that, unlike fungible tokens, NFTs come with NFT-representing files. These files can be in all sorts of formats; however, the most common ones are image files (JPEGs, PNGs, etc.). Furthermore, NFT-representing files are not stored on the blockchain because they are too large. As such, token metadata is used to accommodate links to those files; ideally, those files are stored using decentralized storage solutions.

Nonetheless, although metadata files are typically a lot smaller, it’s still neither economically nor technically sound to store them on the blockchain. Consequently, decentralized storage solutions typically host metadata files, and IPFS remains one of the most popular decentralized storage protocols. However, there are other reputable alternatives (see the “Bonus” section below).  

So, if neither NFT-representing files nor NFT metadata are stored on-chain, what can be stored on a blockchain? In short, URIs. These are links pointing to token metadata files (usually JSON files). That said, NFT metadata and URIs tend to be used interchangeably. The URI link contains the details as presented in the image above, and the following offers a broader perspective:

diagram showing token metadata for an nft on an nft marketplace

Additionally, token metadata details vary depending on the token standard. For instance, the above image represents the ERC-721 standard example. However, in general, you can expect token metadata to at least include the name and the symbol of an NFT. 

smart contracts

How Does Token Metadata Work?

If you want to know how token metadata works, you need to learn the basics of smart contracts. After all, there is a smart contract behind every token. Furthermore, these on-chain pieces of software include the above-explained URIs to store them in the blockchain database. Moreover, it’s worth repeating that smart contracts ensure that predefined automated actions follow specific predefined rules, which are triggered when specific predefined conditions are met. All in all, to mint NFTs, devs need to deploy tokens’ smart contracts, which also regulate tokens’ transactions and ownership.

The above means that if you want to mint your own NFTs, you need to create your own smart contract. The latter needs to follow one of the NFT standards. In addition, when deploying smart contracts, you decide which blockchain network (Ethereum, BNB Chain, Polygon, etc.) you want to focus on. However, fortunately, there are some shortcuts making this process pretty straightforward. For instance, you can use OpenZeppelin for EVM-compatible chains or Metaplex for Solana. These open-source tools provide you with verified NFT smart contract templates. 

Aside from smart contracts, metadata for NFT storage plays a significant role. After all, providing a link to your NFT metadata in a smart contract is vital. As already explained above, token metadata files are not stored on the blockchain. Instead, devs use cloud storage solutions for that purpose. Ideally, all NFT creators follow the highest possible levels of decentralization and store token metadata in a decentralized manner. Nonetheless, to better understand how NFT metadata is stored, let’s look at the following illustration:

process from smart contract to metadata for a contract into an actual nft image

Note: Instead of the Ethereum blockchain, you can deploy smart contracts to any other programmable chain. Also, instead of IPFS, you may use any other storage solution (preferably decentralized ones).

Bonus: Decentralized Storage Solutions

This bonus section is for those of you who might decide to create NFTs down the road. In that case, you’ll want to store your NFT-representing files and your token metadata in a decentralized way. InterPlanetary File System (IPFS) is currently the best solution for most NFTs. You can learn more about this solution in our “IPFS NFT” article. However, if you prefer to focus on blockchain-based storage, these are some of the reputable options: 

  • Filecoin
  • Crust Network
  • Arweave
  • Holo
  • Storj
  • Sia

Metadata for Different Types of Tokens

So far, we’ve primarily focused on NFT metadata. Why? Because you’ll most likely deal with that type. However, this ultimate guide wouldn’t be complete without at least touching base with fungible tokens (e.g., ERC-20 tokens). Moreover, just like NFTs, fungible tokens (FTs) are also minted and managed by smart contracts. These types of Web3 contracts mint FTs based on specific pieces of information. The latter consist of optional and mandatory data. For instance, the contract address and the total supply of tokens are the two essential details that define ERC-20 contracts. 

On the other hand, the optional pieces of information include the token name, symbol, and decimal numbers. It is these optional details that represent fungible tokens’ metadata. Furthermore, many users consider fungible tokens’ logos as part of the metadata. However, technically, metadata and a token’s logo are separate things. After all, FTs’ logos can’t be stored on the blockchain, but their metadata can be. 

token attributes shown on a token metadata contract documentation page

However, a quality fungible token metadata API, such as the Moralis Token API, will also fetch a token’s logo. Essentially, this “ultimate ERC20 token API” makes fetching the balance of ERC20 tokens and native coins straightforward. 

Nonetheless, the token metadata also varies based on token standards. As such, let’s cover that aspect as well.

erc20, erc721, and erc1155 standards side by side

Token Standards

As you may know, there are various token standards. However, since Ethereum continues to be the king among programmable chains, ERC standards govern most of the tokens available. As pointed out above, these standards also determine the structure of token metadata. Furthermore, besides the ERC-20 standard (which we mentioned earlier), the other two standards we want to talk about are ERC-721 and “ERC 1155” (ERC-1155). The former was the first NFT standard and currently governs many older NFTs. However, these days, it’s only used for simple NFT projects. Why? Because ERC-1155 expanded the possibilities and has become the gold standard for NFTs.

three column table showing token standards and their important metadata

What’s more, ERC-1155 is, in fact, a multi-token standard. It supports fungible, non-fungible, and even semi-fungible tokens. Consequently, it is the latest go-to umbrella standard for production purposes. Thus, we’ll take a closer look at this standard’s token metadata layout herein. This will help you when working with token metadata and also if you decide to create your own tokens.

Note: If you’d like to explore this standard in more detail, compare it with ERC-721, and learn about semi-fungible tokens, use the “ERC 1155” link above.

ERC-1155 Token Metadata

This article wouldn’t be complete without looking at an actual token metadata example. So, here’s a generic ERC-1155 metadata JSON file:

    "title": "Token Metadata",
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "description": "Identifies the asset to which this token represents"
        "decimals": {
            "type": "integer",
            "description": "The number of decimal places that the token amount should display - e.g. 18, means to divide the token amount by 1000000000000000000 to get its user representation."
        "description": {
            "type": "string",
            "description": "Describes the asset to which this token represents"
        "image": {
            "type": "string",
            "description": "A URI pointing to a resource with mime type image/* representing the asset to which this token represents. Consider making any images at a width between 320 and 1080 pixels and aspect ratio between 1.91:1 and 4:5 inclusive."
        "properties": {
            "type": "object",
            "description": "Arbitrary properties. Values may be strings, numbers, object or arrays."

Looking at the above file, you can see that it contains a title, type, and properties. Then, inside properties, you can see the name, decimals, description, image, and properties. Furthermore, each of these objects contains “type” and “description”. You can find all the details about every specific object next to the “description”. 

robot with its features extracted and outlined as token metadata

When it comes to utilizing NFTs, the last “properties” object is the most useful one. After all, the latter enables NFT creators to extend the above schema with their own arbitrary properties without affecting the top-level namespace. Though, using the “properties” object is, of course, optional. Moreover, the elements that devs add are known as NFT attributes or traits. Nonetheless, here’s an example array of attributes:

"attributes": [
		"trait_type": "Background",
		"value": "Green"
		"trait_type": "Head",
		"value": "Hat"
	"trait_type": "Level",
	"display_type": "number", 
	"value": 10

We recommend you keep an eye on NFT attributes as they play a key role in expanding the use cases of NFTs in Web3 gaming.


Working with Token Metadata

At this point, you know that token metadata is an important part of Web3 development. So, whether you want to work with the details of the tokens you deployed or existing ones, you need a reliable and fast tool to fetch that data. As mentioned in the introduction of today’s article, this is where Moralis offers you the ultimate solution. With its NFT API and Token API, you can query all leading chains and get parsed data. This makes dapp development and token implementation as straightforward as it gets. For example, with this tool in your corner, you can obtain NFT collection data and metadata with a single line of code.

moralis get nft collection data documentation page

As indicated in the above screenshot, you can find all the API endpoint references in the Moralis documentation. This is also the place to tackle all sorts of beginner-friendly dapp development tutorials. However, if you want to take on some easy-to-follow video tutorials on how to use token metadata, watch the two videos below. In these videos, one of our in-house developers explores various token metadata topics and tutorials. These include how to get metadata by symbol and also how to get metadata by a contract address! If you’d like to follow along in the tutorials, make sure first to create your free Moralis account!

Ultimate Guide to Token Metadata – Summary

The sections above took you on quite a journey. Even if you knew nothing about token metadata, you now know more than enough to join the Web3 revolution. At this point, you know what this type of metadata is and how it works. You also know the key differences between NFT and FT metadata. Nonetheless, you also had an opportunity to get acquainted with the ERC-1155 token metadata standard. Lastly, we quickly explained what makes Moralis the best solution for working with token metadata, as illustrated in the two attached video tutorials!

Moving forward, make sure to dive into Moralis’ docs. This resource is all you need to take your legacy skills and become a dapp developer for free. In addition, the Moralis YouTube channel and the Moralis blog can assist you further in exploring other blockchain development topics. For instance, you can learn all you need to know about Ethereum Python implementation, getting all NFT transfers, listening to smart contract events using ethers.js, calling a smart contract function from JavaScript, Web3 py, and much more.   

On the other hand, you can take a more professional approach to your crypto education. If that interests you, you should enroll in Moralis Academy. There, you can become blockchain certified by completing all sorts of blockchain development courses. By enrolling, you can significantly improve your chances of going full-time crypto. Moreover, we encourage you first to cover blockchain and Bitcoin fundamentals. Aside from top-notch courses, this online academy is also the place to get expert mentorship and become a member of one of the most advancing communities. Accordingly, it’s a great place to meet and connect with like-minded folks who already see the power of Web3.  

Moralis Money
Stay ahead of the markets with real-time, on-chain data insights. Inform your trades with true market alpha!
Moralis Money
Related Articles
March 16, 2023

Token Allowance Checker – View Wallet Token Approvals

December 19, 2022

Ultimate Guide to Ethers.js Events and How to Use Them

September 15, 2023

NFT Image API – How to Get Images from NFT Collections

December 27, 2022

Easy Web3 Programming Tutorial for Blockchain Development

December 13, 2022

Tutorial for Blockchain Developers on How to Get All Transfers of an NFT

January 10, 2023

The 2023 Guide to Avalanche’s Fuji Testnet & Avalanche Faucets

October 6, 2022

​​BNB Chain Boilerplate – How to Build BNB Chain Dapps

November 8, 2022

How to Get All NFTs from a Contract