A microservice that indexes metadata for all Fungible, Non-Fungible, and Semi-Fungible Tokens on the Stacks blockchain and exposes it via JSON REST API endpoints. It connects directly to a Stacks node via the Stacks Node Publisher (SNP) Redis event stream, processing every new block to discover token contracts, track mints and burns, and fetch off-chain metadata.

• Features
• API reference
• Client library
• Quick start
  • System requirements
  • Running the service
    • Run modes
  • Stopping the service
• Configuration
  • Core settings
  • Stacks node & SNP
  • PostgreSQL
  • Job queue
  • Metadata fetching
  • IPFS & Arweave gateways
  • Image cache
• Bugs and feature requests
• Contribute
• Community

• Complete SIP-016 metadata ingestion for
  • SIP-009 Non-Fungible Tokens
  • SIP-010 Fungible Tokens
  • SIP-013 Semi-Fungible Tokens
• Real-time block ingestion via the Stacks Node Publisher (SNP) Redis event stream
• Automatic metadata refreshes via SIP-019 notifications
• Metadata localization support
• Metadata fetching via http:, https:, data: URIs, plus customizable gateways for IPFS and Arweave
• Live tracking of FT/SFT supply through mint and burn event deltas
• Easy to use REST JSON endpoints with ETag caching
• Prometheus metrics for job queue status, contract and token counts, API performance, and more
• Optional image cache/CDN via Google Cloud Storage
• Run modes (default, readonly, writeonly) for auto-scaling deployments
• Admin RPC server for operational tasks (retry failed jobs, refresh metadata, import contracts)

See the Token Metadata API Reference for full endpoint documentation.

A fully typed TypeScript client is available for consuming the API. Install it with:

npm install @stacks/token-metadata-api-client

See the client README or the npm package for usage examples.

Clone the repo:

git clone https://github.com/hirosystems/token-metadata-api.git
cd token-metadata-api

Create an .env file and specify the appropriate values. At a minimum you need:

# Stacks node
STACKS_NODE_RPC_HOST=127.0.0.1
STACKS_NODE_RPC_PORT=20443

# SNP event stream (Redis)
SNP_REDIS_URL=redis://127.0.0.1:6379
SNP_REDIS_STREAM_KEY_PREFIX=stacks-node

# PostgreSQL
PGHOST=127.0.0.1
PGPORT=5432
PGUSER=postgres
PGPASSWORD=postgres
PGDATABASE=token_metadata

See the Configuration section below for every available option.

Build and start:

npm install
npm run build
npm run start

The API server starts on port 3000 by default, the Admin RPC server on port 3001, and Prometheus metrics on port 9153.

The RUN_MODE environment variable controls which components the service starts. This allows you to scale the read and write paths independently:

In an auto-scaled cluster you would typically run one writeonly instance that ingests data and multiple readonly instances behind a load balancer to serve API traffic.

Always prefer sending SIGINT (Ctrl+C) instead of SIGKILL. This allows the service to finish any in-progress jobs, flush writes, and cleanly disconnect from PostgreSQL and Redis.

All configuration is done via environment variables. Defaults are shown in parentheses.

If you encounter a bug or have a feature request, we encourage you to follow the steps below:

1. Search for existing issues: Before submitting a new issue, please search existing and closed issues to check if a similar problem or feature request has already been reported.
2. Open a new issue: If it hasn't been addressed, please open a new issue. Choose the appropriate issue template and provide as much detail as possible, including steps to reproduce the bug or a clear description of the requested feature.
3. Evaluation SLA: Our team reads and evaluates all the issues and pull requests. We are available Monday to Friday and we make a best effort to respond within 7 business days.

Please do not use the issue tracker for personal support requests or to ask for the status of a transaction. You'll find help at the #support Discord channel.

Development of this product happens in the open on GitHub, and we are grateful to the community for contributing bugfixes and improvements. Read below to learn how you can take part in improving the product.

Please read our Code of conduct since we expect project participants to adhere to it.

Read our contributing guide to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes.

Join our community and stay connected with the latest updates and discussions:

• Join our Discord community chat to engage with other users, ask questions, and participate in discussions.

• Visit hiro.so for updates and subscribing to the mailing list.

• Follow Hiro on Twitter.