XRPL NFT Metadata & IPFS Storage Guide
How metadata works for XLS-20 NFTs on the XRP Ledger: storage options, JSON format, URI resolution, and best practices.
At a Glance
NFT Standard
XLS-20
Metadata field
URI (256 bytes)
Common storage
IPFS / Arweave
On-chain option
Memo field
How XRPL NFT Metadata Works
When you mint an NFT on the XRP Ledger using NFTokenMint, you set a URI field (up to 256 bytes) that points to the metadata. The metadata itself — name, description, image, attributes/traits — is stored off-chain. The URI is the link between the on-chain NFT object and its off-chain data.
This is the same approach used by Ethereum ERC-721 and Solana Metaplex. The on-chain token is lightweight; the rich content lives wherever the URI points.
Storage Options
| Storage | Persistence | Cost | Speed | Decentralized |
|---|---|---|---|---|
| IPFS + Pinning | Permanent (if pinned) | Free-$20/mo | Moderate | Yes |
| Arweave | Permanent (paid once) | ~$0.001/KB | Moderate | Yes |
| On-chain (Memo) | Permanent | ~0.000012 XRP | Instant | Yes |
| Centralized (HTTPS) | Depends on host | Varies | Fast | No |
IPFS without pinning means the data can disappear when no node hosts it. Always use a pinning service like Pinata or nft.storage. Arweave is pay-once, permanent. On-chain via memo is limited in size but truly permanent. Centralized servers are fast but the host can go offline at any time.
Metadata JSON Format
The standard XLS-20 metadata format follows the same conventions as ERC-721. The URI on the NFT points to a JSON file like this:
{
"name": "My NFT #1",
"description": "Description of the NFT",
"image": "ipfs://QmHash...",
"attributes": [
{ "trait_type": "Background", "value": "Blue" },
{ "trait_type": "Rarity", "value": "Rare" }
]
}The image field typically points to another IPFS hash containing the actual media file. The metadata URI on the NFT points to this JSON file, not the image directly.
How XRPL.to Resolves NFT Metadata
Automatically resolves NFT URIs from IPFS, Arweave, and HTTPS sources
Fetches and caches metadata JSON for fast loading across the platform
Caches images server-side so collection pages load instantly
Extracts trait data from attributes for rarity ranking calculations
When you browse NFT collections on xrpl.to/nfts, all metadata is pre-resolved and cached. This is why collection pages load instantly even though the underlying data is on IPFS.
Common Issues
- Missing images: IPFS content not pinned, gateway timeout. Solution: use a reliable pinning service.
- Broken URIs: Centralized server went offline. This is why decentralized storage is recommended.
- Wrong format: Metadata JSON doesn't follow XLS-20 convention. Marketplaces may not display traits correctly.
- Large files: IPFS retrieval is slow for large images. Optimize images before uploading (WebP format, under 2MB).
Best Practices for Creators
- Use IPFS with a pinning service (Pinata or nft.storage) for both metadata and images
- Keep images under 2MB for fast loading across all devices
- Follow the standard JSON format:
name,description,image,attributes - Test that your URI resolves correctly before minting — once minted, the URI cannot be changed
- See the full minting guide for step-by-step instructions
Get Started
Browse existing NFT collections or mint your own on the XRP Ledger.