Cross-Chain Swap (Relay)
Swap tokens at the best available price via Relay Protocol. The default swap action for buying and selling ERC20 tokens. Supports same-chain swaps on any EVM chain, cross-chain swaps, and bridging to Solana. Configurable slippage.
Catalog action EVM Onchain wallet Gas bridge
Swap tokens at the best available price via Relay Protocol. The default swap action for buying and selling ERC20 tokens. Supports same-chain swaps on any EVM chain, cross-chain swaps, 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, sell, buy, token, erc20, trade, bridge, cross-chain, relay |
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.