🎵 ₿ 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.

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": []
    }
}

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.