Before you start
While not mandatory for integration, doing the following will improve the UX for your users considerably:- Verify user balance - Confirm user has sufficient funds for amount + fees, including native gas on the origin chain for the deposit transaction
- Check chain support - Confirm both origin and destination chains are supported
- Validate quote - Quotes are revalidated when being filled, keep your quotes as fresh as possible.
- Handle errors - Implement proper error handling for API requests and transaction failures
Get a Quote
Get a Quote
To execute a cross-chain transaction, you need to specify the origin chain for payment, the destination chain where the contract is deployed, and the transaction data to execute. Use the quote endpoint with specific parameters for cross-chain calling.Cross-chain calls support bothEXACT_INPUT and EXACT_OUTPUT. Use EXACT_OUTPUT when the destination call requires a precise output amount. Use EXACT_INPUT when you want to cap how much the user spends and can tolerate variable output.Using EXACT_INPUT with proxy contracts
For EXACT_INPUT calls, integrators usually need their own proxy contract on the destination chain. Because Relay delivers a variable output amount, you cannot always precompute the final calldata at quote time.Depositing into Aave is a good example. With EXACT_OUTPUT, the request can include two calls directly: approve the Aave pool, then call supply() with a fixed amount. With EXACT_INPUT, the destination amount is variable, so route the calls through your own Aave-specific proxy contract instead.A simple proxy contract can:- pull the full approved token balance from the caller that initiated execution, such as Relay’s router in a Relay deposit flow
- approve the Aave pool contract
- call
supply()using its full current balance
- an approval to your proxy contract, usually for
MAX_UINT256 - a call to your proxy contract, such as
execute()
txs[].data must contain ABI-encoded calldata.execute(), your proxy can read its token balance, approve the Aave pool, and call supply(asset, balance, onBehalfOf, referralCode) with the live balance.Contract Compatibility
Before integrating cross-chain calls, ensure your contract is compatible with Relay. Review our Contract Compatibility overview to make any necessary changes to your smart contracts. Contract Interaction with Web3
When calling smart contracts, you’ll need to encode the function call data. Here’s how to do it with popular libraries:Important for ERC20 transactions: If your contract call involves spending
ERC20 tokens, you must include an approval transaction in your
txs array
before the actual contract call. See the ERC20
examples below.ERC20 Contract Calls
Critical: When your contract call involves spending ERC20 tokens, you must include an approval transaction in yourtxs array. The approval must come before the actual contract call.ERC20 Approval + Contract Call Pattern
Sweeping ERC20 Balance
Relay’s router contract has a useful function that you can call to transfer out full balance of an ERC20 token, even if you don’t know the full balance. There are currently two methods for doing this:You can use these by passing in the txs field as follows:ERC20 Troubleshooting Guide
Problem: “ERC20: transfer amount exceeds allowance” error Solution: Ensure you include the approval transaction before your contract callProblem: Transaction reverts with “ERC20: insufficient allowance” Solution: Check that the approval amount is sufficient for your contract callProblem: Approval transaction succeeds but contract call fails Solution: Verify the contract address in the approval matches the contract you’re callingERC20 Best Practices
- Always approve before spending: Include approval as the first transaction
- Use exact amounts: Approve the exact amount your contract will spend
- Check token decimals: USDC uses 6 decimals, most others use 18
- Verify contract addresses: Use the correct token contract for each chain
- Handle allowances: Some tokens require setting allowance to 0 before setting a new amount
Quote Parameters for Cross-Chain Calls
| Parameter | Type | Description |
|---|---|---|
amount | string | Total value of all txs combined |
tradeType | string | EXACT_INPUT (quote by input amount) or EXACT_OUTPUT (quote by required output) |
txs | array | Array of transaction objects |
txs[].to | string | Contract address to call |
txs[].value | string | ETH value to send with call |
txs[].data | string | Encoded function call data |
Monitor Cross-Chain Call Status
Monitor Cross-Chain Call Status
Track the progress of your cross-chain call using the status endpoint:Preflight Checklist
Contract compatibility - Before integrating cross-chain calls, ensure your contract is compatible with Relay. Review our Contract Compatibility overview to make any necessary changes to your smart contracts. ERC20 approvals - Include approval transactions before any ERC20 spending calls Verify transaction data - Confirmamount equals the sum of all txs[].value fields
Check tradeType - Use "EXACT_OUTPUT" for a precise output, or "EXACT_INPUT" to cap spend
Plan for EXACT_INPUT execution - Use a destination proxy contract that reads the delivered balance and builds follow-up calldata at runtime
Validate call data - Ensure contract function calls are properly encoded
Test contract calls - Verify contract functions work as expected on destination chain
Gas estimation - Account for potential gas usage variations in contract calls
Common Use Cases
Below are some common use cases for cross-chain calls.- NFT Minting with ETH: Mint NFTs on L2s while paying from L1
- NFT Minting with ERC20: Mint NFTs using USDC
- DeFi Operations: Execute swaps, provide liquidity, or claim rewards on other chains
- Gaming: Execute game actions, purchase items, or claim rewards across chains
See Also
- Gasless Swaps: Find the right gasless approach for your app — permit-based, ERC-4337, or EIP-7702.
- Smart Accounts: Enable fully gasless transactions where users hold zero native tokens, using EIP-7702 or ERC-4337.
- Gasless Execution: Execute gasless transactions where the transaction signer and gas payer are different addresses.
- App Fees: Monetize your integration by adding a fee (in bps) to every quote.
- Fee Sponsorship: Sponsor fees for your users to reduce friction and improve the user experience.
- Handling Errors: Handle quote errors when using the Relay API.
- Relay Fees: Understand the fees associated with using the Relay API.