DeFi and Swap Routing - Enso Developer Documentation

The Route API is Enso’s crosschain automated pathfinding engine that calculates optimal multi-step paths between any two DeFi positions - tokenIn and tokenOut. Whether you’re swapping tokens, entering yield vaults, or moving assets across chains, the Route API handles the complex routing logic automatically.

Would route do the job?
The route API might be the simpler way to route your assets. Before using the bundle API, check if route would work using happypath.

Routing vs Bundling: The Route API excels at single-path operations where you want Enso to determine the optimal route automatically. For custom multi-step workflows where you need precise control over each action, use the Bundle API instead. When to use routing: Token swaps with optimal pricing, vault entries/exits, position migrations between protocols, crosschain transfers, and any scenario where you want automated route optimization rather than manually specifying each step.

Quick Start

The route API produces a gas-optimized, atomic transaction between the two given positions, combining swap, deposit, and redeem operations.

Use the Bundle API if you need other actions Enso supports, such as harvest, borrow, repay.

Sample requests

Token Swap
Vault Entry (Zap)
Crosschain swap
Crosschain Vault Zap

const route = await ensoClient.getRouteData({
  fromAddress: "0x...",
  chainId: 1,
  tokenIn: ["0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"], // ETH
  tokenOut: ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"], // USDC
  amountIn: ["1000000000000000000"], // 1 ETH
  slippage: "50", // 0.5%
  routingStrategy: "delegate"
});

await wallet.sendTransaction(route.tx);

const route = await ensoClient.getRouteData({
  fromAddress: "0x...",
  chainId: 1,
  tokenIn: ["0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"], // ETH
  tokenOut: ["0xa258c4606ca8206d8aa700ce2143d7db854d168c"], // yvWETH
  amountIn: ["1000000000000000000"], // 1 ETH
  slippage: "100", // 1%
  routingStrategy: "delegate"
});

// ETH → WETH → Yearn vault automatically
await wallet.sendTransaction(route.tx);

const route = await ensoClient.getRouteData({
  fromAddress: "0x...",
  chainId: 1, // Ethereum
  destinationChainId: 8453, // Base
  tokenIn: ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"], // USDC Ethereum
  tokenOut: ["0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"], // USDC Base
  amountIn: ["1000000000"], // 1,000 USDC
  slippage: "300", // 3% (higher for crosschain)
  routingStrategy: "delegate"
});

// Bridge USDC from Ethereum to Base
await wallet.sendTransaction(route.tx);

const route = await ensoClient.getRouteData({
  fromAddress: "0x...",
  chainId: 1, // Ethereum
  destinationChainId: 8453, // Base
  tokenIn: ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"], // USDC Ethereum
  tokenOut: ["0x04C0599Ae5A44757c0af6F9eC3b93da8976c150A"], // weETH vault on Base
  amountIn: ["1000000000"], // 1,000 USDC
  slippage: "500", // 5% (complex operation)
  routingStrategy: "delegate"
});

// Bridge + vault entry in one transaction
await wallet.sendTransaction(route.tx);

See complete examples with full setup and explanations →

Core Concepts

Input/Output Model

Specify any tokenIn and tokenOut - ERC20 tokens, LP tokens, vault shares, or yield positions. The Route API automatically finds the optimal path between any two DeFi positions across protocols and chains.

Response

Response contains a complete transaction object ready to sign (tx), amountOut (expected output), gas (estimated), and route (optimized path taken).

Slippage Control

Set slippage in basis points: "50" = 0.5%, "300" = 3%. Higher slippage for complex routes. Cannot use both slippage and minAmountOut - choose one protection method.

Crosschain Operations

Add destinationChainId for crosschain routes. API automatically selects optimal bridges and calculates fees.

Response Structure

Use these fields to build the quote review screen:

Field	What it means	Show it as
`tx`	Complete transaction object ready for submission. Contains the correct `to`, `data`, `value`, and gas fields.	The transaction your wallet signs. Submit it as-is.
`amountOut`	Simulated output amount from the selected route.	Expected output or estimated received amount.
`minAmountOut`	Slippage-protected minimum output when available.	Minimum received amount.
`gas`	Estimated gas usage from simulation.	Network cost estimate and transaction gas value.
`priceImpact`	Estimated price impact for the route when available.	Price impact warning or route quality indicator.
`route`	The optimization path Enso constructed.	Route details, protocols, or path disclosure.

Always use the complete tx object returned by the API, and use the gas value for your transaction.

The to address varies based on routing strategy, and other fields like value and data are precisely calculated for your specific route.
The gas value estimate comes from actual simulation and helps prevent out-of-gas transaction failures.

Examples

The following examples progress from simple token swaps to complex crosschain vault interactions. Each example builds on concepts from previous ones, demonstrating how the Route API handles increasingly sophisticated DeFi operations automatically.

0. Install & Authenticate

You can interact with the API using Enso SDK or directly via a REST API. You can explore Enso through API Sandbox. To install the SDK run the following command:

npm i @ensofinance/sdk
pnpm i @ensofinance/sdk
yarn add @ensofinance/sdk

To use the API, authenticate using the API key.

1. Simple Token Swap

Start with the most basic routing operation: swapping ETH for USDC on Ethereum mainnet.

SDK

import { EnsoClient } from '@ensofinance/sdk';

const ensoClient = new EnsoClient({
  apiKey: 'your-api-key-here'
});

const fromAddress = "0xd8da6bf26964af9d7eed9e03e53415d37aa96045";
const receiver = "0xd8da6bf26964af9d7eed9e03e53415d37aa96045";
const spender = "0xd8da6bf26964af9d7eed9e03e53415d37aa96045";
// ETH → USDC swap with 0.5% slippage

const swapRoute = await ensoClient.getRouteData({
  fromAddress,
  receiver,
  spender,
  chainId: 1,
  amountIn: ["1000000000000000000"], // 1 ETH
  tokenIn: ["0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"], // ETH
  tokenOut: ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"], // USDC
  slippage: "50", // 0.5%
  routingStrategy: "delegate"
});
console.log('Expected USDC output:', swapRoute.amountOut);
console.log('Estimated gas:', swapRoute.gas);
console.log('Swap route complexity:', swapRoute.route.length, 'steps');
// Use route.tx to execute the transaction
const txHash = await wallet.sendTransaction(swapRoute.tx);

2. Zap into Vault

Enter a Yearn vault directly from ETH, automatically handling any intermediate swaps and vault deposits.

SDK

// ETH → yvWETH (Yearn WETH vault) with 1% slippage
const vaultEntry = await ensoClient.getRouteData({
  fromAddress,
  receiver,
  spender, 
  chainId: 1,
  amountIn: ["1000000000000000000"], // 1 ETH
  tokenIn: ["0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"], // ETH
  tokenOut: ["0xa258c4606ca8206d8aa700ce2143d7db854d168c"], // yvWETH
  slippage: "100", // 1%
  routingStrategy: "delegate"
});
console.log('yvWETH shares received:', vaultEntry.amountOut);
console.log('Route complexity:', vaultEntry.route.length, 'steps');
// Route typically: ETH → WETH → deposit to Yearn vault

What’s happening: The router automatically wraps ETH to WETH, then deposits into the Yearn vault. The amountOut represents vault shares, not underlying tokens.

3. Vault Migration

Move from one yield protocol to another - exit Yearn vault and enter Aave lending position.

SDK

// yvWETH → aWETH (migrate from Yearn to Aave)
const migration = await ensoClient.getRouteData({
  fromAddress,
  receiver,
  spender,
  chainId: 1, 
  amountIn: ["1000000000000000000"], // 1 yvWETH
  tokenIn: ["0xa258c4606ca8206d8aa700ce2143d7db854d168c"], // yvWETH
  tokenOut: ["0x4d5F47FA6A74757f35C14fD3a6Ef8E3C9BC514E8"], // aWETH
  slippage: "100", // 1%
  routingStrategy: "delegate"
});
console.log('aWETH tokens received:', migration.amountOut);
console.log('Migration complexity:', migration.route.length, 'steps');
// Route: yvWETH → withdraw to WETH → deposit to Aave → receive aWETH

Complex routing: This involves exiting one protocol (Yearn) and entering another (Aave). The route array will show multiple steps including withdrawal, potential swaps, and final deposit.

4. Crosschain Transfer

Move assets between blockchains using Enso’s integrated bridge routing.

SDK

// USDC from Ethereum → USDC.e on Plume Network
const crossChain = await ensoClient.getRouteData({
  fromAddress,
  receiver,
  spender,
  chainId: 1, // Ethereum
  destinationChainId: 98866, // Plume Network
  amountIn: ["1000000000"], // 1,000 USDC
  tokenIn: ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"], // USDC on Ethereum
  tokenOut: ["0x78adD880A697070c1e765Ac44D65323a0DcCE913"], // USDC.e on Plume
  slippage: "300", // 3% (higher for crosschain)
  routingStrategy: "delegate"
});
console.log('USDC.e on Plume:', crossChain.amountOut);
console.log('Bridge fee:', crossChain.feeAmount);
console.log('Crosschain complexity:', crossChain.route.length, 'steps');

Crosschain considerations: Higher slippage accounts for bridge fees and potential price differences. The feeAmount shows bridge costs, and route reveals pre- and post- bridging steps.

5. Crosschain Vault Zapping

The most complex example: bridge assets and enter a vault on the destination chain in one transaction.

SDK

// USDC Ethereum → myPUSD vault on Plume (crosschain vault zap)
const crossChainVault = await ensoClient.getRouteData({
  fromAddress, 
  receiver,
  spender,
  chainId: 1, // Ethereum
  destinationChainId: 98866, // Plume Network
  amountIn: ["2000000000"], // 2,000 USDC
  tokenIn: ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"], // USDC on Ethereum
  tokenOut: ["0xAf5aEAb2248415716569Be5d24FbE10b16590D6c"], // myPUSD vault on Plume
  slippage: "500", // 5% (complex crosschain + vault operation)
  routingStrategy: "delegate"
});
console.log('myPUSD vault shares:', crossChainVault.amountOut);
console.log('Total route steps:', crossChainVault.route.length);
console.log('Estimated gas:', crossChainVault.gas);

Maximum complexity: This combines crosschain bridging with vault interaction.

Route vs Bundle Output

Route returns a single optimized path from the requested input position to the requested output position. The route array explains the actions Enso selected, while tx, amountOut, and gas are the execution fields your application should display and submit. Bundle returns a transaction built from the explicit actions you provide. When bundled actions include routing, the response can also include route-style information for those routed segments, giving users and reviewers more transparency into how the final transaction was constructed. Use Route when the product can express the desired outcome as tokenIn -> tokenOut. Use Bundle when the product must control the exact sequence of actions, such as checking a bridged balance, harvesting rewards, borrowing, repaying, or depositing through a protocol-specific path.

When to Use Other APIs

Bundle API: When you need custom multi-step logic or want to orchestrate specific actions in sequence, or you need actions beyond swap, deposit and redeem the route API uses
Nontokenized Positions: For lending positions that don’t issue tokens (like Aave debt positions)
Approval Endpoint: Managing token permissions when using "router" strategy

Supporting APIs

Tokens API: Discover available tokens and their addresses across chains
Prices API: Get current token valuations for your UI
Networks API: List supported chains and their details

Updated

​Quick Start

​Sample requests

​Core Concepts

Input/Output Model

Response

Slippage Control

Crosschain Operations

​Response Structure

​Examples

​0. Install & Authenticate

​1. Simple Token Swap

​2. Zap into Vault

​3. Vault Migration

​4. Crosschain Transfer

​5. Crosschain Vault Zapping

​Route vs Bundle Output

​Related APIs & Next Steps

​When to Use Other APIs

​Supporting APIs

Quick Start

Sample requests

Core Concepts

Response Structure

Examples

0. Install & Authenticate

1. Simple Token Swap

2. Zap into Vault

3. Vault Migration

4. Crosschain Transfer

5. Crosschain Vault Zapping

Route vs Bundle Output

Related APIs & Next Steps

When to Use Other APIs

Supporting APIs