Contents
Let's walk through a familiar scenario: You update an NFT's artwork for a reveal, migrate your IPFS gateway, or fix metadata. But nothing happens downstream. Marketplaces show old images. Wallets display stale data. Block explorers are stuck in the past.
Why? Because every indexer had its own refresh strategy: hourly, daily, maybe never. There was no standard way to say "this changed, please look again."
The Problem: Metadata Staleness Across the Ecosystem
Here's the fundamental challenge: when you change a token's metadata URI on-chain, the blockchain records it, but indexers have no idea you updated anything. So they resorted to polling - constantly reading every contract.
This creates serious problems:
- Expensive: Unnecessary load on Stacks nodes
- Inconsistent: Different apps refresh at different intervals
- Incomplete: You miss updates between polling intervals
Real production issues: NFT reveals where marketplaces show old images for hours. Fungible tokens with wrong decimals in wallets. Stale descriptions everywhere.
The ecosystem needed a standard notification mechanism.
SIP-019: Standardizing Metadata Update Notifications
The answer was already built into Clarity: the print function. When you call print in a smart contract, it emits a contract_event broadcast to the network.
SIP-019 standardized the message format:
{ notification: "token-metadata-update", payload: { token-class: "nft", contract-id: <token contract id>, token-ids: (list u100 u101) } }
When this gets printed, every indexer knows which tokens need refreshing. The notification is permanent, trust-less, and practically free. SIP-019 also includes optional update modes (`standard`, `frozen`, `dynamic`) so contracts can communicate their update patterns.
The Token Metadata API Architecture
The Token Metadata API is Hiro's SIP-019-compliant indexer, originally part of the Stacks Blockchain API but broken out for independent scaling.
You can think of the basic flow as:
- Read the events
- Enqueue the work
- Then process the job
The key decision: decouple event ingestion from processing.
But what if the URI points to a rate-limited host?
Smart Rate Limiting
When we get a 429 Too Many Requests from a host, we track it in a rate_limited_hosts table with the retry-after time. Before any metadata fetch, we check if the hostname is rate-limited.
If so, the job throws a retry-able error and waits. When the retry window passes, the job queue picks it up again.
This means we respect rate limits automatically - no hammering servers, no manual intervention.
Configurable IPFS Gateway Support
Many NFT contracts return IPFS URIs (ipfs://QmX...) or hard-coded gateway URLs (https://ipfs.io/ipfs/QmX...). IPFS gateways vary in performance, so we made gateway selection configurable:
PUBLIC_GATEWAY_IPFS=https://cloudflare-ipfs.com
PUBLIC_GATEWAY_IPFS_REPLACED=ipfs.io,dweb.link,gateway.pinata.cloud
The system converts `ipfs://` URIs and replaces hard-coded gateways with your configured one. This lets you use your own infrastructure, optimize for your region, avoid gateway downtime, and control costs. All without code changes.
For Hiro's hosted Token Metadata API, we upgraded to Pinata, a hosted IPFS gateway. This makes metadata fetches significantly faster for all users of our service.
Using the Reference Contract
SIP-019 includes a deployed reference contract. You can call it to trigger a refresh:
(contract-call? 'SP1H6HY2ZPSFPZF6HBNADAYKQ2FJN75GHVV95YZQ.token-metadata-update-notify nft-metadata-update-notify 'SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.my-nft-contract (list u1 u2 u3 u4 u5))
The reference contract is permission-less, so anyone can trigger refreshes. Or deploy your own as long as it prints the SIP-019 payload. You can add authorization, integrate notifications directly into your token contract, or build custom notification logic.
Where We Go From Here
The Token Metadata API is open source. Run your own instance, file issues, contribute improvements, or deploy your own SIP-019-compliant notification contracts.
Next steps
- Check out the API documentation
- Join the Hiro Discord for questions
- Read the full SIP-019 specification
Follow the spec, emit notifications when metadata changes, and indexers across the ecosystem will pick them up automatically.
