​
Getting Started with Route API

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.

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 an 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

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);

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

The route response consists of the following fields:

  • tx: Complete transaction object ready for submission. Contains the correct to address, data, value, and gas fields.
  • amountOut: Simulated output amount - display this to users as expected returns. This is calculated through onchain simulation.
  • gas: Estimated gas usage from simulation. Use this value to prevent out-of-gas failures.
  • route: Array showing the optimization path Enso constructed. Shows the DEX(s) Enso selected for optimal pricing.

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, 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.

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. Vault Entry/Zap In

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

// 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.

// 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.

// 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.

// 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.

​
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