Using Relay’s Cross-chain Execution
You can use Relay Cross-chain Execution with custom call methods or with the pre-defined methods of the Reservoir Aggregator.Custom Call Methods
Relay lets you execute arbitrary call data cross-chain using a custom call method. You can call custom contract methods, mint from custom contracts, mint + bridge (mint an NFT and bridge additional funds in one), or any other custom call execution. To get started make sure that you install and configure the Relay SDK. Ensure that everything is configured properly before moving on to implementing the call action.Guides
- Bridge: Bridge funds to another chain
- Custom Contract Call: Call a contract method across chains to perform a multitude of actions
Cross-chain Execution with the Reservoir Aggregator
To use cross-chain execution with the Reservoir Aggregator, i.e. to mint, buy or sell NFTs aggregated by Reservoir, simply use the Reservoir SDK to trigger cross-chain execution with the appropriate method. When using the Reservoir SDK to trigger a cross-chain purchase all that’s required is additionally passing acurrencyChainId
to the buyToken method. This assumes you know which token you would like to buy or mint. You can leverage the Reservoir API to look at aggregated collection liquidity, or trending mints. Below is an example of what that would look like to buy a token from secondary:
Cross-chain Example
Summary
1
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.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.Basic Cross-Chain Call Quote
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
ERC20 Troubleshooting Guide
Problem: “ERC20: transfer amount exceeds allowance” error Solution: Ensure you include the approval transaction before your contract call Problem: Transaction reverts with “ERC20: insufficient allowance”Solution: Check that the approval amount is sufficient for your contract call Problem: Approval transaction succeeds but contract call fails Solution: Verify the contract address in the approval matches the contract you’re calling
ERC20 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 | Required | Description |
---|---|---|---|
user | string | Yes | Address that will pay for the transaction |
originChainId | number | Yes | Chain ID where payment originates |
destinationChainId | number | Yes | Chain ID where contract calls execute |
originCurrency | string | Yes | Currency contract on source chain (e.g., “0x0000000000000000000000000000000000000000”, “0x833589fcd6edb6e08f4c7c32d4f71b54bda02913”) |
destinationCurrency | string | Yes | Currency contract on destination chain |
amount | string | Yes | Total value of all txs combined |
tradeType | string | Yes | Must be “EXACT_OUTPUT” |
txs | array | Yes | Array of transaction objects |
txs[].to | string | Yes | Contract address to call |
txs[].value | string | Yes | ETH value to send with call |
txs[].data | string | Yes | Encoded function call data |
recipient | string | No | Alternative recipient for any surplus |
referrer | string | No | Identifier that can be used to monitor transactions from a specific source. |
refundTo | string | No | Address to send the refund to in the case of failure, if not specified the user address is used |
Execute the Call
After receiving a call quote, execute it by processing each step in the response. The execution handles both the origin chain transaction and destination chain fulfillment.Learn more about step execution using the API here.
Monitor Cross-Chain Call Status
Track the progress of your cross-chain call using the status endpoint:Status Values
Status | Description |
---|---|
waiting | Deposit tx for the request is yet to be indexed |
pending | Deposit tx was indexed, now the fill is pending |
success | Relay completed successfully |
failure | Relay failed |
refund | Funds were refunded due to failure |
Advanced Features
App Fees
You can include app fees in your call requests to monetize your integration:Custom Slippage
Control slippage tolerance for your calls:Preflight Checklist
☐ Contract compatibility - Ensure your smart contract follows Relay compatibility guidelines ☐ ERC20 approvals - Include approval transactions before any ERC20 spending calls ☐ Verify transaction data - Confirmamount
equals the sum of all txs[].value
fields
☐ Check tradeType - Must be set to "EXACT_OUTPUT"
for cross-chain calls
☐ Validate call data - Ensure contract function calls are properly encoded
☐ Token addresses - Use correct ERC20 contract addresses for each chain
☐ Test contract calls - Verify contract functions work as expected on destination chain
☐ Balance verification - Confirm user has sufficient funds for amount + fees
☐ Error handling - Implement proper error handling for failed contract executions
☐ Monitor progress - Use status endpoints to track execution progress
☐ Gas estimation - Account for potential gas usage variations in contract calls