Skip to main content

​
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