Skip to main content

​
Overview

The MiradorProvider is an EIP-1193 compatible wrapper that automatically captures transaction data for Mirador traces. It intercepts eth_sendTransaction and eth_sendRawTransaction calls, records tx hints and error data, and passes everything else through to the underlying provider. This means you can drop it into any dApp and get transaction tracing without changing your existing transaction flow.

​
Quick Start

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

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

// Use `provider` wherever you'd use window.ethereum
// Transactions are automatically captured in Mirador traces
const txHash = await provider.request({
  method: 'eth_sendTransaction',
  params: [{
    from: '0xabc...',
    to: '0xdef...',
    data: '0xa9059cbb...',
    value: '0x0'
  }]
});

​
How It Works

Your dApp → MiradorProvider → Underlying Provider (MetaMask, etc.)
                ↓
         Mirador Trace
         ├── tx:sent event (on success)
         ├── tx:error event (on failure)
         └── TxHint with chain + input data
  1. Your application sends a transaction through MiradorProvider
  2. The provider intercepts eth_sendTransaction / eth_sendRawTransaction
  3. It forwards the call to the underlying provider (e.g., MetaMask)
  4. On success: records the tx hash as a hint and adds a tx:sent event
  5. On failure: captures the error message, code, and revert data as a tx:error event
  6. All other RPC methods (e.g., eth_call, eth_getBalance) pass through unchanged

​
Configuration

​
Auto-Create Traces Per Transaction

By default, MiradorProvider creates a new trace for each transaction: 
const provider = new MiradorProvider(window.ethereum, client);

// Each eth_sendTransaction creates its own trace
await provider.request({ method: 'eth_sendTransaction', params: [tx1] });
await provider.request({ method: 'eth_sendTransaction', params: [tx2] });
// → 2 separate traces
You can pass traceOptions to configure the auto-created traces: 
const provider = new MiradorProvider(window.ethereum, client, {
  traceOptions: {
    name: 'WalletTx',
    maxRetries: 5
  }
});

​
Bind to an Existing Trace

For multi-step flows where you want all transactions in a single trace: 
const trace = client.trace({ name: 'CrossChainSwap' })
  .addAttributes({ user: userAddress });

const provider = new MiradorProvider(window.ethereum, client, { trace });

// All transactions go into the same trace
await provider.request({ method: 'eth_sendTransaction', params: [approveTx] });
await provider.request({ method: 'eth_sendTransaction', params: [swapTx] });
// → 1 trace with 2 tx hints

​
Using with Libraries

​
ethers.js

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

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

// Wrap in ethers BrowserProvider
const ethersProvider = new BrowserProvider(miradorProvider);
const signer = await ethersProvider.getSigner();

// Transactions through the signer are automatically captured
const tx = await signer.sendTransaction({
  to: '0xdef...',
  value: parseEther('1.0')
});

​
viem

import { createWalletClient, custom } from 'viem';
import { mainnet } from 'viem/chains';
import { Client, MiradorProvider } from '@miradorlabs/web-sdk';

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

const walletClient = createWalletClient({
  chain: mainnet,
  transport: custom(miradorProvider)
});

// Transactions are automatically captured
const hash = await walletClient.sendTransaction({
  to: '0xdef...',
  value: parseEther('1.0')
});

​
Alternative: sendTransaction on Trace

If you don’t want a wrapper provider and prefer explicit control, use sendTransaction() directly on a trace. First set up the Web3Plugin, then call sendTransaction() on the trace: 
import { Client, Web3Plugin } from '@miradorlabs/web-sdk';

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

const trace = client.trace({ name: 'Swap' });

const txHash = await trace.web3.evm.sendTransaction({
  from: '0xabc...',
  to: '0xdef...',
  data: '0xa9059cbb...',
  chainId: 1
});
This gives you the same automatic tx hint and error capture, but scoped to a specific trace method call.

​
Chain Detection

Both MiradorProvider and the Web3Plugin automatically detect the connected chain by calling eth_chainId on the underlying provider. The chain ID is mapped to a supported ChainName:
Chain IDChain Name
1ethereum
137polygon
42161arbitrum
8453base
10optimism
56bsc
You can also use the chainIdToName() utility directly: 
import { chainIdToName } from '@miradorlabs/web-sdk';

chainIdToName(1);      // 'ethereum'
chainIdToName(137);    // 'polygon'
chainIdToName('0x89'); // 'polygon'
chainIdToName(999);    // undefined

​
Error Capture

When a transaction fails (user rejection, insufficient funds, revert, etc.), the error is automatically captured: 
// This is captured automatically — no try/catch needed in your tx flow
// The trace will contain:
// {
//   event: 'tx:error',
//   details: {
//     message: 'User rejected the request',
//     code: 4001,
//     data: '0x...'  // revert data if available
//   }
// }
The original error is always re-thrown so your application’s error handling continues to work normally.

​
Next Steps

Transaction Hints

Learn about transaction correlation

Transaction Tracking Example

See a complete implementation

API Reference: Trace

Full method documentation

Types

EIP1193Provider, MiradorProviderOptions, etc.