Bundle API - Enso Developer Documentation

The Bundle API builds one transaction from an ordered array of actions selected by your product. Use it for custom sequencing, dynamic outputs, checks, fees, flashloans, or protocol actions that do not fit a single Route API request.

If Enso should choose the entire path into one destination, start with the Route API. See Route API vs Bundle API before building a custom sequence.

Actions executed in one same-chain transaction succeed or revert together. Cross-chain delivery is different: the source transaction completes first, then the callback executes on the destination chain. A destination callback failure cannot revert a finalized source-chain bridge.

Before you start

Create and verify an API key.
Choose a supported chain, protocol, and public action.
Use the Bundle Actions Reference for action inputs and outputs.
Use supported actions and the per-protocol action endpoint for current protocol availability.

Request anatomy

POST /api/v1/shortcuts/bundle?chainId=1&fromAddress=0x...&routingStrategy=router
Authorization: Bearer $ENSO_API_KEY
Content-Type: application/json

The request body is the action array directly:

[
  {
    "protocol": "enso",
    "action": "route",
    "args": {
      "tokenIn": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
      "tokenOut": "0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84",
      "amountIn": "100000000000",
      "slippage": "300"
    }
  }
]

Do not wrap the array in { "bundle": [...] }. Wallet and execution settings belong in query parameters for REST, or in the first argument to getBundleData in the SDK.

Request options

Field	Required	Description
`chainId`	Yes	Source-chain ID.
`fromAddress`	Yes	Wallet that submits the returned transaction.
`routingStrategy`	No	Execution client strategy.
`executionMode`	No	Quote execution mode.
`receiver`	No	Default recipient for final outputs.
`spender`	No	Account supplying input assets when supported by the selected strategy.
`refundReceiver`	No	Recipient for dust or applicable bridge refunds.
`ignoreAggregators`	No	Swap aggregators to exclude globally.
`skipQuote`	No	Skip quote-dependent output and gas fields.
`referralCode`	No	Referral code included in the on-chain event.

Action structure

Every action has three fields:

{
  protocol: "enso",
  action: "route",
  args: {
    tokenIn: "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
    tokenOut: "0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84",
    amountIn: "100000000000",
  },
}

protocol selects the Enso meta-action or protocol integration.
action selects a public action supported by that protocol.
args contains the action-specific inputs.

Protocol action inputs are not universal. Query the current per-protocol action metadata instead of assuming every deposit, redeem, or swap accepts the same fields.

Amounts and native assets

Use decimal strings in the token’s smallest base unit. Do not use JavaScript numbers for token amounts.

"1000000" is 1 USDC when the token has 6 decimals.
"1000000000000000000" is 1 ETH or one 18-decimal token.
Use 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee for the native asset.

When native value is involved, send the returned tx.value exactly as provided.

Chain action outputs

A later action can consume an earlier action’s output:

{ useOutputOfCallAt: 0 }

If the producer returns an array, select an item explicitly:

{ useOutputOfCallAt: 0, index: 1 }

References are zero-based and must point to an earlier output. Array outputs require index. Some checks do not expose a normal consumable output; consult the action output table before chaining them.

Receivers and intermediate assets

The query-level receiver is the default recipient for final outputs. An action-level receiver overrides recipient behavior for that action when supported. refundReceiver is for dust or applicable cross-chain refunds. Do not send every intermediate output to the user. Assets consumed by later actions must remain with the executing account until the sequence completes.

Example: route into a deposit

This source-backed example routes native ETH into rETH and deposits the route output into Aave. The deposit consumes action 0 dynamically.

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

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

const result = await client.getBundleData(
  {
    chainId: 1,
    fromAddress: "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
    routingStrategy: "router",
  },
  [
    {
      protocol: "enso",
      action: "route",
      args: {
        tokenIn: "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
        tokenOut: "0xae78736Cd615f374D3085123A210448E74Fc6393",
        amountIn: "10000000000000000",
        slippage: "300",
      },
    },
    {
      protocol: "aave-v3",
      action: "deposit",
      args: {
        primaryAddress: "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
        tokenIn: "0xae78736Cd615f374D3085123A210448E74Fc6393",
        tokenOut: "0xCc9EE9483f662091a1de4795249E24aC0aC2630f",
        amountIn: { useOutputOfCallAt: 0 },
      },
    },
  ],
);

Equivalent REST request:

curl --fail --silent --show-error -X POST \
  'https://api.enso.build/api/v1/shortcuts/bundle?chainId=1&fromAddress=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&routingStrategy=router' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ENSO_API_KEY" \
  -d '[
    {
      "protocol": "enso",
      "action": "route",
      "args": {
        "tokenIn": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
        "tokenOut": "0xae78736Cd615f374D3085123A210448E74Fc6393",
        "amountIn": "10000000000000000",
        "slippage": "300"
      }
    },
    {
      "protocol": "aave-v3",
      "action": "deposit",
      "args": {
        "primaryAddress": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
        "tokenIn": "0xae78736Cd615f374D3085123A210448E74Fc6393",
        "tokenOut": "0xCc9EE9483f662091a1de4795249E24aC0aC2630f",
        "amountIn": { "useOutputOfCallAt": 0 }
      }
    }
  ]' | jq

Example: consume an array output

split returns one output per tokenOut. The following CLMM deposit selects both outputs explicitly.

const result = await client.getBundleData(
  {
    chainId: 42161,
    fromAddress: "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
    routingStrategy: "router",
  },
  [
    {
      protocol: "enso",
      action: "split",
      args: {
        tokenIn: "0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9",
        tokenOut: [
          "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
          "0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9",
        ],
        amountIn: "100000000",
      },
    },
    {
      protocol: "sushiswap-v3",
      action: "depositclmm",
      args: {
        tokenOut: "0xf0cbce1942a68beb3d1b73f0dd86c8dcc363ef49",
        ticks: [-887271, 887271],
        tokenIn: [
          "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
          "0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9",
        ],
        poolFee: "100",
        amountIn: [
          { useOutputOfCallAt: 0, index: 0 },
          { useOutputOfCallAt: 0, index: 1 },
        ],
      },
    },
  ],
);

For CLMM flows that require explicit protection for the internal swaps, slippage checks can sit between split and depositclmm. They reference the split outputs; they do not need to appear after the final deposit.

Example: route fee

Route fees are deducted from the corresponding input amounts before routing. fee is an array aligned with amountIn; "100" is 1%.

{
  protocol: "enso",
  action: "route",
  args: {
    tokenIn: "0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84",
    tokenOut: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    amountIn: { useOutputOfCallAt: 0 },
    fee: ["100"],
    feeReceiver: "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
    slippage: "1000",
  },
}

For a standalone fee step that returns the net amount, use the public enso:fee action.

Example: bridge callback

A bridge callback executes later on the destination chain. For supported callback bridges, the callback must begin with enso:balance; callback output references are local to the callback array.

const result = await client.getBundleData(
  {
    chainId: 10,
    fromAddress: "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
    receiver: "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
    routingStrategy: "router",
  },
  [
    {
      protocol: "stargate",
      action: "bridge",
      args: {
        primaryAddress: "0xe8cdf27acd73a434d661c84887215f7598e7d0d3",
        destinationChainId: 130,
        tokenIn: "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
        amountIn: "5000000000000000000",
        receiver: "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
        callback: [
          {
            protocol: "enso",
            action: "balance",
            args: {
              token: "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
            },
          },
          {
            protocol: "enso",
            action: "route",
            args: {
              tokenIn: "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
              tokenOut: "0x078d782b760474a361dda0af3839290b0ef57ad6",
              amountIn: { useOutputOfCallAt: 0 },
              slippage: "100",
            },
          },
        ],
      },
    },
  ],
);

After submitting the source transaction, monitor Bridge Status. Bridge-provider callback capabilities and refund behavior differ; see Crosschain Routing.

Execute the response

Building a bundle does not submit it.

Inspect approvals. Submit each required approval transaction before the bundle transaction.
Submit tx unchanged, including to, data, and value.
Do not submit an expired quote; respect validUntil when present.
For cross-chain bundles, monitor bridge and destination status after source confirmation.

Response fields

Field	Description
`tx`	Signer-ready transaction.
`approvals`	External approval transactions required before `tx`.
`createdAt`	Block number used to build the transaction.
`bundle`	Normalized action sequence returned by the backend. It can include injected fee actions.
`route`	Expanded route hops selected for route actions.
`amountsOut`	Expected final outputs by token.
`minAmountsOut`	Minimum protected outputs by token.
`feeAmount`	Fees by token.
`gas`	Estimated gas when quoting is enabled.
`priceImpact`	Estimated price impact when available.
`bridgingEstimates`	Cross-chain timing and fee estimates when applicable.
`validUntil`	Quote expiry timestamp when applicable.
`userOp`	ERC-4337 user operation for supported execution flows.

When skipQuote=true, quote-dependent fields such as output amounts and gas may be absent.

Limits and common errors

Constraint	Current limit or behavior
Top-level actions	50 maximum
Total actions including callbacks	100 maximum
Actions in each callback	10 maximum
Callback nesting	5 callback levels beneath a top-level action
Output references	Resolved against outputs already built; missing or future references fail during bundle construction. Array outputs require `index`.
Static `amountIn`	Positive base-unit integer string; placeholders and output references are also supported. Other amount fields are action-specific.
Callback order	CCIP, Stargate, and Relay callbacks require `enso:balance` first. CCTP callbacks support a narrower documented sequence.
Simulation failure	Error detail depends on the failing action and simulation path; detailed simulation context is not guaranteed.

See the FAQ and Bundle Actions Reference for action-specific constraints.

Next steps

Bundle Actions Reference

Review public action inputs, outputs, fees, checks, and composition rules.

API Reference

Inspect the exact Bundle endpoint request and response schema.

Routing Strategies

Understand execution-account and approval behavior.

Crosschain Routing

Choose bridge protocols and monitor asynchronous destination execution.

​Before you start

​Request anatomy

​Request options

​Action structure

​Amounts and native assets

​Chain action outputs

​Receivers and intermediate assets

​Example: route into a deposit

​Example: consume an array output

​Example: route fee

​Example: bridge callback

​Execute the response

​Response fields

​Limits and common errors

​Next steps

Bundle Actions Reference

API Reference

Routing Strategies

Crosschain Routing

Before you start

Request anatomy

Request options

Action structure

Amounts and native assets

Chain action outputs

Receivers and intermediate assets

Example: route into a deposit

Example: consume an array output

Example: route fee

Example: bridge callback

Execute the response

Response fields

Limits and common errors

Next steps