How to Integrate the Relay API into Your App

Mar 6, 2026

7 min read

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?

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

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 or explore relay.link to see the execution model live.