🎵 ₿ from hash to harmony: an orchestrated Bitcoin indexing suite ₿ 🎵

Maestro Symphony

Overview

Maestro Symphony is a fast, mempool-aware, and extensible Bitcoin indexer and API server. It provides a framework for indexing UTXOs, metaprotocols, and any other onchain activity.

Core Features

Endpoints: OpenAPI

Mempool Awareness: Query any endpoint with ?mempool=true to include pending transactions.

Rollback Handling: Always maintains an index of the longest chain.

Prerequisites

• Bitcoin Core (22+) with RPC and P2P access
• Rust (stable)

Optional Tools

• Docker
• mise

Deployment Requirements

NOTE: Deployment requirements are subject to change with new indexers and API endpoints.

Configuration

Below is a table describing the main configuration options for maestro-symphony. See the example configuration for context.

See examples to quickly get started.

Deployment

Quick Start with Snapshots

See instructions here.

Running Locally

Optionally, use mise to easily set up your environment:

mise install

Build

make build

Sync & Serve

make run [CONFIG=examples/testnet.toml]

Sync Only

make sync [CONFIG=examples/testnet.toml]

Serve Only

make serve [CONFIG=examples/testnet.toml]

Generate OpenAPI

make openapi

Running with Docker

Start

make compose-up

Stop

make compose-down

Endpoint Examples

Rune UTXOs by Address

curl -X GET "http://localhost:8080/addresses/tb1pn9dzakm6egrv90c9gsgs63axvmn6ydwemrpuwljnmz9qdk38ueqsqae936/runes/utxos" | jq .

{
    "data": [
        {
            "tx_hash": "63937d48e35d15a7c5530469210c202104cc94a945cc848554f336b3f4f24121",
            "output_index": 1,
            "height": 30562,
            "satoshis": "10000",
            "runes": [
                {
                    "id": "30562:50",
                    "amount": "100000000"
                }
            ]
        }
    ],
    "indexer_info": {
        "chain_tip": {
            "block_hash": "000000002ec229e75c52e8e9adf95149fdde167b59c3271abb6bf541ef85249b",
            "block_height": 87777
        },
        "mempool_timestamp": null,
        "estimated_blocks": []
    }
}

Rune Info (Batch)

curl -X POST "http://localhost:8080/runes/info" \
  -H "Content-Type: application/json" \
  -d '["30562:50", "ABCDEF"]' | jq .

{
    "data": {
        "30562:50": {
            "id": "30562:50",
            "name": "BESTINSLOTXYZ",
            "spaced_name": "BESTINSLOT•XYZ",
            "symbol": "ʃ",
            "divisibility": 8,
            "etching_tx": "63937d48e35d15a7c5530469210c202104cc94a945cc848554f336b3f4f24121",
            "etching_height": 30562,
            "terms": {
                "amount": "100000000",
                "cap": "3402823669209384634633746074316",
                "start_height": null,
                "end_height": null
            },
            "premine": "100000000"
        },
        "ABCDEF": null
    },
    "indexer_info": {
        "chain_tip": {
            "block_hash": "00000000000000108a4cd9755381003a01bea7998ca2d770fe09b576753ac7ef",
            "block_height": 31633
        },
        "mempool_timestamp": null,
        "estimated_blocks": []
    }
}

Mempool-Aware Rune UTXOs by Address

curl -X GET "http://localhost:8080/addresses/tb1pn9dzakm6egrv90c9gsgs63axvmn6ydwemrpuwljnmz9qdk38ueqsqae936/runes/utxos?mempool=true" | jq .

{
    "data": [
        {
            "tx_hash": "63937d48e35d15a7c5530469210c202104cc94a945cc848554f336b3f4f24121",
            "output_index": 1,
            "height": 30562,
            "satoshis": "10000",
            "runes": [
                {
                    "id": "30562:50",
                    "amount": "100000000"
                }
            ]
        }
    ],
    "indexer_info": {
        "chain_tip": {
            "block_hash": "000000002ec229e75c52e8e9adf95149fdde167b59c3271abb6bf541ef85249b",
            "block_height": 87777
        },
        "mempool_timestamp": "2025-06-23 22:04:31",
        "estimated_blocks": [
            {
                "block_height": 87778
            }
        ]
    }
}

Rune Balance Changes in a Transaction

curl -X GET "http://localhost:8080/addresses/<ADDRESS>/runes/tx/<TXID>" | jq .

{
    "data": [
        {
            "rune_id": "30562:50",
            "amount": "100000000",
            "output": 1,
            "block_height": 30562
        }
    ],
    "indexer_info": {
        "chain_tip": {
            "block_hash": "0000000000000035ec326a15b2f81822962f786028f33205b74b47a9b7cf3caf",
            "block_height": 38980
        },
        "mempool_timestamp": null,
        "estimated_blocks": []
    }
}

Security

Maestro Symphony has undergone professional security audits to ensure the safety and reliability of the codebase.

Audit Reports

• Thesis Defense Security Audit (September 2025) - Independent security assessment of the core indexing and API components.

For reporting security vulnerabilities, please see our Security Policy.

Contributing

Pull requests and issues are welcome! See the Kanban board for project status and tasks.

Feature Checklist

• Base Indexer
  • Addresses
    • Runes by address
    • Runes by address and rune ID
    • Runes by address and transaction ID
    • Rune UTXOs by address
    • Rune UTXOs by address and rune ID
    • UTXOs by address
    • Satoshi balance by address
    • BRC20 by address
    • Inscriptions by address
    • Transactions by address
  • Runes
    • Rune info by rune ID
    • Rune balance by rune ID and UTXO
    • List runes
    • Holders by rune
    • UTXOs by rune
• Wallet activity
  • Addresses
    • Satoshi activity by address
    • Metaprotocol activity by address
    • Historical satoshi balance by address
    • Inscription activity by address
    • Address statistics
• Alkanes
• Webhook Notifications

License

This project is licensed under the Apache 2.0 License.