Skip to main content
Rainbow provides seamless token swapping within and across blockchains, powered by aggregated DEX liquidity and optimized routing.

​
Swap Types

Rainbow supports two main swap types:

​
Same-Chain Swaps

Same-Chain Swaps exchange tokens on the same blockchain network.
Features:
  • Fast execution: Single transaction
  • Lower cost: Only one network’s gas fees
  • Instant settlement: Immediate token receipt
  • Wide token support: Thousands of tokens
Example: ETH → USDC on Ethereum mainnet

​
Cross-Chain Swaps (Bridging)

Cross-Chain Swaps move tokens between different blockchain networks.
Features:
  • Multi-step process: Bridge + swap if needed
  • Higher cost: Gas on multiple networks
  • Longer time: Minutes to hours
  • Network flexibility: Access tokens on any chain
Example: USDC on Ethereum → USDC on Polygon 
// From src/__swaps__/types/swap.ts
const isCrosschainSwap = inputAsset.chainId !== outputAsset.chainId;

const type = isCrosschainSwap ? 'crosschainSwap' : 'swap';

​
Swap Architecture

Rainbow uses a sophisticated swap system with shared values and reactive state: 
// From src/__swaps__/screens/Swap/providers/swap-provider.tsx
interface SwapContextType {
  // Asset selection
  internalSelectedInputAsset: SharedValue<ExtendedAnimatedAssetWithColors | null>;
  internalSelectedOutputAsset: SharedValue<ExtendedAnimatedAssetWithColors | null>;
  
  // Quote data
  quote: SharedValue<Quote | CrosschainQuote | QuoteError | null>;
  isFetching: SharedValue<boolean>;
  isQuoteStale: SharedValue<number>;
  
  // User inputs
  lastTypedInput: SharedValue<InputKeys>;
  sliderXPosition: SharedValue<number>;
  
  // Actions
  executeSwap: () => void;
  setAsset: (params) => void;
}

​
Quote Types

// Same-chain quote
interface Quote {
  sellAmount: string;           // Input amount (wei)
  buyAmount: string;            // Output amount (wei)
  sellTokenAsset: Asset;        // Input token details
  buyTokenAsset: Asset;         // Output token details
  allowanceTarget: string;      // Approval contract
  to: string;                   // Swap contract
  data: string;                 // Transaction data
  value: string;                // ETH value
  gas: string;                  // Estimated gas
  gasPrice?: string;            // Gas price
}

// Cross-chain quote
interface CrosschainQuote extends Quote {
  swapType: SwapType.crossChain;
  routes: Array<{
    bridgeRoute: BridgeRoute;
    recipient?: string;
    userTxs?: Transaction[];
    serviceTime?: number;       // Estimated time (seconds)
  }>;
}

​
User Swap Flow

1

Select Input Token

Choose token to swap from:
  • Tap input asset selector
  • Search or browse tokens
  • Shows your balance
  • Filter by chain
2

Enter Amount

Specify swap amount:
  • Type amount directly
  • Use percentage slider (25%, 50%, 75%, 100%)
  • See USD value live
  • Validate sufficient balance
3

Select Output Token

Choose token to receive:
  • Tap output asset selector
  • Search tokens on any chain
  • See popular suggestions
  • Rainbow suggests bridged version if cross-chain
4

Review Quote

Rainbow fetches best quote:
  • Multiple DEX aggregators queried
  • Best rate automatically selected
  • Shows exchange rate
  • Displays estimated gas
  • Indicates price impact
5

Adjust Settings (Optional)

Customize swap parameters:
  • Slippage tolerance
  • Gas speed (slow/normal/fast/urgent)
  • MEV protection
  • Swap source preference
6

Execute Swap

Complete the swap:
  • Tap and hold swap button
  • Approve token (if first time)
  • Sign swap transaction
  • Track in activity feed
7

Receive Tokens

Tokens arrive in wallet:
  • Same-chain: Immediately after confirmation
  • Cross-chain: After bridge completes (mins-hours)
  • Notification on completion

​
Swap Settings

Customizable swap parameters:

​
Slippage Tolerance

// From src/__swaps__/utils/swaps.ts
const DEFAULT_SLIPPAGE_BIPS = 500; // 5%

const getDefaultSlippage = (
  chainId: ChainId,
  slippageConfig: RainbowConfig['default_slippage_bips_chainId']
) => {
  const amount = +(
    slippageConfig[chainId] ||
    DEFAULT_SLIPPAGE_BIPS_CHAINID[chainId] ||
    DEFAULT_SLIPPAGE_BIPS
  );
  return slippageInBipsToString(amount); // "5.0"
};
Slippage controls:
  • How much price can change: Before transaction fails
  • Basis points: 100 bips = 1%
  • Default: 5% (500 bips) for most swaps
  • Custom: Set your own tolerance
  • Higher = more likely to succeed, worse price
  • Lower = better price, more likely to fail
For volatile or low-liquidity tokens, you may need to increase slippage to 10-15% for swaps to succeed.

​
Gas Speed

// From src/__swaps__/types/gas.ts
enum GasSpeed {
  URGENT = 'urgent',   // Fastest, highest cost
  FAST = 'fast',       // Fast, higher cost
  NORMAL = 'normal',   // Standard, balanced
  CUSTOM = 'custom',   // User-defined
}

interface GasFeeParams {
  maxBaseFee: GasFeeParam;
  maxPriorityFeePerGas: GasFeeParam;
  estimatedTime: { amount: number; display: string };
  gasFee: { amount: string; display: string };
}
Gas options:
  • Normal: Default, usually confirms in 1-2 minutes
  • Fast: Priority, confirms in less than 1 minute
  • Urgent: Maximum priority, next block
  • Custom: Set your own gas price and limit

​
Swap Source

Choose which aggregators to use:
  • Auto (default): Rainbow selects best
  • Specific DEX: Force use of particular aggregator
  • Rainbow Swap: Rainbow’s own routing

​
Quote Fetching

Quotes are fetched reactively: 
// Automatic quote fetching when inputs change
const quote = useReactiveQuote({
  inputAsset,
  outputAsset,
  inputAmount,
  outputAmount,
  lastTypedInput,
});
Quote updates when:
  • Input/output asset changes
  • Amount changes
  • Slippage changes
  • Gas settings change
  • Every 12 seconds (automatic refresh)
See Quote Fetching for detailed quote mechanism.

​
Gas Estimation

Gas estimated before swap: 
// From src/__swaps__/screens/Swap/hooks/useSwapEstimatedGasLimit.ts
const estimatedGasLimit = useSwapEstimatedGasLimit({
  chainId,
  quote,
  assetToSell,
});

// Different estimates for different swap types
const gasLimit = await (
  quote.swapType === SwapType.crossChain
    ? estimateUnlockAndCrosschainSwap({ chainId, quote })
    : estimateUnlockAndSwap({ chainId, quote })
);
Gas estimation includes:
  • Token approval (if needed)
  • Swap execution
  • Cross-chain bridge (if applicable)
  • Safety margin (10%)
See Gas Estimation for details.

​
Price Impact

Shows how swap affects market price:
  • Less than 1%: Low impact, good liquidity
  • 1-3%: Medium impact, acceptable
  • 3-5%: High impact, proceed with caution
  • Greater than 5%: Very high impact, warning shown
const priceImpact = calculatePriceImpact(
  inputAmount,
  outputAmount,
  marketPrice
);

if (priceImpact > 5) {
  showWarning('High price impact! Consider smaller trade.');
}
High price impact means you’re moving the market price significantly. Consider:
  • Trading smaller amounts
  • Splitting into multiple trades
  • Using limit orders instead
  • Checking if there’s enough liquidity

​
Swap Confirmation

Before executing, review:
Verify swap details:
  • Input amount and token
  • Output amount (minimum)
  • Exchange rate
  • USD values

​
Swap Execution

// From src/__swaps__/screens/Swap/providers/swap-provider.tsx
const executeSwap = () => {
  const { inputAsset, outputAsset, quote } = getSwapState();
  
  // Determine swap type
  const type = inputAsset.chainId !== outputAsset.chainId
    ? 'crosschainSwap'
    : 'swap';
  
  // Build swap parameters
  const swapParams: RapSwapActionParameters = {
    sellAmount: quote.sellAmount,
    buyAmount: quote.buyAmount,
    assetToSell: inputAsset,
    assetToBuy: outputAsset,
    quote,
    chainId: inputAsset.chainId,
    requiresApproval: needsApproval(inputAsset, quote),
  };
  
  // Execute via RAP (Rainbow Action Protocol)
  await walletExecuteRap({
    type,
    parameters: swapParams,
  });
  
  // Track analytics
  trackSwapEvent({ type, ...swapParams });
};

​
Approval Process

For ERC-20 tokens (not ETH):
1

Check Allowance

Rainbow checks if approval needed:
  • Query current allowance
  • Compare with swap amount
  • Skip if sufficient allowance
2

Request Approval

If approval needed:
  • First transaction: Token approval
  • User signs approval
  • Wait for confirmation
3

Execute Swap

After approval confirmed:
  • Second transaction: Actual swap
  • User signs swap
  • Tokens swapped
Rainbow requests exact amount approval by default for security. You can enable unlimited approvals in settings if you prefer convenience over security.

​
Swap Status Tracking

Track swap progress:
  • Pending: Transaction submitted to network
  • Confirming: Waiting for block confirmations
  • Bridging: Cross-chain transfer in progress
  • Complete: Tokens received
  • Failed: Transaction reverted or rejected

​
Error Handling

Common swap errors:
Error: Not enough tokens to swapSolutions:
  • Reduce swap amount
  • Account for gas fees
  • Check you have balance on correct chain
Error: Price moved beyond slippage toleranceSolutions:
  • Increase slippage tolerance
  • Wait for less volatility
  • Trade smaller amount
  • Retry swap
Error: Cannot get swap quoteSolutions:
  • Check network connection
  • Verify token exists on chain
  • Try different amount
  • Check if pair has liquidity
Error: Swap transaction revertedSolutions:
  • Check gas settings
  • Increase slippage
  • Verify balances
  • Try again with updated quote

​
Best Practices

1

Check Multiple Quotes

Compare options:
  • Let Rainbow auto-select best
  • Review exchange rate
  • Check gas costs
  • Consider price impact
2

Set Appropriate Slippage

Balance risk and success:
  • 0.5-1% for stable pairs
  • 2-5% for standard tokens
  • 5-15% for volatile/low liquidity
  • Monitor for frontrunning with high slippage
3

Mind the Gas

Optimize costs:
  • Don’t swap amounts smaller than gas cost
  • Use L2s for small swaps
  • Batch operations when possible
  • Wait for lower gas if not urgent
4

Verify Tokens

Ensure correctness:
  • Check token contract address
  • Verify token name and symbol
  • Confirm you’re on right chain
  • Watch for scam tokens

Quote Fetching

How swap quotes are obtained

Gas Estimation

Gas calculation and optimization

Atomic Swaps

Advanced atomic swap features

Assets Overview

Managing your tokens

Build docs developers (and LLMs) love

Get started for freeTalk to us