Integration Guide

This guide covers two integration paths: Passkey Signing where the widget handles passkey-based signing for you, and Metadata Mode where you receive transaction metadata to sign with your own stack. Both modes use the same Widget component.

Prerequisites: wagmi providers configured per Installation. An understanding of your integration mode — see the Overview for architecture details.

Passkey Signing Integration

In Passkey Signing, the widget manages the full transaction lifecycle: prepare, sign via passkey, and confirm. You provide a wallet adapter and an action URL or widget ID.

Create the adapter

Use the useWagmiAdapter hook and render a Widget with your action URL:

src/components/SwapWidget.tsx

'use client';
import { useWagmiAdapter, Widget } from '@relayerfi/widget-kit-react';

export function SwapWidget() {
  const adapter = useWagmiAdapter();
  return (
    <Widget
      adapter={adapter}
      url="https://api.relayer.fi/v1/action/{widgetId}/metadata"
    />
  );
}

The Widget component handles the entire signing flow automatically. When a user initiates an action, the widget calls POST /v1/transactions/prepare to get an unsigned transaction, prompts the user with a passkey biometric challenge, and then calls POST /v1/transactions/confirm with the signed result.

User signs with passkey

The widget renders a biometric prompt (Face ID, fingerprint, or security key). Signing happens inside a secure enclave — the private key never leaves the hardware-protected environment. No additional code is needed on your side.

Transaction confirmation

After the user signs, the widget automatically submits the signed transaction to Relayer for broadcast. The widget shows a success state with the transaction hash.

In Passkey Signing, the Widget component manages the full prepare → sign → confirm lifecycle. You only need to provide the adapter and the action URL.

Metadata Mode Integration

In Metadata Mode, the widget handles UI and user input, but signing is delegated to your stack. You receive transaction metadata (routing, calldata, gas estimates) and handle signing and broadcast yourself.

Render the Widget

The Widget renders the same UI as Passkey Signing. Provide a wallet adapter and action URL:

src/components/SwapWidget.tsx

'use client';
import { useWagmiAdapter, Widget } from '@relayerfi/widget-kit-react';

export function SwapWidget() {
  const adapter = useWagmiAdapter();
  return (
    <Widget
      adapter={adapter}
      url="https://api.relayer.fi/v1/action/{widgetId}/metadata"
    />
  );
}

The Widget renders the same UI, but in Metadata Mode the signing step is delegated to your infrastructure.

Handle transaction metadata

When your integrator is configured for Metadata Mode, the Relayer API returns routing and calldata for your application to sign:

const response = await fetch('https://api.relayer.fi/v1/action/execute/swap/quote', {
  method: 'GET',
  headers: {
    'Authorization': `ApiKey ${apiKey}`,
  },
});
const { routing, calldata, gasEstimate } = await response.json();

// Build and sign with your own wallet infrastructure
const tx = buildTransaction(routing, calldata, gasEstimate);
const signedTx = await yourSigner.signTransaction(tx);
const txHash = await yourProvider.sendTransaction(signedTx);

Broadcast

You are responsible for broadcasting the signed transaction to the blockchain. Use your own RPC provider or infrastructure.

In Metadata Mode, the widget UI still renders action cards and handles user input. The difference is in how signing is handled — your backend receives the transaction parameters instead of completing the flow inside the widget.

Widget Kit ships first-party widgets for the canonical protocols Relayer supports. All examples use the same Widget component pattern — only the action URL differs.

Swap
Transfer
Crosschain Transfer
Crosschain Bridge

import { useWagmiAdapter, Widget } from '@relayerfi/widget-kit-react';

export function SwapWidget() {
  const adapter = useWagmiAdapter();
  return (
    <Widget
      adapter={adapter}
      url="https://api.relayer.fi/v1/action/{widgetId}/metadata"
    />
  );
}

Swap widget renders a token-to-token swap card. Backed by POST /v1/action/builders/swap and executed via /v1/action/execute/swap/*.

import { useWagmiAdapter, Widget } from '@relayerfi/widget-kit-react';

export function TransferWidget() {
  const adapter = useWagmiAdapter();
  return (
    <Widget
      adapter={adapter}
      url="https://api.relayer.fi/v1/action/{widgetId}/metadata"
    />
  );
}

Transfer widget handles native token and ERC20 transfers. Backed by POST /v1/action/builders/transfer-native.

import { useWagmiAdapter, Widget } from '@relayerfi/widget-kit-react';

export function CrosschainTransferWidget() {
  const adapter = useWagmiAdapter();
  return (
    <Widget
      adapter={adapter}
      url="https://api.relayer.fi/v1/action/{widgetId}/metadata"
    />
  );
}

Crosschain transfer widget moves the same asset across supported networks. Backed by POST /v1/action/builders/crosschain-transfer.

import { useWagmiAdapter, Widget } from '@relayerfi/widget-kit-react';

export function BridgeWidget() {
  const adapter = useWagmiAdapter();
  return (
    <Widget
      adapter={adapter}
      url="https://api.relayer.fi/v1/action/{widgetId}/metadata"
    />
  );
}

Bridge widget moves assets between supported chains. Backed by POST /v1/action/builders/crosschain-bridge.

Embedder: End-User Onboarding

For Embedder integrators using Passkey Signing, each end user gets their own wallet and passkey. The onboarding flow:

User registers passkey

When a new end user first interacts with a widget, they are prompted to create a passkey (biometric or security key). This registers a WebAuthn credential tied to your application’s wallet workspace.

Wallet creation

A wallet is automatically created in the user’s workspace. The private key is generated and stored inside a hardware-secured enclave — neither you nor Relayer can access it.

Subsequent transactions

For future transactions, the user simply approves with their passkey. No seed phrases, no browser extensions.

Passkey recovery is available through Relayer’s email recovery flow (POST /v1/signing/recovery/initiate). Ensure you communicate recovery options to your users during onboarding.

For workspace-level integrations (not end-user facing), team members register passkeys through the Relayer dashboard. Policies define which team members can approve which transaction types.

WidgetProps Reference

Prop	Type	Required	Description
`adapter`	`WidgetAdapter`	Yes	Wallet adapter — use `useWagmiAdapter()` or `createWagmiAdapter(config)`
`url`	`string`	Yes*	URL to fetch widget metadata from
`metadata`	`ValidatedMetadata`	Yes*	Pass pre-validated metadata instead of `url`
`securityState`	`WidgetSecurityState`	Yes (with `metadata`)	Security context for pre-validated flow
`stylePreset`	`'x' \| undefined`	No	Apply Twitter/X visual preset
`enableAnalytics`	`boolean`	No	Track interaction events (default: `true`)
`player`	`boolean`	No	Enable player mode for embedded contexts
`className`	`string`	No	Additional CSS class on the root element
`startDisabled`	`boolean`	No	Render widget in disabled state

Either url or metadata + securityState must be provided, not both.

Theming

Widgets read data-x-theme="dark|light" from the document root to determine the active theme.

Automatic Theme Detection (Twitter/X)

Call applyXTheme() once on mount to read the Twitter/X night mode cookie and set the theme attribute automatically:

import { applyXTheme } from '@relayerfi/widget-kit-react';

// Call once on mount
applyXTheme();

React Hook

Use the useTheme hook to read the current theme in your components:

import { useTheme } from '@relayerfi/widget-kit-react';

function MyComponent() {
  const theme = useTheme(); // 'dark' | 'light'
  return <div data-theme={theme}><Widget ... /></div>;
}

Manual Override

Set the attribute directly on document.documentElement for custom toggle UIs:

document.documentElement.setAttribute('data-x-theme', 'dark');

Twitter/X stylePreset

Pass stylePreset="x" to apply the Twitter/X visual preset — rounded card, correct font sizing, consistent with the embedded appearance on social platforms:

<Widget adapter={adapter} url={url} stylePreset="x" />

Platform Observers

The library ships observers for automatic widget detection on Twitter/X, YouTube, and Twitch. These observers scan the DOM for canonical action URLs and render Widget components inline. For custom embedding in your own app, use the Widget component directly as shown above. See the Widget Kit Overview for architecture details.

Widget Kit

Passkey Signing Integration

Metadata Mode Integration

Widget Examples

Embedder: End-User Onboarding

WidgetProps Reference

Theming

Automatic Theme Detection (Twitter/X)

React Hook

Manual Override

Twitter/X stylePreset

Platform Observers

Next Steps

SDK Reference

Widget Kit Overview

Widget Kit

Documentation Index

​Passkey Signing Integration

​Metadata Mode Integration

​Widget Examples

​Embedder: End-User Onboarding

​WidgetProps Reference

​Theming

​Automatic Theme Detection (Twitter/X)

​React Hook

​Manual Override

​Twitter/X stylePreset

​Platform Observers

​Next Steps

SDK Reference

Widget Kit Overview

Passkey Signing Integration

Metadata Mode Integration

Widget Examples

Embedder: End-User Onboarding

WidgetProps Reference

Theming

Automatic Theme Detection (Twitter/X)

React Hook

Manual Override

Twitter/X stylePreset

Platform Observers

Next Steps