> ## 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.

# Quickstart

> Get started with the Mirador SDK in under 5 minutes

## Installation

Install the SDK for your environment:

**Web SDK:**

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

**Node.js SDK:**

```bash theme={null}
npm install @miradorlabs/nodejs-sdk
```

## Basic Usage

### 1. Initialize the Client

**Web SDK:**

```typescript theme={null}
import { Client } from '@miradorlabs/web-sdk';

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

**Node.js SDK:**

```typescript theme={null}
import { Client } from '@miradorlabs/nodejs-sdk';

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

### 2. Create a Trace

**Web SDK:**

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

**Node.js SDK:**

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

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

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

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

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

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

```typescript theme={null}
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'
  }]
});
```

<Tip>
  `MiradorProvider` works with ethers.js, viem, and any library that accepts an EIP-1193 provider. See the [Provider guide](/concepts/provider) for integration examples.
</Tip>

## 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.

```typescript theme={null}
trace.addEvent('important');
trace.flush();  // Send immediately instead of waiting for microtask
```

## Next Steps

* Learn about [Traces](/concepts/traces) and how they work
* Explore [Transaction Hints](/concepts/transaction-hints) for blockchain correlation
* Track [Safe multisig](/concepts/safe-multisig) message and transaction workflows
* Share traces across frontend and backend with [Cross-SDK Trace Sharing](/concepts/traces#cross-sdk-trace-sharing)
* Set up [MiradorProvider](/concepts/provider) for automatic transaction capture
* See the full [API Reference](/api-reference/client)
* Check out the [Migration Guide](/migration) if upgrading from v1