Quickstart

Installation

Install the SDK for your environment: Web SDK:

npm install @miradorlabs/web-sdk

Node.js SDK:

npm install @miradorlabs/nodejs-sdk

Basic Usage

1. Initialize the Client

Web SDK:

import { Client } from '@miradorlabs/web-sdk';

const client = new Client('your-api-key');

Node.js SDK:

import { Client } from '@miradorlabs/nodejs-sdk';

const client = new Client('your-api-key');

2. Create a Trace

Web SDK:

const trace = client.trace({ name: 'UserAction' })
  .addAttribute('userId', 'user-123')
  .addEvent('action_started');
// → FlushTrace sent automatically at end of current microtask

Node.js SDK:

const trace = client.trace({ name: 'UserAction' })
  .addAttribute('userId', 'user-123')
  .addEvent('action_started');
// → FlushTrace auto-flushed at end of current microtask

3. Update the Trace

As your application flow progresses, add more data: Web SDK:

trace.addEvent('processing')
     .addAttribute('step', 'validation');
// → FlushTrace sent automatically at end of current microtask

trace.addEvent('completed', { result: 'success' });
// → FlushTrace sent automatically at end of current microtask

Node.js SDK:

trace.addEvent('processing')
     .addAttribute('step', 'validation');
// → FlushTrace auto-flushed at end of current microtask

trace.addEvent('completed', { result: 'success' });
// → FlushTrace auto-flushed at end of current microtask

// Close the trace when done (flushes pending data first)
await trace.close('Workflow completed');

Complete Example

Here’s a real-world example tracking a blockchain transaction: Web SDK:

import { Client, Web3Plugin } from '@miradorlabs/web-sdk';

const client = new Client('your-api-key', { plugins: [Web3Plugin()] });

async function handleTransaction(userAddress: string, amount: string) {
  // Create trace with initial context
  const trace = client.trace({ name: 'SendETH' })
    .addAttribute('from', userAddress)
    .addAttribute('amount', amount)
    .addTags(['transaction', 'ethereum'])
    .addEvent('wallet_connected');
  // → FlushTrace sent automatically

  try {
    // Sign transaction
    trace.addEvent('user_signing');
    const receipt = await sendTransaction();

    // Record transaction hash for correlation
    trace.web3.evm.addTxHint(receipt.hash, 'ethereum');
    // → FlushTrace sent automatically

    // Close the trace when done
    await trace.close('Transaction completed successfully');
  } catch (error) {
    trace.addEvent('transaction_failed', { error: error.message });
    await trace.close('Transaction failed');
  }
}

Node.js SDK:

import { Client, Web3Plugin } from '@miradorlabs/nodejs-sdk';

const client = new Client('your-api-key', { plugins: [Web3Plugin()] });

async function handleTransaction(userAddress: string, amount: string) {
  // Create trace with initial context
  const trace = client.trace({ name: 'SendETH' })
    .addAttribute('from', userAddress)
    .addAttribute('amount', amount)
    .addTags(['transaction', 'ethereum'])
    .addEvent('wallet_connected');
  // → FlushTrace auto-flushed

  try {
    // Sign transaction
    trace.addEvent('user_signing');
    const receipt = await sendTransaction();

    // Record transaction hash for correlation
    trace.web3.evm.addTxHint(receipt.hash, 'ethereum');
    // → FlushTrace auto-flushed

    // Close the trace when done
    await trace.close('Transaction completed successfully');
  } catch (error) {
    trace.addEvent('transaction_failed', { error: error.message });
    await trace.close('Transaction failed');
  }
}

Using `sendTransaction`

If you configure a provider, you can use sendTransaction() on the trace to capture tx hints and errors automatically:

import { Client, Web3Plugin } from '@miradorlabs/web-sdk';

const client = new Client('your-api-key', {
  plugins: [Web3Plugin({ provider: window.ethereum })]
});

async function handleTransaction(userAddress: string, amount: string) {
  const trace = client.trace({ name: 'SendETH' })
    .addAttribute('from', userAddress)
    .addAttribute('amount', amount)
    .addTags(['transaction', 'ethereum']);

  try {
    // sendTransaction captures tx hints and errors automatically
    const txHash = await trace.web3.evm.sendTransaction({
      from: userAddress,
      to: '0xrecipient...',
      value: '0x' + BigInt(amount).toString(16),
      chainId: 1
    });

    trace.addEvent('transaction_confirmed', { txHash });
    await trace.close('Transaction completed successfully');
  } catch (error) {
    // tx:error already captured in the trace
    await trace.close('Transaction failed');
  }
}

Using MiradorProvider

For a zero-config approach, wrap your wallet provider to automatically capture all transactions:

import { Client, MiradorProvider } from '@miradorlabs/web-sdk';

const client = new Client('your-api-key');
const provider = new MiradorProvider(window.ethereum, client);

// Use `provider` as a drop-in replacement for window.ethereum
// All eth_sendTransaction calls are automatically traced
const txHash = await provider.request({
  method: 'eth_sendTransaction',
  params: [{
    from: userAddress,
    to: '0xrecipient...',
    value: '0x38D7EA4C68000'
  }]
});

MiradorProvider works with ethers.js, viem, and any library that accepts an EIP-1193 provider. See the Provider guide for integration examples.

Auto-Flushing

Both the Web SDK and Node.js SDK automatically batch and send trace data at the end of the current JavaScript tick (microtask). You can also call flush() manually at any time to send pending data immediately.

trace.addEvent('important');
trace.flush();  // Send immediately instead of waiting for microtask

Next Steps

Learn about Traces and how they work
Explore Transaction Hints for blockchain correlation
Track Safe multisig message and transaction workflows
Share traces across frontend and backend with Cross-SDK Trace Sharing
Set up MiradorProvider for automatic transaction capture
See the full API Reference
Check out the Migration Guide if upgrading from v1

Getting Started

Core Concepts

Web3 Integration

OpenTelemetry

Automations

AI & Agents

Advanced

Best Practices

Installation

Basic Usage

1. Initialize the Client

2. Create a Trace

3. Update the Trace

Complete Example

Using `sendTransaction`

Using MiradorProvider

Auto-Flushing

Next Steps

​Installation

​Basic Usage

​1. Initialize the Client

​2. Create a Trace

​3. Update the Trace

​Complete Example

​Using sendTransaction

​Using MiradorProvider

​Auto-Flushing

​Next Steps

Installation

Basic Usage

1. Initialize the Client

2. Create a Trace

3. Update the Trace

Complete Example

Using `sendTransaction`

Using MiradorProvider

Auto-Flushing

Next Steps