Open any Solana wallet and look at your token list. Each token shows a name, a ticker symbol, and usually a small logo — not just a 44-character mint address. None of that information lives in the core SPL token program itself. It comes from a separate layer called token metadata, and understanding how it works is one of the most overlooked parts of launching a token correctly. Get the metadata wrong, or skip it entirely, and even a technically flawless token will look broken, generic, or untrustworthy to anyone who encounters it in a wallet or on an explorer.
This article breaks down exactly how Solana token metadata works: the distinction between the mint account and the metadata account, how the Metaplex Token Metadata standard fits in, where the actual data is stored, what mutability means for your metadata, and the practical decisions you need to make when you create a Solana token. If you are building a serious project — not just experimenting — this is the layer that determines whether your token looks professional from the first transaction.
The Core Problem: SPL Tokens Are Anonymous by Default
When you create a new SPL token, you are really just initializing a mint account. That account stores a small, fixed set of fields defined by the SPL Token program: the number of decimals, the current supply, the mint authority (who can create more tokens), and the freeze authority (who can freeze individual holder accounts). That is it. There is no field for "name," no field for "symbol," and no field for "logo URL."
This is deliberate. The SPL Token program is intentionally minimal — it does one thing (fungible and non-fungible token accounting) and does it efficiently. Every additional byte stored on-chain costs rent, and baking in name/symbol/image fields would have bloated every single token account on the network, including the millions of tokens that never need a public identity (internal accounting tokens, test tokens, protocol-specific utility tokens, and so on).
The consequence is that, by default, a freshly minted SPL token is anonymous. If you look it up on an explorer or paste the mint address into a wallet, you will see the raw address and nothing else. For anyone building something people are actually meant to hold, trade, or recognize — a memecoin, a project token, a community currency — that anonymity is a problem. This is where metadata comes in.
Metaplex Token Metadata: The De Facto Standard
To solve the anonymity problem, Metaplex built a separate on-chain program called the Token Metadata program. It has become the de facto standard across the entire Solana ecosystem — every major wallet (Phantom, Solflare, Backpack), every explorer (Solscan, Solana Explorer), and every marketplace or DEX aggregator reads token metadata using this same standard. If you want your token to be recognized anywhere on Solana, this is the program that makes it happen.
Here is how it works mechanically:
- A metadata account is derived. Using a deterministic formula (a Program Derived Address, or PDA) based on the Token Metadata program ID and your token's mint address, a unique account address is calculated. This is not a random new keypair — it is mathematically derived, which is why every wallet and explorer can independently compute the same address just from knowing your mint.
- The metadata account is created and populated. A transaction creates this PDA and writes a small set of fields into it: the token's name, its symbol, a URI string, and some configuration flags (like whether the metadata is mutable, and whether the token is part of a collection, which matters more for NFTs than fungible tokens).
- The URI points elsewhere. Critically, the on-chain metadata account does not store your image or your long-form description directly — that would be expensive and impractical. Instead, it stores a URI (a link) to an off-chain JSON file that contains the richer data.
This two-layer design — a small on-chain pointer plus a larger off-chain JSON payload — is the key architectural idea to understand. On-chain, you are minimizing rent cost and keeping only what's essential for identity and authority. Off-chain, you have room for a full description, an image, external links, and attributes.
What's Actually in the On-Chain Metadata Account
The on-chain metadata account is compact by design. The fields that matter most for a fungible token are:
- Name — the full display name of your token, up to 32 bytes in the original spec (UTF-8 encoded, so effectively fewer characters if you use non-ASCII text).
- Symbol — the short ticker, up to 10 bytes, shown in wallet balances and trading pairs (e.g., "BONK", "WIF").
- URI — a link, up to 200 bytes, pointing to the off-chain JSON metadata file.
- Seller fee basis points — relevant for NFT royalties, generally irrelevant for fungible tokens and typically left at zero.
- Update authority — the wallet address permitted to modify this metadata account in the future, if it remains mutable.
- Is mutable flag — a boolean that, once set to false, permanently locks the metadata from further changes by anyone, including the original update authority.
Notice how tight these byte limits are. This is why the name and symbol you choose need to be deliberate from the start — you generally cannot use a 60-character marketing tagline as your token name, and abbreviations matter. If you are also thinking about decimals and total supply, treat metadata as part of the same up-front planning exercise rather than an afterthought bolted on later.
What's in the Off-Chain JSON File
The off-chain JSON file — the thing your URI points to — is where the richer detail lives. A typical structure looks like this:
{
"name": "Example Token",
"symbol": "EXTK",
"description": "A community-driven token on Solana.",
"image": "https://arweave.net/abc123...",
"external_url": "https://example.com",
"attributes": []
}
The image field is the one most people care about — it's what determines the logo shown in wallets and on trading interfaces. This file needs to be hosted somewhere permanent and publicly reachable. Two off-chain data structures need to be uploaded and linked correctly: the image asset itself, and the JSON document that references it. If either link breaks, your token effectively loses its face — wallets fall back to a generic placeholder icon, and any explorer or aggregator that cached the metadata may show stale or broken data.
On-Chain vs Off-Chain: Why Not Store Everything On-Chain?
It's a fair question — if metadata matters so much, why not just store the image and description directly in the blockchain account? The answer is almost entirely about cost and account size limits. Solana accounts have a rent-exempt minimum balance proportional to their byte size, and storing even a small compressed image on-chain (base64-encoded, no less, which inflates size by roughly a third) would cost dramatically more than storing a short URI string. Multiply that by every token ever created, and on-chain image storage would be economically unworkable at scale.
The off-chain-plus-pointer pattern is a pragmatic tradeoff: pay a small, fixed on-chain rent cost for the pointer, and let a separate storage layer handle the actual payload. The tradeoff you're accepting is that the durability of your metadata now depends on the durability of that off-chain storage.
Storage Choices: Arweave, IPFS, and Centralized Hosting
Not all off-chain storage is equal, and this decision has real consequences for your token's long-term integrity.
Arweave is a permanent storage network — you pay once, and the data is designed to persist indefinitely, replicated across a decentralized network of storage nodes. This is why most reputable token creation tools, including this one, default to Arweave for metadata and image hosting. There's no renewal fee, no expiring subscription, and no single company that can delete your file.
IPFS (InterPlanetary File System) is content-addressed storage where a file's address is derived from its content hash. It's decentralized in principle, but persistence depends on someone continuing to "pin" your file — if no node keeps pinning it, it can become unreachable even though the address technically still exists.
Centralized hosting (a regular web server, a cloud storage bucket, a URL on your own domain) is the riskiest option for token metadata. If your hosting lapses, your domain expires, or you simply take the file down, every wallet that references your token loses its image and possibly its name. For a token meant to last, this is a fragile foundation.
Mutable vs Immutable Metadata
When your metadata account is created, a decision gets baked in: is it mutable or immutable? This has meaningful implications and deserves real thought rather than a default click-through.
Mutable metadata means the update authority — usually your own wallet, at least initially — can change the name, symbol, image, or URI at any point after launch. This is useful if you expect to rebrand, fix a typo, or evolve the project. But it's also a trust signal that cuts both ways: sophisticated holders and analysts often check whether a token's metadata is mutable as part of their due-diligence process, precisely because a malicious project could theoretically swap out the image or description post-launch to mislead new buyers (though note this does not let anyone alter supply or transfer tokens — it only affects display information).
Immutable metadata permanently locks the name, symbol, and image pointer. No one — not even the original creator — can change it afterward. For projects aiming to build trust and signal that there's no hidden lever left to pull, immutability is often the safer public commitment, similar in spirit to revoking mint authority or revoking freeze authority to prove supply and account-freezing cannot be manipulated later.
That said, immutability is a one-way door. If you catch a typo in your token's description the day after launch, or decide the logo needs a refresh, you're out of options once metadata is locked. Many creators choose to keep metadata mutable for a short window after launch — long enough to fix any early mistakes — before deliberately revoking update authority once they're confident everything is correct. This mirrors how you'd approach mint and freeze authority: verify everything first, then lock it down for good.
Setting Up Metadata Correctly When You Create a Token
Here's the practical workflow, whether you're using this platform's token creation tool or building the transaction yourself:
- Decide your name and symbol first, and check the byte limits. Keep your symbol short (ideally 3-5 characters) and your name concise. Test that any special characters or emoji you want to use actually fit within the UTF-8 byte budget — an emoji can eat several bytes on its own.
- Prepare a clean, appropriately sized image. Most wallets display token logos as small square icons, so a square image (512x512 is a common safe choice) in PNG or a similarly well-supported format works best. Oversized files slow down uploads and rendering without adding visible benefit at the display sizes wallets actually use.
- Write a real description. Even though the description doesn't show up everywhere, aggregators and some wallets do surface it, and it's part of what makes a token look legitimate versus thrown together in five minutes.
- Choose your storage layer. If your tool defaults to Arweave, that's generally the right call for durability. Confirm the uploaded URI actually resolves before you finalize anything.
- Decide mutability deliberately. Don't just accept a default. If you're not fully confident in the final name, symbol, and image, keep it mutable initially, verify everything is correct, and consider locking it down afterward.
- Verify the result. After the mint and metadata transactions confirm, check your token in at least one wallet (Phantom or Solflare are good choices — see our wallet comparison if you haven't picked one yet) and on a block explorer to make sure the name, symbol, and image all display as expected.
Common Metadata Mistakes
A few patterns come up repeatedly with new token creators, and they're worth calling out directly.
Skipping metadata entirely to save a step. Some creators mint the token, get distracted, and never come back to add metadata. The token works technically, but it shows up as an unrecognizable address in every wallet, which kills trust and adoption before the project has a chance to get off the ground.
Uploading an image that's too large or the wrong aspect ratio. A rectangular banner image crammed into a circular wallet icon slot looks distorted and unprofessional. Stick to square images sized for icon display.
Using centralized, self-hosted links for the JSON or image. As discussed above, this creates a silent long-term failure mode — everything looks fine at launch, then months later the image quietly disappears because a hosting bill lapsed.
Not double-checking symbol collisions. Solana doesn't enforce unique symbols — nothing stops two different tokens from both using "MOON" as a symbol. This means users need to verify the mint address, not just the symbol, before trusting a token. As a creator, it's worth searching your intended symbol beforehand to avoid obvious confusion with an existing, unrelated project.
Confusing metadata authority with mint/freeze authority. These are separate permissions on separate accounts. Revoking mint authority does nothing to your metadata's mutability, and vice versa. If your goal is to present a fully "locked down" token to the community, you need to address all three independently: mint authority, freeze authority, and metadata mutability.
How Metadata Fits Into the Bigger Trust Picture
Metadata alone doesn't make a token trustworthy — a scam token can have a beautiful logo and a compelling description just as easily as a legitimate one can. What metadata does is remove one specific kind of friction and uncertainty: it lets people recognize what they're holding without doing forensic work on a raw address. Combined with other trust signals — a revoked mint authority so supply can't be inflated, a revoked freeze authority so accounts can't be arbitrarily frozen, transparent tokenomics, and a locked or thoughtfully managed metadata state — a well-presented token tells holders that the creator took the process seriously.
If you're evaluating a token someone else created, checking its metadata setup is a quick, useful signal alongside checking authorities directly. Our full security checklist walks through the complete set of checks, metadata included, that you should run through before trusting or launching any Solana token. And if you're setting one up yourself, the FAQ covers common questions about the creation process end to end, including where metadata fits alongside decimals, supply, and authority settings.
Metadata is a small piece of the overall token creation process in terms of the number of clicks it takes, but it has an outsized effect on how your token is perceived from the very first moment someone encounters it. Treat it with the same care you'd give to your supply and authority decisions, and your token will look — and feel — like a finished, professional project rather than a placeholder address with a number attached.