# How to Integrate the Relay API into Your App

Mar 6, 2026

Relay is crosschain execution infrastructure — the layer that wallets, payment processors, and DeFi applications use to route assets across 85+ chains without managing bridges, liquidity, or solver networks themselves. One integration covers the whole crosschain surface.

This guide covers the three integration paths: a drop-in SwapWidget for UI-first apps, the TypeScript SDK for programmatic control, and the direct REST API for backend and non-JS environments.

## Which Integration Path Is Right for You?

| Path               | Best for                                                 |
|-------------------|---------------------------------------------------------|
| **SwapWidget**    | React apps that need a ready-made crosschain UI         |
| **TypeScript SDK**| Custom UI or headless integrations in TypeScript/JS     |
| **REST API**      | Backend services, non-JS environments, or full control  |

All three share the same underlying infrastructure — 85+ chains, 2.7 second median execution, 99.9%+ fill rate, non-custodial execution.

## Path 1: Drop-In SwapWidget

The fastest path to a working crosschain UI. The `SwapWidget` component handles token selection, chain routing, wallet connection, and execution — you configure it, embed it.

### Install dependencies

### Set up providers

Wrap your application with the required providers. Provider order matters:

### Embed the widget

The widget handles quote fetching, step execution, status polling, and error states. Users see exact output amounts before confirming — no hidden fees.

## Path 2: TypeScript SDK

Full programmatic control over the crosschain flow. Use this when you're building a custom UI, need fine-grained callbacks, or want to embed Relay into an existing transaction flow.

### Install

Requires Node 18+ and TypeScript 5.0.4+.

### Create a client

Initialise a global singleton at app startup:

The `source` field tags your volume onchain — use your app's domain.

### Get a quote

The quote response contains exact output amounts, fees, and the steps array needed to execute.

### Execute

The `onProgress` callback fires at each state change — use it to drive loading states, transaction confirmations, and success screens. Execution settles in under 3 seconds under normal conditions.

## Path 3: Direct REST API

For backend services, server-side quote generation, or environments outside the JavaScript ecosystem.

Base URL: `https://api.relay.link`

### Step 1: Get a quote

The response includes a `steps` array. Each step is either a `transaction` (submit to chain) or a `signature` (sign off-chain).

### Step 2: Execute steps

Iterate through the steps array. For each step:

- `transaction` type → submit the provided calldata to the origin chain using the user's wallet
- `signature` type → request an off-chain signature from the user and submit it via the permit endpoint

### Step 3: Monitor status

Poll the status endpoint with the `requestId` from your quote response:

Poll once per second. Status values: `waiting` → `pending` → `success`. On success, the destination chain transaction hash is included in the response.

For real-time updates, use the [WebSocket endpoint](https://docs.relay.link/references/api/api_guides/websockets.md) instead of polling.

## What to Build On Top

### App fees

Charge a protocol fee on every crosschain action your app facilitates — collected in USDC, claimable anytime on Base.

Fees are denominated in basis points relative to input value. Minimum threshold is $0.025 per transaction. No additional infrastructure required — Relay accumulates and you withdraw.

### Gas abstraction

Users on your destination chain don't need the native gas token. Relay covers destination fees as part of execution — users only pay on the origin chain.

This matters for onboarding: a user arriving on Base for the first time doesn't need ETH to receive USDC. The protocol handles it.

### Deposit addresses

Generate static deposit addresses for users who need to fund from a CEX or external wallet — without exposing a connected wallet flow. See the [deposit addresses docs](https://docs.relay.link/features/deposit-addresses.md).

## Why Relay

**85+ chains.** One integration covers Ethereum, Base, Arbitrum, Optimism, Solana, Polygon, Tron, and 78+ others. New chains are added regularly — your integration stays current without changes.

**2.7 second median execution.** Intent-based architecture means a solver delivers the output immediately on the destination chain. No waiting for confirmation windows or challenge periods.

**Non-custodial.** The protocol coordinates through smart contracts. No centralised party holds user funds during execution. Your users remain in control throughout.

**$20B+ in volume, 99.9%+ fill rate.** Relay is production infrastructure — it's what Phantom, MetaMask, and OpenSea run on.

**Single integration, any use case.** Crosschain swaps, token buys, gasless transactions, crosschain contract calls — all accessible from the same API.

## Frequently Asked Questions

Do I need an API key to get started?

No. The Relay API is accessible without authentication for development and moderate production volume. Rate-limited API keys are available for high-volume integrations and enterprise use.

Which chains does Relay support?

85+ chains including all major EVMs (Ethereum, Base, Arbitrum, Optimism, Polygon, zkSync), Solana, Tron, and newer networks like Abstract, Berachain, and HyperEVM.

Can I integrate Relay into a non-EVM app?

Yes. Relay supports Solana natively. The REST API works with any stack. The SDK and widget are TypeScript/React — for other frameworks, use the API directly.

Is there a testnet?

Yes — see the testnet support guide. Use testnet for development and validation before going to production.

What if a transaction can't be filled?

If a step cannot complete, the protocol returns funds automatically — nothing gets stuck in an intermediate state.

How does Relay handle ERC-4337 smart accounts?

The SDK has native smart account support.

Ready to integrate? Start with the [Relay quickstart](https://docs.relay.link/references/api/quickstart.md) or explore [relay.link](https://relay.link/) to see the execution model live.