/     /   ▶ Bitcoin Indexer
  / --- /      Index Bitcoin meta-protocols like Ordinals, BRC-20, and Runes.
 /     /

• Features
• Quick Start
  • Installing
  • Running the Indexer
• Configuration
• System Requirements
  • Postgres
• Contribute
• Community

---

Features

Bitcoin Indexer is a tool that continuously reads Bitcoin blocks from a connected Bitcoin node in order to extract and index meta-protocol data contained within it. Once indexed, data is stored in a Postgres DB and can be made available to clients or users via REST APIs.

Quick Start

Installing

$ git clone https://github.com/hirosystems/bitcoin-indexer.git
$ cd bitcoin-indexer
$ cargo bitcoin-indexer-install

Docker images are also available at https://hub.docker.com/r/hirosystems/bitcoin-indexer

Running the Indexer

The following command will start indexing Ordinals activity and will continue to stream new blocks once it reaches the Bitcoin chain tip.

$ bitcoin-indexer ordinals service start --config-path <path>

A similar command exists for indexing Runes

$ bitcoin-indexer runes service start --config-path <path>

A fully synced Bitcoin node is required for indexing to start.

Running an API

Once the index starts advancing, you can deploy the Ordinals API or Runes API to read the same data via REST endpoints.

Configuration

Indexer configurations are set via a TOML file. To generate a new config file, run this command:

$ bitcoin-indexer config new

Postgres database configurations are set like this. Each index will have its own database.

[ordinals.db]
database = "ordinals"
host = "localhost"
port = 5432
username = "postgres"
password = "postgres"

Ordinals meta-protocols like BRC-20 are also configured in this file

[ordinals.meta_protocols.brc20]
enabled = true
lru_cache_size = 10000

[ordinals.meta_protocols.brc20.db]
database = "brc20"
host = "localhost"
port = 5432
username = "postgres"
password = "postgres"

System Requirements

The Bitcoin Indexer is resource-intensive, demanding significant CPU, memory and disk capabilities. As we continue to refine and optimize, keep in mind the following system requirements and recommendations to ensure optimal performance:

• CPU: The ordhook tool efficiently utilizes multiple cores when detected at runtime, parallelizing tasks to boost performance.

• Memory: A minimum of 16GB RAM is recommended.

• Disk: To enhance I/O performance, SSD or NVMe storage is suggested.

• OS Requirements: Ensure your system allows for a minimum of 4096 open file descriptors. Configuration may vary based on your operating system. On certain systems, this can be adjusted using the ulimit command or the launchctl limit command.

Postgres

To store indexed data, a Postgres database is required per index (ordinals, runes, etc.). It is recommended to use Postgres 17+ for optimal performance.

Contribute

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.

Code of Conduct

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

Contributing Guide

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

Community

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 subcribing to the mailing list.

• Follow Hiro on Twitter.