Summary

1

Get a Quote

In this step we’ll request a quote that includes all fees, exchange rates, and execution steps required to swap tokens across chains.
2

Execute the Swap

Once we have the quote, we’ll execute the cross-chain swap by submitting transactions and monitoring progress.

Get a Quote

To swap tokens across chains, you need to specify the source and destination chains, currencies, and the amount to swap. Use the quote endpoint to get comprehensive swap quotes that include optimal routing and fee calculations.

Basic Cross-Chain Swap Quote

curl -X POST "https://api.relay.link/quote" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "0x742d35Cc6634C0532925a3b8D9d4DB0a2D7DD5B3",
    "originChainId": 1,
    "destinationChainId": 8453,
    "originCurrency": "eth",
    "destinationCurrency": "usdc",
    "amount": "100000000000000000",
    "tradeType": "EXACT_INPUT"
  }'

Swap Quote Response Structure

The swap response contains detailed information about the exchange rates, fees, and execution steps:
{
  "steps": [
    {
      "id": "deposit",
      "action": "Confirm transaction in your wallet",
      "description": "Depositing funds to the relayer to execute the swap for USDC",
      "kind": "transaction",
      "requestId": "0x92b99e6e1ee1deeb9531b5ad7f87091b3d71254b3176de9e8b5f6c6d0bd3a331",
      "items": [
        {
          "status": "incomplete",
          "data": {
            "from": "0x742d35Cc6634C0532925a3b8D9d4DB0a2D7DD5B3",
            "to": "0xf70da97812cb96acdf810712aa562db8dfa3dbef",
            "data": "0x00fad611",
            "value": "100000000000000000",
            "chainId": 1
          },
          "check": {
            "endpoint": "/intents/status?requestId=0x92b99e6e1ee1deeb9531b5ad7f87091b3d71254b3176de9e8b5f6c6d0bd3a331",
            "method": "GET"
          }
        }
      ]
    }
  ],
  "fees": {
    "gas": {
      "currency": {
        "chainId": 1,
        "address": "0x0000000000000000000000000000000000000000",
        "symbol": "ETH",
        "name": "Ethereum",
        "decimals": 18
      },
      "amount": "21000000000000000",
      "amountFormatted": "0.021",
      "amountUsd": "84.21"
    },
    "relayer": {
      "currency": {
        "chainId": 8453,
        "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "symbol": "USDC",
        "name": "USD Coin",
        "decimals": 6
      },
      "amount": "5000000",
      "amountFormatted": "5.0",
      "amountUsd": "5.0"
    }
  },
  "details": {
    "operation": "swap",
    "timeEstimate": 30,
    "currencyIn": {
      "currency": {
        "chainId": 1,
        "address": "0x0000000000000000000000000000000000000000",
        "symbol": "ETH",
        "name": "Ethereum",
        "decimals": 18
      },
      "amount": "100000000000000000",
      "amountFormatted": "0.1",
      "amountUsd": "400.0"
    },
    "currencyOut": {
      "currency": {
        "chainId": 8453,
        "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "symbol": "USDC",
        "name": "USD Coin",
        "decimals": 6
      },
      "amount": "395000000",
      "amountFormatted": "395.0",
      "amountUsd": "395.0"
    },
    "rate": "3950.0",
    "totalImpact": {
      "usd": "-5.0",
      "percent": "-1.25"
    },
    "swapImpact": {
      "usd": "-2.5",
      "percent": "-0.625"
    }
  }
}

Quote Parameters for Swapping

ParameterTypeRequiredDescription
userstringYesAddress that will initiate the swap
originChainIdnumberYesSource chain ID (e.g., 1 for Ethereum)
destinationChainIdnumberYesDestination chain ID (e.g., 8453 for Base)
originCurrencystringYesCurrency contract on source chain (e.g., “0x0000000000000000000000000000000000000000”, “0x833589fcd6edb6e08f4c7c32d4f71b54bda02913”)
destinationCurrencystringYesCurrency contract on destination chain
amountstringYesAmount in wei/smallest unit
tradeTypestringYes”EXACT_INPUT”, “EXACT_OUTPUT”, or “EXPECTED_OUTPUT”
recipientstringNoRecipient address (defaults to user)
slippageTolerancestringNoSlippage in basis points (e.g., “50” for 0.5%)
useExternalLiquiditybooleanNoUse canonical+ bridging for more liquidity
referrerstringNoIdentifier that can be used to monitor transactions from a specific source.
refundTostringNoAddress to send the refund to in the case of failure, if not specified the user address is used
topupGasbooleanNoIf set, the destination fill will include a gas topup to the recipient (only supported for EVM chains if the requested currency is not the gas currency on the destination chain)
topupGasAmountstringNoThe destination gas topup amount in USD decimal format, e.g 100000 = $1. topupGas is required to be enabled. Defaults to 2000000 ($2)

Trade Types Explained

Trade TypeDescriptionUse Case
EXACT_INPUTSpecify exact input amount, get estimated output”I want to swap exactly 0.1 ETH”
EXACT_OUTPUTSpecify exact output amount, get required input”I want to receive at least 100 USDC or more”
EXPECTED_OUTPUTSpecify expected output with slippage protection”I expect ~100 USDC with slippage tolerance”

Execute the Swap

After receiving a swap 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 Swap Status

Track your cross-chain swap progress using the status endpoint:
curl "https://api.relay.link/intents/status/v2?requestId=0x92b99e6e1ee1deeb9531b5ad7f87091b3d71254b3176de9e8b5f6c6d0bd3a331"

Status Values

StatusDescription
waitingDeposit tx for the request is yet to be indexed
pendingDeposit tx was indexed, now the fill is pending
successRelay completed successfully
failureRelay failed
refundFunds were refunded due to failure

Advanced Features

App Fees

You can include app fees in your swap requests to monetize your integration:
{
  "user": "0x742d35Cc6634C0532925a3b8D9d4DB0a2D7DD5B3",
  "originChainId": 1,
  "destinationChainId": 8453,
  "originCurrency": "eth",
  "destinationCurrency": "usdc",
  "amount": "100000000000000000",
  "tradeType": "EXACT_INPUT",
  "appFees": [
    {
      "recipient": "0xYourFeeRecipient",
      "fee": "25"
    }
  ]
}

Custom Slippage

Control slippage tolerance for your swaps:
{
  "user": "0x742d35Cc6634C0532925a3b8D9d4DB0a2D7DD5B3",
  "originChainId": 1,
  "destinationChainId": 8453,
  "originCurrency": "eth",
  "destinationCurrency": "usdc",
  "amount": "100000000000000000",
  "tradeType": "EXACT_INPUT",
  "slippageTolerance": "100"
}

Preflight Checklist

Currency support - Verify both currencies are supported on their respective chains Balance validation - Ensure user has sufficient balance for swap amount + fees Price impact check - Analyze swap impact and warn users of high slippage Slippage tolerance - Set appropriate slippage for market conditions Progress monitoring - Track swap status and provide user feedback