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

# DeFi and Swap Routing

> Find optimal paths for crosschain entering/exiting DeFi positions or swapping ERC20 tokens.

export const date_0 = "2025-09-12"

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.

<Tip>
  **Would `route` do the job?** <br />
  The `route` API might be the simpler way to route your assets.
  Before using the bundle API, check if `route` would work using [happypath](https://happypath.enso.build).
</Tip>

**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](/api-reference/defi-shortcuts/bundle-a-list-of-actions) 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.

<img src="https://mintcdn.com/enso/nu8qK2z1ysTh8AfC/images/router-dark.webp?fit=max&auto=format&n=nu8qK2z1ysTh8AfC&q=85&s=00a544fef9c83ad3437af35b7b7ecd3e" className="hidden dark:block" width="800" height="528" data-path="images/router-dark.webp" />

<img src="https://mintcdn.com/enso/nu8qK2z1ysTh8AfC/images/router-light.webp?fit=max&auto=format&n=nu8qK2z1ysTh8AfC&q=85&s=39efe7210d30e7b623f30c0ede379b38" className="dark:hidden" width="800" height="528" data-path="images/router-light.webp" />

## Quick Start

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

<Note>
  Use the [Bundle API](/pages/build/get-started/bundling-actions) if you need other [actions Enso supports](/pages/build/reference/actions), such as `harvest`, `borrow`, `repay`.
</Note>

## Sample requests

<Tabs>
  <Tab title="Token Swap">
    ```typescript theme={null}
    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);
    ```
  </Tab>

  <Tab title="Vault Entry (Zap)">
    ```typescript theme={null}
    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);
    ```
  </Tab>

  <Tab title="Crosschain swap">
    ```typescript theme={null}
    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);
    ```
  </Tab>

  <Tab title="Crosschain Vault Zap">
    ```typescript theme={null}
    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);
    ```
  </Tab>
</Tabs>

<div className="text-center mt-4">
  <a href="#1-simple-token-swap" className="text-blue-600 hover:underline">
    See complete examples with full setup and explanations →
  </a>
</div>

## Core Concepts

<CardGroup cols={2}>
  <Card title="Input/Output Model" icon="right-left-large">
    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.
  </Card>

  <Card title="Response" icon="code" cta="See Examples" href="#examples">
    Response contains a complete transaction object ready to sign (`tx`), `amountOut` (expected output), `gas` (estimated), and `route` (optimized path taken).
  </Card>

  <Card title="Slippage Control" icon="arrow-trend-down">
    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.
  </Card>

  <Card title="Crosschain Operations" icon="bridge">
    Add `destinationChainId` for crosschain routes. API automatically selects optimal bridges and calculates fees.
  </Card>
</CardGroup>

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

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

## 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](/api-reference/).

To install the SDK run the following command:

```bash theme={null}
npm i @ensofinance/sdk
pnpm i @ensofinance/sdk
yarn add @ensofinance/sdk
```

To use the API, authenticate using the [API key](/pages/build/get-started/authentication).

### 1. Simple Token Swap

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

<CodeGroup dropdown>
  ```typescript SDK theme={null}
  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);
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.enso.build/api/v1/shortcuts/route \
    --header 'Content-Type: application/json' \
    --header "Authorization: Bearer $ENSO_API_KEY" \
    --data '{
      "chainId": 1,
      "fromAddress": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "routingStrategy": "delegate",
      "receiver": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "spender": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "tokenIn": ["0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"],
      "tokenOut": ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"],
      "amountIn": ["1000000000000000000"],
      "slippage": "50"
    }' | jq
  ```
</CodeGroup>

### 2. Zap into Vault

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

<CodeGroup dropdown>
  ```typescript SDK theme={null}
  // 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
  ```

  ```bash cURL theme={null}
  # ETH → yvWETH (Yearn WETH vault) with 1% slippage
  curl --request POST \
    --url https://api.enso.build/api/v1/shortcuts/route \
    --header 'Content-Type: application/json' \
    --header "Authorization: Bearer $ENSO_API_KEY" \
    --data '{
      "chainId": 1,
      "fromAddress": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "routingStrategy": "delegate",
      "receiver": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "spender": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "tokenIn": ["0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"],
      "tokenOut": ["0xa258c4606ca8206d8aa700ce2143d7db854d168c"],
      "amountIn": ["1000000000000000000"],
      "slippage": "100"
    }' | jq
  ```
</CodeGroup>

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

<CodeGroup dropdown>
  ```typescript SDK theme={null}
  // 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
  ```

  ```bash cURL theme={null}
  # Route: yvWETH → withdraw to WETH → deposit to Aave → receive aWETH
  curl --request POST \
    --url https://api.enso.build/api/v1/shortcuts/route \
    --header 'Content-Type: application/json' \
    --header "Authorization: Bearer $ENSO_API_KEY" \
    --data '{
      "chainId": 1,
      "fromAddress": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "routingStrategy": "delegate",
      "receiver": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "spender": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "tokenIn": ["0xa258c4606ca8206d8aa700ce2143d7db854d168c"],
      "tokenOut": ["0x4d5F47FA6A74757f35C14fD3a6Ef8E3C9BC514E8"],
      "amountIn": ["1000000000000000000"],
      "slippage": "100"
    }' | jq
  ```
</CodeGroup>

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

<CodeGroup dropdown>
  ```typescript SDK theme={null}
  // 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');
  ```

  ```bash cURL theme={null}
  # USDC from Ethereum → USDC.e on Plume Network
  curl --request POST \
    --url https://api.enso.build/api/v1/shortcuts/route \
    --header 'Content-Type: application/json' \
    --header "Authorization: Bearer $ENSO_API_KEY" \
    --data '{
      "chainId": 1,
      "destinationChainId": 98866,
      "fromAddress": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "routingStrategy": "delegate",
      "receiver": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "spender": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "tokenIn": ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"],
      "tokenOut": ["0x78adD880A697070c1e765Ac44D65323a0DcCE913"],
      "amountIn": ["1000000000"],
      "slippage": "300"
    }' | jq
  ```
</CodeGroup>

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

<CodeGroup dropdown>
  ```typescript SDK theme={null}
  // 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);

  ```

  ```bash cURL theme={null}
  # USDC Ethereum → myPUSD vault on Plume (crosschain vault zap)
  curl --request POST \
    --url https://api.enso.build/api/v1/shortcuts/route \
    --header 'Content-Type: application/json' \
    --header "Authorization: Bearer $ENSO_API_KEY" \
    --data '{
      "chainId": 1,
      "destinationChainId": 98866,
      "fromAddress": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "routingStrategy": "delegate",
      "receiver": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "spender": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "tokenIn": ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"],
      "tokenOut": ["0xAf5aEAb2248415716569Be5d24FbE10b16590D6c"],
      "amountIn": ["2000000000"],
      "slippage": "500"
    }' | jq
  ```
</CodeGroup>

**Maximum complexity:** This combines crosschain bridging with vault interaction.

## Related APIs & Next Steps

### When to Use Other APIs

* **[Bundle API](/api-reference/defi-shortcuts/bundle-a-list-of-actions)**: 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](/api-reference/defi-shortcuts/routing-to-a-non-tokenized-position)**: For lending positions that don't issue tokens (like Aave debt positions)
* **[Approval Endpoint](/api-reference/defi-shortcuts/approve-enso-contract)**: Managing token permissions when using `"router"` strategy

### Supporting APIs

* **[Tokens API](/api-reference/tokens/tokens)**: Discover available tokens and their addresses across chains
* **[Prices API](/api-reference/tokens/token-price)**: Get current token valuations for your UI
* **[Networks API](/api-reference/integration/networks)**: List supported chains and their details

<div className="text-right text-xs gray-200 font-semibold w-full" style={{marginTop: '0'}}>
  <p style={{
        color: "#b2b2b2"  
    }}>Updated {date_0}</p>
</div>