Maestro Official Developer Documentation

This guide for understanding the Event Manager can be viewed in conjunction with our Bitcoin Wallet Insight Demo - an example Bitcoin application showcasing the Wallet API and Event Manager capabilities for wallet insights and state monitoring.You can deploy this demo to see the Event Manager in action, as well as how it is integrated, before implementing it in your own application to:

Set up automated monitoring for Bitcoin wallet activities, transactions, and blockchain events
Create triggers that fire when specific conditions are met (e.g., large transactions, new inscriptions)
Receive real-time notifications via webhooks to keep your application responsive

Overview

The Event Manager is a powerful service that allows you to monitor Bitcoin blockchain events and receive notifications when specific conditions are met. Unlike user-facing features, the Event Manager is designed as an admin-only service that operates behind the scenes to keep your application informed of important blockchain activities. Key benefits:

Real-time monitoring of wallet addresses, transactions, and blockchain state
Automated notifications via webhooks when triggers activate
Flexible trigger conditions for various blockchain events

Architecture Overview

Flow Explanation:

Admin creates triggers via the Maestro Dashboard
Event Manager monitors the blockchain for specified conditions
Webhooks fire when conditions are met, sending data to your application
Your application processes the webhook and takes appropriate actions

Prerequisites

Node.js ≥16 and npm (or Yarn) installed
A Maestro API key with Event Manager access
An existing application (we’ll use our maestro-replit-templates wallet demo as an example)

Complete Event Manager Operations

Setup and Manage Event Triggers in the Maestro Dashboard Interface

The Maestro Dashboard provides a user-friendly interface for managing Event Manager operations. Follow these steps to set up monitoring for your Bitcoin applications:

Step 1: Access the Event Manager Dashboard

Log in to your Maestro Dashboard
Navigate to the Event Manager section in the sidebar
Select your project that has Event Manager access enabled
Choose the network (Mainnet or Testnet) you want to monitor

Step 2: Create Your First Trigger

Click “Create New Trigger” to open the trigger creation wizard
Configure basic settings:
- Trigger Name: Give it a descriptive name (e.g., “Wallet Balance Monitor”)
- Chain: Select “Bitcoin”
- Network: Choose “Mainnet” or “Testnet”
- Trigger Type: Select “Transaction” for monitoring Bitcoin transactions
Set up your webhook endpoint:
- Webhook URL: Enter your application’s webhook endpoint
- Testing tip: Use webhook.site to generate a test URL for initial setup
Configure trigger conditions using the filter builder:
- For wallet monitoring: Set filter key to “sender_or_receiver” with your Bitcoin address
- For large transactions: Set “total_input_volume” with operator ”>” and value in satoshis
- For specific addresses: Use “sender” or “receiver” filters as needed
Set confirmation requirements: Choose 1-6 confirmations based on your security needs
Click “Create Trigger” to activate monitoring

Step 3: Test Your Trigger

Send a test transaction that matches your trigger conditions
Monitor the Event Logs section to see triggered events in real-time
Check your webhook endpoint to verify you’re receiving notifications
Review the payload structure to understand the data format for your application

Step 4: Manage Active Triggers

View all triggers in the dashboard with status indicators (Active/Paused)
Monitor trigger statistics including event count and last triggered time
Pause/Resume triggers as needed for maintenance or testing
Edit trigger settings to modify filters, webhook URLs, or confirmation requirements
Delete unused triggers to stay within your account limits and keep things organized

Step 5: Monitor Event Logs

Access the Event Logs tab to view all triggered events
Filter logs by trigger, date range, or status for easier debugging
Inspect event details including the full transaction payload and webhook response
Troubleshoot webhook issues by checking response status codes and error messages
Export logs for analysis or compliance reporting if needed

Pro Tips for Dashboard Usage:

Start with testnet triggers to familiarize yourself with the interface
Use descriptive trigger names that indicate their purpose
Set up multiple triggers with different confirmation levels for different use cases
Regularly review and clean up unused triggers to optimize performance

If you’d prefer to manage triggers/logs programmatically, the Event Manager API provides comprehensive functionality for this. Below are all available operations:

Trigger Management

1. Creating Triggers

Create triggers to monitor Bitcoin transactions based on specific conditions:

const eventManager = new EventManagerApi('mainnet', 'your-api-key');

const triggerConfig: CreateTriggerRequest = {
  name: "High Value Transaction Monitor",
  chain: "bitcoin",
  network: "mainnet",
  type: "transaction",
  webhook_url: "https://your-app.com/webhook",
  filters: [
    {
      key: "total_input_volume",
      operator: ">",
      value: "1000000000" // 10 BTC in satoshis
    }
  ],
  confirmations: 6
};

const newTrigger = await eventManager.createTrigger(triggerConfig);
console.log('Created trigger:', newTrigger.id);

2. Listing All Triggers

Retrieve all your active triggers:

const triggers = await eventManager.listTriggers();
triggers.forEach(trigger => {
  console.log(`${trigger.name} (${trigger.id}): ${trigger.status}`);
  console.log(`Events triggered: ${trigger.event_count}`);
});

3. Getting Trigger Details

Fetch detailed information about a specific trigger:

const triggerId = "your-trigger-id";
const trigger = await eventManager.getTrigger(triggerId);
console.log('Trigger details:', trigger);

4. Updating Triggers

Modify existing triggers (name, filters, status, etc.):

const updates: UpdateTriggerRequest = {
  name: "Updated High Value Monitor",
  chain: "bitcoin",
  network: "mainnet",
  type: "transaction",
  webhook_url: "https://your-app.com/webhook",
  status: "paused", // or "active"
  filters: [
    {
      key: "total_input_volume",
      operator: ">",
      value: "2000000000" // 20 BTC in satoshis
    }
  ],
  confirmations: 6
};

const updatedTrigger = await eventManager.updateTrigger(triggerId, updates);
console.log('Updated trigger:', updatedTrigger);

5. Deleting Triggers

Remove triggers that are no longer needed:

await eventManager.deleteTrigger(triggerId);
console.log('Trigger deleted successfully');

Available filter keys include:

sender: Monitor transactions from specific addresses (operator: =)
receiver: Monitor transactions to specific addresses (operator: =)
sender_or_receiver: Monitor transactions involving specific addresses (operator: =)
transaction_id: Monitor specific transaction IDs (operator: =)
total_input_volume: Monitor by transaction value (operators: =, >, >=, <, <=)
fee: Monitor by transaction fee (operators: =, >, >=, <, <=)
size: Monitor by transaction size in bytes (operators: =, >, >=, <, <=)
weight: Monitor by transaction weight (operators: =, >, >=, <, <=)

Event Log Management

6. Listing Event Logs

View logs of triggered events with optional filtering:

// List all logs with pagination
const logs = await eventManager.listEventLogs({
  page: 1,
  limit: 50
});

// Filter logs by trigger
const triggerLogs = await eventManager.listEventLogs({
  trigger_id: "your-trigger-id",
  page: 1,
  limit: 20
});

// Filter by chain and network
const mainnetLogs = await eventManager.listEventLogs({
  chain: "bitcoin",
  network: "mainnet",
  page: 1,
  limit: 25
});

logs.forEach(log => {
  console.log(`Log ${log.id}: Status ${log.status}`);
  console.log(`Response: ${log.response_status} - ${log.response}`);
});

7. Getting Specific Event Logs

Retrieve detailed information about a specific event log:

const logId = "your-log-id";
const eventLog = await eventManager.getEventLog(logId);
console.log('Event log details:', {
  id: eventLog.id,
  trigger_id: eventLog.trigger_id,
  status: eventLog.status,
  response_status: eventLog.response_status,
  payload: eventLog.payload
});

Advanced Filter Examples

Here are practical examples of different filter configurations:

// Monitor large transactions (>= 1 BTC)
const largeTransactionTrigger: CreateTriggerRequest = {
  name: "Large Transaction Monitor",
  chain: "bitcoin",
  network: "mainnet",
  type: "transaction",
  webhook_url: "https://your-app.com/webhook/large-tx",
  filters: [{
    key: "total_input_volume",
    operator: ">=",
    value: "100000000" // 1 BTC in satoshis
  }],
  confirmations: 3
};

// Monitor specific wallet address
const walletMonitor: CreateTriggerRequest = {
  name: "Wallet Activity Monitor",
  chain: "bitcoin", 
  network: "mainnet",
  type: "transaction",
  webhook_url: "https://your-app.com/webhook/wallet",
  filters: [{
    key: "sender_or_receiver",
    operator: "=",
    value: "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
  }],
  confirmations: 1
};

// Monitor high fee transactions
const highFeeTrigger: CreateTriggerRequest = {
  name: "High Fee Monitor",
  chain: "bitcoin",
  network: "mainnet", 
  type: "transaction",
  webhook_url: "https://your-app.com/webhook/high-fee",
  filters: [{
    key: "fee",
    operator: ">",
    value: "100000" // 0.001 BTC in satoshis
  }],
  confirmations: 2
};

// Using the helper function for wallet monitoring
const walletAddress = "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh";
const balanceMonitor = createWalletBalanceMonitoringTrigger(
  walletAddress,
  "mainnet",
  "https://your-app.com/webhook/balance",
  1 // confirmations
);

const createdTrigger = await eventManager.createTrigger(balanceMonitor);

Security Considerations

Important Security Notes:

Use Maestro Dashboard: Manage all triggers through the secure Maestro Dashboard instead of building custom admin interfaces
Webhook Validation: Verify webhook authenticity using signatures
Rate Limiting: Consider implementing rate limiting on webhook endpoints

Common Use Cases

1. Wallet Monitoring

Track activity on specific wallet addresses
Get notified when funds are received or sent
Monitor for suspicious activity patterns

2. Large Transaction Alerts

Alert when transactions exceed certain thresholds
Monitor for whale movements
Compliance and AML monitoring

3. Rune/Inscription Activity

Track new rune mints or transfers
Monitor inscription marketplace activity
Get notified of rare asset movements

4. Portfolio Automation

Automatically update portfolio values
Trigger rebalancing based on events
Generate activity reports

See our example Wallet Insights Demo for a working implementation of wallet monitoring and event management operating together in a single application.

Best Practices

Test Webhooks: Use tools like webhook.site or ngrok for local webhook testing
Document Triggers: Keep clear documentation of what each trigger does
Regular Cleanup: Remove unused triggers to avoid unnecessary API calls and remain below your account’s trigger limits

🎉 You’re Done!

The Maestro Event Manager transforms your application from reactive to proactive by providing real-time blockchain monitoring capabilities. By implementing the admin-only architecture shown in this guide, you can:

Monitor critical wallet activities without constant manual checking
Respond instantly to important blockchain events
Automate business logic based on on-chain activities
Maintain security by keeping event management admin-only

The integration with your existing wallet demo creates a powerful combination of portfolio visualization and automated monitoring, making your application more responsive and valuable to users. For more advanced features, explore the full Event Manager API documentation and consider implementing custom trigger conditions for your specific use case. Be sure to review Maestro’s rate limits, trigger limits and pricing tiers to select the plan that best fits your application’s needs.

SupportIf you are experiencing any trouble with the above, open an issue or reach out on Discord.

Blockchain Indexer API

Esplora API

Node RPC API

Mempool Monitoring API

Event Manager API

Market Price API

Wallet API

Integrating Maestro Event Manager into Your Application

Overview

Architecture Overview

Prerequisites

Complete Event Manager Operations

Setup and Manage Event Triggers in the Maestro Dashboard Interface

Step 1: Access the Event Manager Dashboard

Step 2: Create Your First Trigger

Step 3: Test Your Trigger

Step 4: Manage Active Triggers

Step 5: Monitor Event Logs

Trigger Management

1. Creating Triggers

2. Listing All Triggers

3. Getting Trigger Details

4. Updating Triggers

5. Deleting Triggers

Event Log Management

6. Listing Event Logs

7. Getting Specific Event Logs

Advanced Filter Examples

Security Considerations

Common Use Cases

1. Wallet Monitoring

2. Large Transaction Alerts

3. Rune/Inscription Activity

4. Portfolio Automation

Best Practices

🎉 You’re Done!

Blockchain Indexer API

Esplora API

Node RPC API

Mempool Monitoring API

Event Manager API

Market Price API

Wallet API

​Overview

​Architecture Overview

​Prerequisites

​Complete Event Manager Operations

​Setup and Manage Event Triggers in the Maestro Dashboard Interface

​Step 1: Access the Event Manager Dashboard

​Step 2: Create Your First Trigger

​Step 3: Test Your Trigger

​Step 4: Manage Active Triggers

​Step 5: Monitor Event Logs

​Trigger Management

​1. Creating Triggers

​2. Listing All Triggers

​3. Getting Trigger Details

​4. Updating Triggers

​5. Deleting Triggers

​Filter Options

​Event Log Management

​6. Listing Event Logs

​7. Getting Specific Event Logs

​Advanced Filter Examples

​Security Considerations

​Common Use Cases

​1. Wallet Monitoring

​2. Large Transaction Alerts

​3. Rune/Inscription Activity

​4. Portfolio Automation

​Best Practices

​🎉 You’re Done!

Overview

Architecture Overview

Prerequisites

Complete Event Manager Operations

Setup and Manage Event Triggers in the Maestro Dashboard Interface

Step 1: Access the Event Manager Dashboard

Step 2: Create Your First Trigger

Step 3: Test Your Trigger

Step 4: Manage Active Triggers

Step 5: Monitor Event Logs

Trigger Management

1. Creating Triggers

2. Listing All Triggers

3. Getting Trigger Details

4. Updating Triggers

5. Deleting Triggers

Filter Options

Event Log Management

6. Listing Event Logs

7. Getting Specific Event Logs

Advanced Filter Examples

Security Considerations

Common Use Cases

1. Wallet Monitoring

2. Large Transaction Alerts

3. Rune/Inscription Activity

4. Portfolio Automation

Best Practices

🎉 You’re Done!