
1
Configure
To see how fast and simple Relay makes transacting cross-chain, let’s bridge real assets between inexpensive L2s—Base and Arbitrum.Prerequisites:
- Base URL:
https://api.relay.link - Environment: Node.js installed
- Wallet: An EOA with a small amount of ETH (~$2.00 USD equivalent) on Base
Coming Soon: API Key Provisioning
A self-serve form to request API keys is currently in development. For now, you can start building immediately without one.2
Quote
Every action in Relay starts with a Quote.The quote endpoint handles all of your use cases, whether it’s a bridge, swap, or cross-chain call. It calculates fees, finds the best route, and generates the transaction data.
Note: the
Request
As an example, let’s consider the scenario of bridging 0.0001 ETH from Base (Chain ID 8453) to Arbitrum One (Chain ID 42161):Note: the
requestId will be unique to every request.3
Execute
The quote endpoint returns a
steps array. Think of this as a recipe your application must follow. You need to iterate through these steps and prompt the user to sign or submit them.Deep Dive
For the full logic on parsing steps, see Understanding Step Execution.The Logic
For a simple ETH bridge, thesteps array contains a single transaction item. To execute it:- Check the Step Kind: Identify if the step is a
transaction(submit to chain) or asignature(sign off-chain). - Execute: For transactions, submit the provided
data,to,value, andchainIdusing the user’s wallet. For signatures, follow thesignatureKindprovided in the step item to sign themessage.
Need More Complexity?
For the full logic on parsing steps, see Understanding Step Execution. Because Relay’s API is generic, this exact same loop automatically handles advanced flows:- Cross-Chain Swaps: Uses the same logic as bridging; just change the input/output currencies in the Quote.
- Smart Accounts: Batches multiple steps into a single atomic user operation.
- Contract Calls: Executes arbitrary logic (like NFT mints) on the destination chain.
The Script (Node.js / Viem example)
Copy the script below to execute the transaction returned by the Quote in Step 2. You’ll need to add the wallet connection logic using your preferred provider.4
Monitor
Once you submit the transaction, the Relay Solver detects the deposit and fills the request on the destination chain.Use the status endpoint with the
Note: Replace with the requestId returned in your quote
requestId located inside each step object in your quote response to track status and confirm success. You can also use the check.endpoint property inside the step item object as the endpoint for checking the status of the request. Note: Replace with the requestId returned in your quote
Status Lifecycle
The diagram below illustrates the journey of a cross-chain transaction through Relay’s infrastructure and the corresponding API statuses. Below are descriptions for each status. Refer to the Get Status endpoint for a full list of statuses and what they mean.-
waiting: The user is submitting or has submitted the deposit transaction to the Relay Depository contract on the origin chain, but it has not yet been indexed by the system. -
pending: The deposit was successfully indexed. The Relay Solver is now monitoring the request and preparing the fill transaction on the destination chain. -
success: The Relay Solver successfully executed the “Fill Tx”, and the funds have reached the recipient.
5
Optimize
You have successfully executed your first cross-chain transaction with Relay!
Check out some of the advanced features we offer to customize the experience:
- App Fees: Monetize your integration by adding a fee (in bps) to every quote. Revenue is collected automatically in USDC.
- Smart Accounts: Use ERC-4337 and EIP-7702 to enable Gas Sponsorship and Atomic Batching (e.g., Approve + Swap in one click).
- Transaction Indexing: Handle complex settlement scenarios, like tracking complex same-chain wraps or transfers.
See Also
- Bridging & Onboarding: Learn more about instant cross-chain deposits and withdrawals.
- Swaps: Combine bridging with DEX meta-aggregation for any-to-any token swaps.
- Call Execution: Execute arbitrary transactions on any chain, paying with any token.