> ## Documentation Index
> Fetch the complete documentation index at: https://docs.b3os.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Cross-Chain Swap (Relay)

Swap tokens at the best available price via Relay Protocol. The default swap action for buying and selling tokens. Supports EVM and Solana sources, same-chain swaps, cross-chain swaps, and bridging. Configurable slippage.

![Cross-Chain Swap (Relay) logo](https://cdn.b3.fun/b3os-icons/relay.svg)
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 tokens. Supports EVM and Solana sources, same-chain swaps, cross-chain swaps, and bridging. Configurable slippage.

**Review wallet and value movement**

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`, `solana`, `dex`, `swap`, `sell`, `buy`, `token`, `erc20`, `trade`, `bridge`, `cross-chain` |

## Payload Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `srcChainId` | `number` | Yes | Source chain ID \(e.g., 1 for Ethereum, 8453 for Base, or 7565164 for Solana mainnet\). Relay's 792703809 and LI.FI's 1151111081099710 are accepted as Solana mainnet aliases. |
| `tokenIn` | `string` | Yes | Source token address or Solana SPL mint. Use "native" for the source chain's native token \(including SOL\); EVM native-token sentinels are also accepted. |
| `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. Use 7565164 for Solana mainnet \(792703809 and 1151111081099710 are accepted as aliases for that same network\). |
| `tokenOut` | `string` | Yes | Destination token address. Use "native" for the destination chain's native token on any chain, including native SOL on Solana \(0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE and 0x0000000000000000000000000000000000000000 also work on EVM chains\). For other tokens use the chain's address format \(e.g., base58 SPL mint for Solana\). |
| `recipient` | `string` | No | Recipient address for the output tokens. Defaults to sender for same-family swaps. Required when crossing between EVM and Solana. |
| `useMaxTokenInBalance` | `boolean` | No | When true and tokenIn is a native EVM 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 EVM 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\). |
| `amountInFormatted` | `string \| null` | No | Input amount in human-readable units \(amountIn ÷ 10^inputDecimals\), full precision. Null when the input token's decimals are unavailable. Prefer this over amountIn for display. |
| `amountOut` | `string` | No | Output amount received. Receipt-parsed on EVM destinations; on non-EVM destinations \(e.g. Solana\) this is Relay's quoted estimate — actual delivery can be lower within the slippage tolerance. |
| `amountOutFormatted` | `string \| null` | No | Output amount in human-readable units \(amountOut ÷ 10^decimals\), full precision. Null when the output token's decimals are unavailable. Prefer this over amountOut for display — it needs no client-side math. Carries amountOut's caveat: a quoted estimate on non-EVM destinations. |
| `srcChainId` | `number` | No | Source chain ID |
| `dstChainId` | `number` | No | Destination chain ID |
| `tokenInSymbol` | `string \| null` | No | Symbol of the INPUT token that was swapped \(e.g. 'USDC'\). Lets the UI label the source token correctly. |
| `tokenSymbol` | `string \| null` | No | Symbol of the output token received \(e.g., 'JUP'\). Lets the UI label the destination token when on-chain token lookup is unavailable \(e.g., Solana SPL mints\). |
| `decimals` | `number \| null` | No | Decimal places of the output token, used to format the received amount when on-chain token lookup is unavailable. |

## Examples

**Workflow node**

```json
{
  "type": "relay-swap",
  "payload": {
    "tokenIn": "ETH",
    "tokenOut": "ETH",
    "srcChainId": 8453,
    "dstChainId": 8453
  },
  "children": [],
  "connector": {
    "type": "wallet",
    "id": "conn_wallet"
  }
}
```
  **Test with API**

```bash
curl -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
  }
}'
```

**Use expressions for dynamic values**

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.