Web SDK

@miradorlabs/web-sdk is Mirador’s browser SDK. It is actively supported and is the recommended way to instrument front-end web3 applications.

For server-side services, use a standard OpenTelemetry SDK instead. The Node.js SDK is deprecated.

When to use it

Use the Web SDK when your telemetry starts in the browser and involves a wallet:

You need the transaction lifecycle from user intent through wallet signature to on-chain confirmation, including the steps that never reach your backend (wallet prompts, user rejections, chain switches).
You want zero-config capture by wrapping an EIP-1193 provider, rather than hand-instrumenting every call site.
You want automatic browser environment metadata attached to each trace.

If you only need standard browser telemetry (page loads, fetch/XHR timing) without wallet capture, the OpenTelemetry JS browser SDK works against the same OTLP endpoint.

Features

Feature	What it does
Fluent builder	Chainable `client.trace().addAttribute().addEvent()` API
Spans	Timed, nestable units of work via `startSpan()` / `span(name, fn)`
Auto-flush	Batches and sends at the end of the current microtask; `flush()` to force
EIP-1193 provider wrapper	`MiradorProvider` captures every `eth_sendTransaction` with no call-site changes
Web3 plugin	`web3.evm`, `web3.safe`, `web3.solana`, `web3.relay`, `web3.canton` hint namespaces
Browser metadata	27+ environment metrics collected automatically
Cross-SDK trace sharing	Resume a browser-started trace on the backend by trace ID
Sampling	`sampleRate` or a custom `sampler`; sampled-out traces return a zero-cost `NoopTrace`
Lifecycle callbacks	Observe flush success, failure, close, and dropped items
Retry and backoff	Full-jitter retry on retryable errors, with client-wide rate-limit backoff
Pluggable logger	No-op by default; enable with `debug: true` or supply your own
TypeScript	Full type definitions included

Install

npm install @miradorlabs/web-sdk

yarn add @miradorlabs/web-sdk

pnpm add @miradorlabs/web-sdk

Or load it from a CDN with no bundler. See Installation for the UMD global and module formats.

Quick example

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

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

const trace = client.trace({ name: 'SwapExecution' })
  .addAttribute('from', '0xabc...')
  .addTags(['dex', 'swap'])
  .addEvent('swap_initiated');

const tx = await wallet.sendTransaction(swapTx);

trace.web3.evm.addTxHint(tx.hash, 'ethereum', { input: swapTx.data });

await trace.close('Swap completed');

Wrap a provider instead, and every transaction is captured automatically:

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

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

// Drop-in replacement for window.ethereum — works with ethers.js and viem

Relationship to OpenTelemetry

Both paths feed the same trace pipeline, so a browser trace and an OTel backend trace can be correlated into one flow. The Web SDK’s web3.* hint methods and OTel’s mirador.* enrichment events trigger the same backend enrichment. A typical setup: Web SDK in the browser for the wallet half, OpenTelemetry on the server for the API half, joined by a shared trace ID.

Learn more

Installation

Package managers, CDN, module formats, browser support

Core concepts

Traces, spans, events, attributes, and plugins

Provider guide

Zero-config capture with ethers.js and viem

API reference

Client, Trace, Span, and type definitions

Getting Started

OpenTelemetry

Web3 Integration

Payments & Market Data

Automations

AI & Agents

Best Practices

Web SDK

When to use it

Features

Install

Quick example

Relationship to OpenTelemetry

Learn more

Installation

Core concepts

Provider guide

API reference

​When to use it

​Features

​Install

​Quick example

​Relationship to OpenTelemetry

​Learn more

Installation

Core concepts

Provider guide

API reference

When to use it

Features

Install

Quick example

Relationship to OpenTelemetry

Learn more