Solana token metadata JSON: fields, image rules and hosting
A Solana token's name and image are not stored in the mint account. The mint points to a metadata account, which stores a name, a symbol and a URL. Wallets and explorers fetch that URL and read a JSON file. Get the JSON wrong and the token shows up as an anonymous address.
What is on chain and what is not
- On chain (Metaplex metadata account): name (up to 32 bytes), symbol (up to 10 bytes), URI (up to 200 bytes), and whether the metadata can still be changed.
- Off chain (the JSON at the URI): description, image, links and attributes.
The JSON
{
"name": "Demo Token",
"symbol": "DEMO",
"description": "What the token is for, in a sentence or two.",
"image": "https://developers.tokenanvil.store/i/<id>.png",
"external_url": "https://example.com",
"attributes": [{ "trait_type": "Category", "value": "Community" }],
"properties": {
"files": [{ "uri": "https://developers.tokenanvil.store/i/<id>.png", "type": "image/png" }],
"category": "image"
}
}Keep name and symbol identical to the on-chain values. image must be a direct, public https link to a PNG, JPEG or WebP file; keep it under 1 MB and roughly square (512 by 512 pixels is a safe size). Link fields must be real https URLs.
Hosting matters more than people expect
If the image or JSON goes offline, the token loses its identity in every wallet. Prefer hosting that is stable, public and served with the right content type. POST /v1/metadata does this for you: it validates the fields, checks the image by its file signature rather than its extension, stores both files and returns permanent /m/ and /i/ URLs served with long-lived caching. If you prefer to host elsewhere, pass your own https URL as metadataUri to /v1/tokens.
Immutable or mutable?
By default the metadata stays mutable so you can fix a mistake or update the image. Set immutableMetadata: true when you want to lock it permanently. Locking metadata is separate from revoking the mint authority, which locks the supply.
For a plain-language explainer aimed at people creating a token in an app, see SPL token metadata on TokenAnvil.