Quickstart
Get the Bitcoin Indexer running with pre-indexed archives in 30 minutes.
This quickstart uses Hiro's pre-indexed archives to get you running in minutes instead of days. You'll set up a Bitcoin node, restore from archives, and start serving metaprotocol APIs.
Prerequisites
- Ubuntu 20.04+ or macOS
- 32GB RAM minimum
- 2TB fast storage (NVMe recommended)
- Basic command line knowledge
Install dependencies
Install required system packages:
$sudo apt update$sudo apt install -y build-essential git curl postgresql-17
Quick Bitcoin node setup
Download and configure Bitcoin Core with indexer settings:
$mkdir -p ~/bitcoin-indexer/bitcoin && cd ~/bitcoin-indexer/bitcoin$curl -O https://bitcoincore.org/bin/bitcoin-core-25.1/bitcoin-25.1-x86_64-linux-gnu.tar.gz$tar -xzf bitcoin-25.1-x86_64-linux-gnu.tar.gz$sudo ln -s ~/bitcoin-indexer/bitcoin/bitcoin-25.1/bin/bitcoind /usr/local/bin/bitcoind
Create minimal config:
$cat > bitcoin.conf << EOFdatadir=$HOME/bitcoin-indexer/bitcoin/chainstatetxindex=1rpcuser=userrpcpassword=passwordzmqpubrawblock=tcp://0.0.0.0:18543EOF
Start syncing (continues in background):
$bitcoind -conf=$HOME/bitcoin-indexer/bitcoin/bitcoin.conf -daemon
Set up PostgreSQL
Create databases for metaprotocol data:
$sudo -u postgres createdb ordinals$sudo -u postgres createdb brc20$sudo -u postgres psql -c "ALTER USER postgres WITH PASSWORD 'postgres';"
Download pre-indexed archives
Skip weeks of indexing by using Hiro archives:
$mkdir -p ~/bitcoin-indexer/archives && cd ~/bitcoin-indexer/archives$# Download archives (this takes 2-4 hours)$curl -O -C - https://archive.hiro.so/mainnet/bitcoin-indexer-adhoc/mainnet-bitcoin-indexer-ordinals-pg-latest.tar$curl -O -C - https://archive.hiro.so/mainnet/bitcoin-indexer-adhoc/mainnet-bitcoin-indexer-rocksdb-latest.tar.gz
Restore from archives
Extract and import the archived data:
$# Extract archives$tar -xzf mainnet-bitcoin-indexer-rocksdb-latest.tar.gz$tar -xf mainnet-bitcoin-indexer-ordinals-pg-latest.tar$# Move RocksDB data$mv rocksdb ~/bitcoin-indexer/rocksdb-chainstate$# Restore PostgreSQL$sudo chown postgres:postgres ordinals.dump$sudo -u postgres pg_restore --jobs=4 -d ordinals ordinals.dump
Build and configure indexer
Clone and build the Bitcoin Indexer:
$cd ~/bitcoin-indexer$git clone https://github.com/hirosystems/bitcoin-indexer.git$cd bitcoin-indexer$cargo build --release
Create configuration:
$cat > bitcoin-indexer-config.toml << 'EOF'[storage]working_dir = "/home/$USER/bitcoin-indexer/rocksdb-chainstate"[ordinals.db]database = "ordinals"host = "localhost"port = 5432username = "postgres"password = "postgres"[bitcoind]network = "mainnet"rpc_url = "http://127.0.0.1:8332"rpc_username = "user"rpc_password = "password"zmq_url = "tcp://0.0.0.0:18543"[resources]cpu_core_available = 4memory_available = 8EOF
Start indexing
Wait for Bitcoin node to sync (check progress):
$bitcoin-cli -conf=$HOME/bitcoin-indexer/bitcoin/bitcoin.conf getblockchaininfo | jq .verificationprogress0.9523 # When this reaches ~0.9999, you're ready
Start the Ordinals indexer:
$./target/release/bitcoin-indexer ordinals service start --config-path=bitcoin-indexer-config.toml[32m✓[0m Loaded archive state from block 819,542[32m✓[0m Catching up to chain tip...
Verify it's working
Test the API endpoints:
$# Check indexer status$curl http://localhost:3000/ordinals/v1/status$# Get first inscription$curl http://localhost:3000/ordinals/v1/inscriptions/0{"id": "6fb976ab49dcec017f1e201e84395983204ae1a7c2abf7ced0a85d692e442799i0","number": 0,"address": "bc1pxaneaf3w4d27hl2y93fuft2xk6m4u3wc4rafevc6slgd7f5tq2dqynekta"}
What's next?
Your indexer is now running and serving API requests! Here's what you can do:
Explore the API
Learn about all available endpoints
Advanced configuration
Optimize performance and add features
Set up monitoring
Track indexer health and performance