Cross-Chain Swap (Relay)
Swap or bridge tokens across chains using Relay Protocol. Supports same-chain swaps, cross-chain EVM transfers, and bridging to Solana. Configurable slippage.
Catalog action EVM Onchain wallet Gas bridge
Swap or bridge tokens across chains using Relay Protocol. Supports same-chain swaps, cross-chain EVM transfers, and bridging to Solana. Configurable slippage.
This action can require a wallet connector, gas, token movement, or an external side effect. Test with simulation or a controlled amount before using it in a live workflow.
At a Glance
| Field | Value |
|---|---|
| Action ID | relay-swap |
| Category | EVM Onchain |
| Connector | wallet |
| Requires gas | Yes |
| Funds movement | bridge |
| Tags | blockchain, evm, dex, swap, bridge, cross-chain, relay, defi |
Payload Schema
| Field | Type | Required | Description |
|---|---|---|---|
srcChainId | number | Yes | Source chain ID (e.g., 1 for Ethereum, 8453 for Base, 42161 for Arbitrum) |
tokenIn | string | Yes | Source token address. Use "native", 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE, or 0x0000000000000000000000000000000000000000 for native tokens (ETH, BNB, POL, etc.). Use native address format for other chains (e.g., base58 for Solana). |
amountIn | string | No | Exact input amount to sell in smallest unit (wei for ETH). Provide either amountIn (EXACT_INPUT) or amountOut (EXACT_OUTPUT), not both. |
amountOut | string | No | Desired output amount to receive in smallest unit. When provided, Relay quotes the minimum amountIn needed to receive this amount (EXACT_OUTPUT mode). Provide either amountIn or amountOut, not both. |
dstChainId | number | Yes | Destination chain ID. Can be same as srcChainId for same-chain swaps or different for cross-chain. |
tokenOut | string | Yes | Destination token address. Use "native", 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE, or 0x0000000000000000000000000000000000000000 for native tokens (ETH, BNB, POL, etc.). Use native address format for other chains (e.g., base58 for Solana). |
recipient | string | No | Recipient address for the output tokens. Defaults to sender if not specified. Required for non-EVM destinations (e.g., Solana). |
useMaxTokenInBalance | boolean | No | When true and tokenIn is a native token, subtracts estimated gas cost from amountIn (based on current gas price). Useful when bridging all native ETH cross-chain, where amountIn is the full balance and gas must be reserved. Only applies to native tokens. |
slippageBps | number | No | Slippage tolerance in basis points (100 = 1%). Default is 300 (3%). Max 8000 (80%). |
Result Schema
| Field | Type | Required | Description |
|---|---|---|---|
status | string | Yes | Status of the swap operation |
srcTransactionHash | string | No | Transaction hash on the source chain |
dstTransactionHash | string | No | Transaction hash on the destination chain (for cross-chain swaps) |
amountIn | string | No | Input amount that was swapped (actual amount sold, useful in EXACT_OUTPUT mode). |
amountOut | string | No | Output amount received |
srcChainId | number | No | Source chain ID |
dstChainId | number | No | Destination chain ID |
Examples
json{ "type": "relay-swap", "payload": { "tokenIn": "ETH", "tokenOut": "ETH", "srcChainId": 8453, "dstChainId": 8453 }, "children": [], "connector": { "type": "wallet", "id": "conn_wallet" }}
bashcurl -X POST "https://api.b3os.org/v1/actions/relay-swap/test" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "inputs": { "tokenIn": "ETH", "tokenOut": "ETH", "srcChainId": 8453, "dstChainId": 8453 }}'
Payload fields can use workflow expressions such as {{$trigger.body.amount}}, {{$nodes.fetch.result.price}}, and {{$props.asset}} when the value should come from a trigger, prior node, or reusable workflow prop.