What Token Metadata JSON Must Contain
A Solana token's on-chain record stores only three things via Metaplex: a name, a symbol, and a URI. Everything else - the logo, description, and links - lives in the JSON document that URI points to. Wallets and explorers fetch that JSON to render your token, which is why one malformed field can leave a token nameless or logoless everywhere at once.
| Field | Required | Rules that matter |
|---|---|---|
| name | Yes | Must match the on-chain name. The on-chain field caps at 32 characters, so keep the JSON name to 32 or less too. |
| symbol | Yes | Ticker shown next to balances. On-chain cap is 10 characters. Uppercase by convention. |
| image | Yes | Direct HTTPS (or ipfs:// / ar://) link to the logo file itself, not a webpage. Square PNG or WEBP, 512x512 or larger, hosted somewhere permanent. |
| description | Recommended | One or two sentences. Wallets truncate long text; screeners quote it verbatim. |
| external_url | Optional | Your project website. Some explorers display it as the official link. |
| extensions | Optional | Object holding social links (website, twitter, telegram). Screeners like DexScreener read these. |
| properties.files | Optional | Array describing the image file(s) with uri and type. If present, it should include the same URL as image. |
The Mistakes That Actually Break Tokens
The image URL points at a page, not a file
A link to an imgur page, a Google Drive share, or a Dropbox preview returns HTML, not an image. Wallets show a blank logo. The URL must return the raw image bytes when opened directly.
Name or symbol over the on-chain limit
The on-chain fields are fixed at 32 and 10 characters. If your JSON says something longer, the two records disagree and explorers may display the truncated on-chain value next to your full JSON value.
NFT fields on a fungible token
Fields like attributes, seller_fee_basis_points, and creators come from the NFT standard. Wallets ignore them on fungible tokens, and screeners occasionally misclassify tokens that carry them. Cleaner to leave them out.
Metadata hosted somewhere temporary
If the JSON or image goes offline, your token loses its identity everywhere at once. Use permanent storage (Arweave, IPFS with pinning) or hosting you control long-term, never a free file host.
For the full picture of how the on-chain record and the JSON interact, read our SPL token metadata guide. Token-2022 mints can store metadata directly on the mint instead; see the Token-2022 extensions reference.