> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirador.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Web SDK

> Browser SDK for wallet, provider, and web3 transaction capture

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

<Info>
  For **server-side** services, use a standard [OpenTelemetry SDK](/opentelemetry/sdks) instead. The Node.js SDK is [deprecated](/nodejs-sdk).
</Info>

## 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](https://opentelemetry.io/docs/languages/js/) 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`](/concepts/provider) 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](/advanced/browser-metadata) 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](/advanced/lifecycle-callbacks) 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

<CodeGroup>
  ```bash npm theme={null}
  npm install @miradorlabs/web-sdk
  ```

  ```bash yarn theme={null}
  yarn add @miradorlabs/web-sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @miradorlabs/web-sdk
  ```
</CodeGroup>

Or load it from a CDN with no bundler. See [Installation](/installation#cdn--browser-global) for the UMD global and module formats.

## Quick example

```typescript theme={null}
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:

```typescript theme={null}
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](/opentelemetry/enrichment-hints) 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

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/installation">
    Package managers, CDN, module formats, browser support
  </Card>

  <Card title="Core concepts" icon="book" href="/concepts/traces">
    Traces, spans, events, attributes, and plugins
  </Card>

  <Card title="Provider guide" icon="wallet" href="/concepts/provider">
    Zero-config capture with ethers.js and viem
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/client">
    Client, Trace, Span, and type definitions
  </Card>
</CardGroup>