maestro-bitcoin – OpenClaw Skill

---

name: maestro-bitcoin description: Comprehensive Bitcoin blockchain interaction via Maestro APIs. Supports 7 API services with 119 endpoints including blockchain indexing, Esplora compatibility, RPC access, event management, market prices, mempool monitoring, and wallet operations. Handles BTC transactions, UTXOs, addresses, blocks, metaprotocols (BRC20, Runes, Inscriptions/Ordinals), webhooks, and real-time data.

Maestro Bitcoin Skill

A comprehensive skill for interacting with the Bitcoin blockchain through the Maestro API platform, providing access to 7 distinct API services with 119 total endpoints.

Overview

This skill provides complete access to Maestro's Bitcoin API suite:

1. Blockchain Indexer API (37 endpoints) - Real-time UTXO data with metaprotocol support
2. Esplora API (29 endpoints) - Blockstream-compatible REST API
3. Node RPC API (24 endpoints) - JSON-RPC protocol access
4. Event Manager API (9 endpoints) - Real-time webhooks and monitoring
5. Market Price API (8 endpoints) - OHLC data and price analytics
6. Mempool Monitoring API (9 endpoints) - Mempool-aware operations
7. Wallet API (6 endpoints) - Address-level activity tracking

Key Capabilities

• Query addresses, transactions, blocks, and UTXOs
• Broadcast transactions with multiple methods
• Track BRC20 tokens, Runes, and Inscriptions (Ordinals)
• Monitor mempool and estimate fees
• Set up webhooks for blockchain events
• Access market price data and DEX trading info
• Mempool-aware balance and UTXO queries
• Historical balance tracking
• Collection and metaprotocol statistics

Configuration

API Key Setup

This skill requires a Maestro API Key. Set the MAESTRO_API_KEY environment variable:

export MAESTRO_API_KEY="your_api_key_here"

Add to ~/.bashrc or ~/.zshrc for persistence:

echo 'export MAESTRO_API_KEY="your_api_key_here"' >> ~/.bashrc
source ~/.bashrc

Getting an API Key

1. Sign up at Maestro Dashboard
2. Create a new project
3. Select Bitcoin as the blockchain
4. Select your network (Mainnet or Testnet4)
5. Copy the API key from your project dashboard

Network Configuration

The skill supports both mainnet and testnet. Set MAESTRO_NETWORK to switch:

# Use mainnet (default)
export MAESTRO_NETWORK="mainnet"

# Use testnet4
export MAESTRO_NETWORK="testnet"

Usage

Primary Interface: Shell Script

The main interface is through scripts/call_maestro.sh, which provides access to all 7 API services.

Quick Examples

# Get latest block height
./scripts/call_maestro.sh get-latest-height

# Get address balance
./scripts/call_maestro.sh get-balance bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh

# Get address UTXOs
./scripts/call_maestro.sh get-utxos bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh

# Get transaction details
./scripts/call_maestro.sh get-tx <tx_hash>

# Broadcast transaction
./scripts/call_maestro.sh broadcast-tx <hex_tx>

# Get mempool info
./scripts/call_maestro.sh get-mempool-info

# Estimate fee for 6 blocks
./scripts/call_maestro.sh estimate-fee 6

# Get BRC20 tokens
./scripts/call_maestro.sh list-brc20

# Get runes for address
./scripts/call_maestro.sh get-address-runes bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh

Available Commands by Service

Blockchain Indexer Commands

Address Operations:

• get-balance <address> - Get address satoshi balance
• get-utxos <address> - Get address UTXOs
• get-address-txs <address> - Get address transactions
• get-address-activity <address> - Get address satoshi activity
• get-address-stats <address> - Get address statistics
• get-balance-history <address> - Get historical balance
• get-address-runes <address> - Get runes for address
• get-address-rune-activity <address> - Get rune activity
• get-address-rune-utxos <address> - Get rune UTXOs
• get-address-brc20 <address> - Get BRC20 tokens for address
• get-address-inscriptions <address> - Get inscriptions for address
• get-address-inscription-activity <address> - Get inscription activity

Block Operations:

• get-block <height_or_hash> - Get block information
• get-block-txs <height_or_hash> - Get transactions in block
• get-block-inscriptions <height_or_hash> - Get inscription activity in block

Transaction Operations:

• get-tx <tx_hash> - Get transaction information
• get-tx-metaprotocols <tx_hash> - Get transaction with metaprotocols
• get-tx-output <tx_hash> <index> - Get transaction output info
• get-tx-inscriptions <tx_hash> - Get inscription activity in transaction

BRC20 Operations:

• list-brc20 - List all BRC20 tokens
• get-brc20 <ticker> - Get BRC20 token info
• get-brc20-holders <ticker> - Get BRC20 token holders

Runes Operations:

• list-runes - List all runes
• get-rune <rune_id> - Get rune information
• get-rune-activity <rune_id> - Get rune activity
• get-rune-holders <rune_id> - Get rune holders
• get-rune-utxos <rune_id> - Get rune UTXOs

Inscriptions Operations:

• get-inscription <inscription_id> - Get inscription info
• get-inscription-content <inscription_id> - Get inscription content
• get-inscription-activity <inscription_id> - Get inscription activity
• get-collection <collection_symbol> - Get collection metadata
• get-collection-stats <collection_symbol> - Get collection statistics
• get-collection-inscriptions <collection_symbol> - Get collection inscriptions

Esplora API Commands

• esplora-address-info <address> - Get address information
• esplora-address-txs <address> - Get address transactions
• esplora-address-utxos <address> - Get address UTXOs
• esplora-block <hash> - Get block information
• esplora-block-txs <hash> - Get block transactions
• esplora-tx <txid> - Get transaction information
• esplora-tx-hex <txid> - Get transaction hex
• esplora-broadcast <tx_hex> - Broadcast transaction
• esplora-mempool - Get mempool information
• esplora-tip-height - Get blockchain tip height

Node RPC Commands

• rpc-get-latest-block - Get latest block
• rpc-get-latest-height - Get latest block height
• rpc-get-block <height_or_hash> - Get block info
• rpc-get-block-miner <height_or_hash> - Get block miner info
• rpc-get-info - Get blockchain info
• rpc-get-mempool-info - Get mempool info
• rpc-get-mempool-txs - Get mempool transactions
• rpc-get-mempool-tx <tx_hash> - Get mempool transaction info
• rpc-get-tx <tx_hash> - Get transaction info
• rpc-decode-tx <hex> - Decode transaction
• rpc-broadcast-tx <hex> - Broadcast transaction
• rpc-estimate-fee <blocks> - Estimate fee

Event Manager Commands

• event-list-triggers - List all event triggers
• event-create-trigger <json> - Create event trigger
• event-get-trigger <id> - Get trigger details
• event-delete-trigger <id> - Delete trigger
• event-list-logs - List event logs
• event-get-log <id> - Get event log details

Market Price Commands

• market-btc-price <timestamp> - Get BTC price at timestamp
• market-rune-price <rune_id> <timestamp> - Get rune price
• market-list-dexs - List supported DEXs
• market-list-runes - Get rune registry
• market-ohlc <dex> <symbol> - Get OHLC data for rune
• market-trades <dex> <symbol> - Get trades for rune

Mempool Monitoring Commands

• mempool-get-balance <address> - Get balance (mempool-aware)
• mempool-get-utxos <address> - Get UTXOs (mempool-aware)
• mempool-get-runes <address> - Get runes (mempool-aware)
• mempool-get-rune-utxos <address> - Get rune UTXOs (mempool-aware)
• mempool-get-fee-rates - Get mempool block fee rates
• mempool-broadcast <hex> - Broadcast with propagation tracking
• mempool-get-tx-meta <tx_hash> - Get tx metaprotocols (mempool-aware)

Wallet API Commands

• wallet-get-activity <address> - Get wallet activity (mempool-aware)
• wallet-get-meta-activity <address> - Get metaprotocol activity
• wallet-get-balance-history <address> - Get historical balance
• wallet-get-inscription-activity <address> - Get inscription activity
• wallet-get-rune-activity <address> - Get rune activity
• wallet-get-stats <address> - Get address statistics (mempool-aware)

References

• API Reference: Complete endpoint documentation
• Examples: Common use case examples
• Official Docs: Maestro documentation

Features

Metaprotocol Support

Full support for Bitcoin metaprotocols:

• BRC20 Tokens: Query tokens, holders, and balances
• Runes: Track rune balances, activity, and UTXOs
• Inscriptions (Ordinals): Query inscriptions, collections, and content

Mempool Awareness

Several endpoints offer mempool-aware queries that include pending transactions:

• Balance queries
• UTXO queries
• Rune and inscription tracking
• Transaction metaprotocols

Event-Driven Architecture

Set up webhooks to monitor:

• Address activity
• Block confirmations
• Transaction events
• Metaprotocol operations

Rate Limiting

Maestro implements two-tier rate limiting:

• Daily credit limits based on subscription
• Per-second request caps

Check rate limit headers in responses:

• X-RateLimit-Limit-Second
• X-RateLimit-Remaining-Second
• X-Maestro-Credits-Limit
• X-Maestro-Credits-Remaining

Notes

• All endpoints require valid API key authentication
• The /v0 version prefix must be included in all API calls
• Cursor-based pagination is available for listing endpoints
• Block height filtering available via from and to parameters
• Support for both mainnet and testnet4 networks
• Comprehensive error handling with standard HTTP status codes

Maestro Bitcoin Skill

A comprehensive skill for interacting with the Bitcoin blockchain through the Maestro API platform. Provides complete access to 7 distinct API services with 119 total endpoints covering all aspects of Bitcoin blockchain interaction.

Overview

This skill enables agents to interact with the Bitcoin blockchain via Maestro's comprehensive API suite, including:

• Blockchain Indexer API (37 endpoints) - Real-time UTXO data with metaprotocol support
• Esplora API (29 endpoints) - Blockstream-compatible REST API
• Node RPC API (24 endpoints) - JSON-RPC protocol access
• Event Manager API (9 endpoints) - Real-time webhooks and monitoring
• Market Price API (8 endpoints) - OHLC data and price analytics
• Mempool Monitoring API (9 endpoints) - Mempool-aware operations
• Wallet API (6 endpoints) - Address-level activity tracking

Key Features

✅ Complete API Coverage - All 119 endpoints across 7 services ✅ Metaprotocol Support - BRC20 tokens, Runes, Inscriptions (Ordinals) ✅ Mempool Awareness - Real-time pending transaction tracking ✅ Event-Driven - Webhook support for blockchain events ✅ Market Data - BTC and Rune price feeds, DEX trading data ✅ Multi-Network - Support for both mainnet and testnet4 ✅ Comprehensive Docs - Detailed API reference and examples

Quick Start

1. Get an API Key

Sign up at Maestro Dashboard and create a Bitcoin project to get your API key.

2. Configure Environment

# Set your API key
export MAESTRO_API_KEY="your_api_key_here"

# Optional: Set network (defaults to mainnet)
export MAESTRO_NETWORK="mainnet"  # or "testnet"

3. Run Commands

# Get latest block height
./scripts/call_maestro.sh get-latest-height

# Get address balance
./scripts/call_maestro.sh get-balance bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh

# List all BRC20 tokens
./scripts/call_maestro.sh list-brc20

# Get mempool fee rates
./scripts/call_maestro.sh mempool-get-fee-rates

# View all available commands
./scripts/call_maestro.sh help

What You Can Do

Address Operations

• Query balances (standard and mempool-aware)
• Get UTXOs and transaction history
• Track address activity and statistics
• Historical balance queries

Transaction Operations

• Get transaction details with metaprotocol data
• Broadcast transactions (3 different methods)
• Decode transactions and PSBTs
• Track transaction lifecycle from mempool to confirmation

Block Operations

• Query blocks by height or hash
• Get block transactions and metadata
• Track miner information and block volume
• Query block ranges

Metaprotocol Support

• BRC20 Tokens: List, query, and track BRC20 tokens and holders
• Runes: Query runes, holders, activity, and UTXOs
• Inscriptions (Ordinals): Get inscriptions, collections, and content

Mempool Monitoring

• Real-time fee rate estimation
• Mempool-aware balance and UTXO queries
• Track pending transactions
• Monitor mempool congestion

Market Data

• BTC price feeds (current and historical)
• Rune token prices
• OHLC data for DEX trading
• Trading pair information

Event Management

• Set up webhooks for blockchain events
• Monitor address activity
• Track confirmations
• Custom trigger conditions

Documentation

• SKILL.md - Complete skill documentation and usage guide
• API Reference - Detailed documentation for all 119 endpoints
• Examples - Real-world usage examples and patterns
• Official Maestro Docs - Maestro Bitcoin documentation

Available Commands

The skill provides 119+ commands organized across 7 API services:

Blockchain Indexer (37 endpoints)

# Address operations
get-balance, get-utxos, get-address-txs, get-address-activity, get-address-stats
get-balance-history, get-address-runes, get-address-rune-activity, get-address-rune-utxos
get-address-brc20, get-address-inscriptions, get-address-inscription-activity

# Block operations
get-block, get-block-txs, get-block-inscriptions

# Transaction operations
get-tx, get-tx-metaprotocols, get-tx-output, get-tx-inscriptions

# BRC20 operations
list-brc20, get-brc20, get-brc20-holders

# Runes operations
list-runes, get-rune, get-rune-activity, get-rune-holders, get-rune-utxos

# Inscriptions operations
get-inscription, get-inscription-content, get-inscription-activity
get-collection, get-collection-stats, get-collection-inscriptions

Esplora API (29 endpoints)

esplora-address-info, esplora-address-txs, esplora-address-utxos
esplora-block, esplora-block-txs, esplora-tip-height
esplora-tx, esplora-tx-hex, esplora-broadcast, esplora-mempool
# ... and 19 more

Node RPC API (24 endpoints)

rpc-get-latest-block, rpc-get-latest-height, rpc-get-info
rpc-get-mempool-info, rpc-get-tx, rpc-decode-tx
rpc-broadcast-tx, rpc-estimate-fee
# ... and 16 more

Event Manager API (9 endpoints)

event-list-triggers, event-create-trigger, event-get-trigger
event-delete-trigger, event-list-logs, event-get-log

Market Price API (8 endpoints)

market-btc-price, market-rune-price, market-list-dexs
market-list-runes, market-ohlc, market-trades

Mempool Monitoring API (9 endpoints)

mempool-get-balance, mempool-get-utxos, mempool-get-runes
mempool-get-fee-rates, mempool-broadcast, mempool-get-tx-meta

Wallet API (6 endpoints)

wallet-get-activity, wallet-get-meta-activity, wallet-get-balance-history
wallet-get-inscription-activity, wallet-get-rune-activity, wallet-get-stats

Run ./scripts/call_maestro.sh help for the complete list with descriptions.

Examples

Basic Queries

# Get latest block height
./scripts/call_maestro.sh get-latest-height

# Get address balance
./scripts/call_maestro.sh get-balance bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh

# Get transaction details
./scripts/call_maestro.sh get-tx 4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b

Metaprotocol Queries

# List all BRC20 tokens
./scripts/call_maestro.sh list-brc20

# Get BRC20 token info
./scripts/call_maestro.sh get-brc20 ordi

# Get runes for an address
./scripts/call_maestro.sh get-address-runes bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh

# Get inscription content
./scripts/call_maestro.sh get-inscription-content 1234567i0

Mempool Operations

# Get mempool-aware balance (includes pending)
./scripts/call_maestro.sh mempool-get-balance bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh

# Get current fee rates
./scripts/call_maestro.sh mempool-get-fee-rates

# Estimate fee for 6 block confirmation
./scripts/call_maestro.sh estimate-fee 6

Market Data

# Get current BTC price
./scripts/call_maestro.sh market-btc-price $(date +%s)

# Get rune price
./scripts/call_maestro.sh market-rune-price 840000:1 $(date +%s)

# List supported DEXs
./scripts/call_maestro.sh market-list-dexs

Event Management

# Create a webhook for address activity
./scripts/call_maestro.sh event-create-trigger '{
  "name": "Address Activity Monitor",
  "trigger_type": "address_activity",
  "conditions": {
    "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
  },
  "webhook_url": "https://your-webhook.com/endpoint"
}'

# List all triggers
./scripts/call_maestro.sh event-list-triggers

See examples.md for more comprehensive examples.

Architecture

File Structure

maestro-skill/
├── SKILL.md                    # Main skill documentation
├── README.md                   # This file
├── scripts/
│   └── call_maestro.sh        # Comprehensive wrapper script (119+ commands)
└── references/
    ├── api_reference.md       # Complete API documentation
    └── examples.md            # Usage examples and patterns

API Services

The skill is organized around Maestro's 7 API services:

1. Blockchain Indexer - Primary data source with metaprotocol support
2. Esplora - Blockstream-compatible REST API for compatibility
3. Node RPC - Direct node access with JSON-RPC protocol
4. Event Manager - Webhook and event-driven architecture
5. Market Price - Price feeds and trading data
6. Mempool Monitoring - Real-time mempool awareness
7. Wallet - Address-level activity tracking

Configuration

Environment Variables

• MAESTRO_API_KEY (required) - Your Maestro API key
• MAESTRO_NETWORK (optional) - Network: mainnet (default) or testnet

Persistent Configuration

Add to ~/.bashrc or ~/.zshrc:

export MAESTRO_API_KEY="your_api_key_here"
export MAESTRO_NETWORK="mainnet"

Rate Limits

Maestro implements two-tier rate limiting:

• Daily Tier: Credit limits based on subscription tier
• Per-Second Tier: Request caps per second (e.g., 10 req/sec for Artist plan)

Monitor rate limit headers in responses:

• X-RateLimit-Limit-Second
• X-RateLimit-Remaining-Second
• X-Maestro-Credits-Limit
• X-Maestro-Credits-Remaining

Network Support

Mainnet (default)

export MAESTRO_NETWORK="mainnet"
# Base URL: https://xbt-mainnet.gomaestro-api.org/v0

Testnet4

export MAESTRO_NETWORK="testnet"
# Base URL: https://xbt-testnet.gomaestro-api.org/v0

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Resources

• Maestro Dashboard: https://dashboard.gomaestro.org
• Official Documentation: https://docs.gomaestro.org/bitcoin
• API Specifications: https://github.com/maestro-org/maestro-api-specifications
• Maestro MCP Server: https://github.com/maestro-org/maestro-mcp-server

License

This skill is provided as-is for use with the Maestro API platform.

Support

For issues or questions:

• Check the API Reference
• Review Examples
• Visit Maestro Documentation
• Contact Maestro support through the dashboard

---

Built with ❤️ for the Bitcoin ecosystem using Maestro APIs