Skip to main content
Crosschain routing enables complex multichain workflows that execute DeFi operations across multiple blockchains atomically. Unlike simple token transfers, crosschain routing orchestrates sophisticated strategies that span several chains. Both route and bundle API operate in crosschain mode. For custom bundles, use the bridge action to facilitate cross-chain token transfers using Stargate. For example: bridge assets to chains where protocols exist, execute operations such as minting, then optionally bridge results back to your origin chain and deposit them in a yield-bearing position.

​
Quick Start

  • Crosschain Stablecoin Minting
  • Crosschain Swap
Use the GET layerzero/pool API to find the correct pool address and use it as the primaryAddress for stargate.bridge operation.Always start the post-bridging callback with balance action.

  {
    protocol: "stargate",
    action: "bridge",
    args: {
      primaryAddress: rusdEthToBeraPools[0].pool,
      destinationChainId: ETHEREUM_ID,
      ...
      callback: [

        //  Mint e-rUSD using bridged USDC on Ethereum
        {
          protocol: "reservoir",
          action: "deposit",
          args: {...},
        },
        // Bridge newly minted e-rUSD back to Berachain
        {
          protocol: "stargate",
          action: "bridge",
          args: {
            destinationChainId: BERACHAIN_ID,
            ...
            // Callback executes on Berachain after e-rUSD arrives
            callback: [
              // Deposit e-rUSD into Euler vault on Berachain
              {
                protocol: "euler-v2",
                action: "deposit",
                args: {...},
              },
            ],
          },
        },
      ],
    },
  },

​
Core Concepts

Bridging

Crosschain routing uses Stargate and LayerZero for bridging assets.

The bridge action’s parameter primaryAddress must reference an appropriate pool contract, exposed by the layerZero/pool API.

Native Drop

Parent bridge calls calculate gas fees required for all child bridge operations and include these costs in the initial transaction fee using LayerZero’s native drop feature.

Post-Bridge Execution

Callback arrays of Enso Actions execute on the destination chain after bridge completion. All actions within a bundle execute atomically.

​
When to use Route vs Bundle API?

Use Route API for: Limitations: Cannot handle custom post-bridge logic or multi-step protocols interactions Use Bundle API for:
Use the GET layerzero/pool API to find the correct pool address and use it as the primaryAddress for stargate.bridge operation.

​
Examples

​
1. Simple Cross-Chain Swap

Use Route API for basic cross-chain operations with automatic pathfinding.
SDK
// ETH on Ethereum → USDC on Base
const route = await ensoClient.getRouteData({
  fromAddress: "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
  chainId: 1, // Ethereum
  destinationChainId: 8453, // Base
  tokenIn: ["0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"], // ETH
  tokenOut: ["0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"], // USDC Base
  amountIn: ["1000000000000000000"], // 1 ETH
  slippage: "300", // 3%
  routingStrategy: "delegate"
});

​
2. Crosschain Vault Zap

In this example, we’ll bridge ETH from Ethereum to zap it to a Ether.fi weETH vault on Base. Try this route → 
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);

​
3. Cross-Chain Position Minting

Crosschain routing enables you to mint positions on different chains and bridge them back, while signing only once. In this example, we’ll bridge USDC from Berachain to Ethereum, mint e-rUSD using Reservoir protocol, then bridge rUSD back to Berachain. About Reservoir: Reservoir is a stablecoin protocol that mints rUSD (a USD-pegged stablecoin) by accepting USDC as collateral on Ethereum mainnet.
Use the GET layerzero/pool API or client.getLayerZeroPool() from the SDK to find the correct pool address and use it as the primaryAddress for stargate.bridge operation.
What’s happening: This workflow demonstrates a complete round-trip bridge operation - taking USDC from Berachain, minting a stablecoin on Ethereum where the protocol exists, then bringing the newly minted e-rUSD back to the origin chain. Understanding callbacks execution Callbacks execute on the destination chain after the bridge completes, but they’re not separate transactions. The bridge operation includes encoded instructions that execute atomically using Enso’s crosschain execution engine. This means:
  • Atomic Safety: All callback actions execute as a single atomic transaction on the destination chain. If any action fails, the entire callback transaction reverts and bridged tokens are sent to the refundReceiver address. Funds never get stuck in an intermediate state.
  • Gas Management: The initial transaction on the source chain calculates and pays for all destination chain gas costs using LayerZero’s native drop feature. You don’t need to hold native tokens on every destination chain.
  • Output Chaining: Callbacks can reference outputs from previous callback actions using useOutputOfCallAt, enabling complex multi-step workflows that adapt to actual bridged amounts rather than fixed values.
mintOnBeraFromMainnet.ts
// Chain IDs
const BERACHAIN_ID = 80094;
const ETHEREUM_ID = 1;

// Common addresses
const WALLET_ADDRESS = "0x93621DCA56fE26Cdee86e4F6B18E116e9758Ff11"; // User wallet

// Token addresses
const USDC_BERACHAIN = "0x549943e04f40284185054145c6E4e9568C1D3241";
const USDC_ETHEREUM = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48";
const RUSD_ETHEREUM = "0x09D4214C03D01F49544C0448DBE3A27f768F2b34";

// Protocol addresses
const RESERVOIR_MINTING_CONTRACT =
  "0x4809010926aec940b550D34a46A52739f996D75D";

const client = new EnsoClient({
  apiKey: process.env.ENSO_API_KEY || "your-api-key-here",
});

const usdcBeraToEthPools = await client.getLayerZeroPool({
  chainId: BERACHAIN_ID,
  token: USDC_BERACHAIN,
  destinationChainId: ETHEREUM_ID + "",
});

const rusdEthToBeraPools = await client.getLayerZeroPool({
  chainId: ETHEREUM_ID,
  token: RUSD_ETHEREUM,
  destinationChainId: BERACHAIN_ID + "",
});

if (!(usdcBeraToEthPools.length && usdcBeraToEthPools.length)) {
  throw new Error("Required pools not available");
}

const bundle = await client.getBundleData(
  {
    chainId: BERACHAIN_ID,
    fromAddress: WALLET_ADDRESS,
    spender: WALLET_ADDRESS,
    routingStrategy: "router",
    refundReceiver: WALLET_ADDRESS,
  },
  [
    {
      protocol: "stargate",
      action: "bridge",
      args: {
        primaryAddress: usdcBeraToEthPools[0].pool,
        destinationChainId: ETHEREUM_ID,
        tokenIn: USDC_BERACHAIN,
        amountIn: parseUnits("1000", 6).toString(), // 1000 USDC
        receiver: WALLET_ADDRESS,
        callback: [
          // Step 1: Check USDC balance on Ethereum after bridge
          {
            protocol: "enso",
            action: "balance",
            args: {
              token: USDC_ETHEREUM,
            },
          },
          // Step 2: Mint e-rUSD using bridged USDC
          {
            protocol: "reservoir",
            action: "deposit",
            args: {
              primaryAddress: RESERVOIR_MINTING_CONTRACT,
              tokenIn: USDC_ETHEREUM,
              tokenOut: RUSD_ETHEREUM,
              amountIn: { useOutputOfCallAt: 0 }, // Use USDC from balance check
              receiver: WALLET_ADDRESS,
            },
          },
          // Step 3: Bridge newly minted e-rUSD back to Berachain
          {
            protocol: "stargate",
            action: "bridge",
            args: {
              primaryAddress: rusdEthToBeraPools[0].pool,
              destinationChainId: BERACHAIN_ID,
              tokenIn: RUSD_ETHEREUM,
              amountIn: { useOutputOfCallAt: 1 }, // Use e-rUSD from minting
              receiver: WALLET_ADDRESS,
            },
          },
        ],
      },
    },
  ]
);

​
4. Crosschain Yield Strategy

Nested callbacks enable multi-hop workflows, allowing operations that span multiple chains where different protocols exist. In this example, we’ll do an Euler deposit of rUSD tokens minted on a Berachain by using Ethereum Mainnet assets. The user starts with USDC on Berachain and ends with yield-generating vault shares with a single signature.
mintOnBeraDepositOnMainnet.ts
const BERACHAIN_ID = 80094;
  const ETHEREUM_ID = 1;

  // Common addresses
  const WALLET_ADDRESS = "0x93621DCA56fE26Cdee86e4F6B18E116e9758Ff11"; // User wallet

  // Token addresses
  const USDC_BERACHAIN = "0x549943e04f40284185054145c6E4e9568C1D3241";
  const USDC_ETHEREUM = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48";
  const RUSD_ETHEREUM = "0x09D4214C03D01F49544C0448DBE3A27f768F2b34";
  const RUSD_BERACHAIN = "0x09D4214C03D01F49544C0448DBE3A27f768F2b34";

  // Protocol addresses
  const RESERVOIR_MINTING_CONTRACT =
    "0x4809010926aec940b550D34a46A52739f996D75D";
  const EULER_VAULT_E_RUSD_BERACHAIN =
    "0x109D6D1799f62216B4a7b0c6e245844AbD4DD281"; // Euler vault for e-rUSD on Berachain (need actual address)

  const client = new EnsoClient({
    apiKey: process.env.ENSO_API_KEY!,
  });

  const usdcBeraToEthPools = await client.getLayerZeroPool({
    chainId: BERACHAIN_ID,
    token: USDC_BERACHAIN,
    destinationChainId: ETHEREUM_ID + "",
  });

  const rusdEthToBeraPools = await client.getLayerZeroPool({
    chainId: ETHEREUM_ID,
    token: RUSD_ETHEREUM,
    destinationChainId: BERACHAIN_ID + "",
  });

  if (!(usdcBeraToEthPools.length && usdcBeraToEthPools.length)) {
    throw new Error("Required pools not available");
  }

  const bundle = await client.getBundleData(
    {
      chainId: BERACHAIN_ID,
      fromAddress: WALLET_ADDRESS,
      spender: WALLET_ADDRESS,
      routingStrategy: "router",
      refundReceiver: WALLET_ADDRESS,
    },
    [
      {
        protocol: "stargate",
        action: "bridge",
        args: {
          primaryAddress: rusdEthToBeraPools[0].pool,
          destinationChainId: ETHEREUM_ID,
          tokenIn: USDC_BERACHAIN,
          amountIn: parseUnits("1000", 6).toString(), // 1000 USDC
          receiver: WALLET_ADDRESS,
          callback: [
            // Step 1: Check USDC balance on Ethereum after bridge
            {
              protocol: "enso",
              action: "balance",
              args: {
                token: USDC_ETHEREUM,
              },
            },
            // Step 2: Mint e-rUSD using bridged USDC on Ethereum
            {
              protocol: "reservoir",
              action: "deposit",
              args: {
                primaryAddress: RESERVOIR_MINTING_CONTRACT,
                tokenIn: USDC_ETHEREUM,
                tokenOut: RUSD_ETHEREUM,
                amountIn: { useOutputOfCallAt: 0 }, // Use USDC from balance check
                receiver: WALLET_ADDRESS,
              },
            },
            // Step 3: Bridge newly minted e-rUSD back to Berachain
            {
              protocol: "stargate",
              action: "bridge",
              args: {
                primaryAddress: rusdEthToBeraPools[0].pool,
                destinationChainId: BERACHAIN_ID,
                tokenIn: RUSD_ETHEREUM,
                amountIn: { useOutputOfCallAt: 1 }, // Use e-rUSD from minting
                receiver: WALLET_ADDRESS,
                // Callback executes on Berachain after e-rUSD arrives
                callback: [
                  // Step 4: Check e-rUSD balance on Berachain
                  {
                    protocol: "enso",
                    action: "balance",
                    args: {
                      token: RUSD_BERACHAIN,
                    },
                  },
                  // Step 5: Deposit e-rUSD into Euler vault on Berachain
                  {
                    protocol: "euler-v2",
                    action: "deposit",
                    args: {
                      primaryAddress: EULER_VAULT_E_RUSD_BERACHAIN,
                      tokenIn: RUSD_BERACHAIN,
                      tokenOut: EULER_VAULT_E_RUSD_BERACHAIN, // ERC4626 vault token
                      amountIn: { useOutputOfCallAt: 0 }, // Use e-rUSD from balance check
                      receiver: WALLET_ADDRESS,
                    },
                  },
                ],
              },
            },
          ],
        },
      },
    ]
  );

​
Reference

​
Bridge Action Parameters

The [bridge action] has the follwing parameters:
ParameterDescriptionRequired
primaryAddressLayerZero pool contract address for the source chainYes
destinationChainIdTarget blockchain network IDYes
tokenInToken address to bridge from source chainYes
amountInAmount to bridge (with full decimals) or reference to previous action outputYes
receiverAddress to receive bridged tokens on destination chainYes
callbackArray of actions to execute on destination chain after bridgingNo
refundReceiverAddress to receive bridged tokens if callback execution fails on destination chain. If not specified, receiver gets refunds.No

​
Callback Requirements

Critical: All callback sequences must begin with a balance check action to verify the bridged token amount on the destination chain.
  1. First action must be the balance action:
{ protocol: "enso", action: "balance", args: { token: "bridged_token_address" } }`
  1. Reference previous outputs: Use the ouseOutputOfCallAt to chain actions together
{ useOutputOfCallAt: callIndex, index: outVarIndex }
  1. Nested callbacks: Bridge actions within callbacks enable multi-hop workflows

​
Supported Chains and Tokens

Use the GET layerzero/pool API to find the correct pool address and use it as the primaryAddress for stargate.bridge operation.

Updated

⌘I