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

# Relay Bridge Integration

> Track Relay (relay.link) intent-based cross-chain bridges through their full lifecycle

## Overview

[Relay](https://relay.link) is an intent-based cross-chain protocol: the user signs an intent at quote time, a solver fulfils it on the destination chain, and the bridge resolves asynchronously. Because deposit and fill happen on different chains — minutes apart, sometimes — instrumenting the flow with raw tx hashes alone misses the structure between them.

Mirador's `web3.relay.addQuoteHint()` ties a Relay intent (by `requestId`) to a trace at quote time. From there the backend `relayhint` processor resolves the full quote from the `requestId` and emits the lifecycle onto the trace:

* `RelayHintAdded` → `RelayQuoteFound`
* `RelayDepositAdded` (with the source-chain tx hint co-emitted)
* `RelaySolverCommitted` (with the destination-chain tx hint co-emitted)
* `RelayFillAdded` *or* `RelayRefunded` / `RelayFailed` / `RelayNotFound`
* `RelayTrackingFinished` (terminal)

You record the hint once. The lifecycle is filled in for you.

<Note>
  Relay methods require the `Web3Plugin`. See [Plugins](/concepts/plugins) for setup.
</Note>

## Recording a Quote Hint

Call `web3.relay.addQuoteHint()` once Relay has returned a `requestId` for the user's intent — *before* they deposit.

```typescript theme={null}
trace.web3.relay.addQuoteHint('rly_request_123');
```

That's it. The `requestId` is the only thing the SDK needs to ship — the platform resolves chain IDs, currencies, amounts, and the rest from Relay's status feed server-side.

### With an Optional Message

You can attach a free-form note for debugging context. The string rides on the proto `RelayHint.details` field.

```typescript theme={null}
trace.web3.relay.addQuoteHint('rly_request_123', 'queued from swap modal');
```

### Method Signature

```typescript theme={null}
trace.web3.relay.addQuoteHint(requestId: string, message?: string): Trace
```

| Parameter   | Type     | Required | Description                                               |
| ----------- | -------- | -------- | --------------------------------------------------------- |
| `requestId` | `string` | Yes      | Relay's API correlation key                               |
| `message`   | `string` | No       | Free-form note attached to the hint for debugging context |

<Tip>
  The relayhint processor resolves the full quote (chain IDs, currencies,
  addresses, amounts) server-side from `requestId` using bridge-api and
  Relay's status feed. The SDK doesn't ship any of that metadata.
</Tip>

## End-to-End Example

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

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

// 1. User starts a cross-chain swap
const trace = client.trace({ name: 'RelaySwap' })
  .addAttribute('user', userAddress)
  .addTag('bridge:relay');

// 2. Fetch a quote from Relay
const quote = await fetchRelayQuote({ from: 'ethereum', to: 'base', amount });

// 3. Tie the intent to the trace — *before* deposit
trace.web3.relay.addQuoteHint(quote.requestId);

// 4. Execute the deposit. Mirador-side, you don't need to do anything more —
//    the relayhint processor will emit deposit, solver-committed, and fill
//    events onto this trace as Relay reports them.
await depositOnRelay(quote);
```

## Combining With Other Hints

Relay hints compose freely with EVM transaction hints, Safe hints, and the rest of the SDK. The processor itself co-emits source and destination `addTxHint`s for the deposit and fill, so the underlying receipts also surface in the waterfall — you usually don't need to add those by hand.

```typescript theme={null}
trace
  .web3.relay.addQuoteHint(quote.requestId)
  .addAttribute('amount_usd', quote.originAmount)
  .addTag('cross-chain');
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Transaction Hints" icon="cube" href="/concepts/transaction-hints">
    EVM transaction hints and correlation
  </Card>

  <Card title="Safe Multisig" icon="vault" href="/concepts/safe-multisig">
    Track Safe multisig flows
  </Card>

  <Card title="Plugins" icon="puzzle-piece" href="/concepts/plugins">
    Web3Plugin setup and configuration
  </Card>
</CardGroup>