Skip to main content
BEX allows multi-hop swaps, or “batch swaps”, which can optimize routes across multiple liquidity pools to find the best prices. The BEX Vault contract exposes the batchSwap function to allow multi-hop swaps.

​
Functions

​
batchSwap

function batchSwap(SwapKind kind,
          BatchSwapStep[] swaps,
          IAsset[] assets,
          FundManagement funds,
          int256[] limits,
          uint256 deadline) returns (int256[] assetDeltas)
ParameterTypeDescription
kindSwapKindThe type of swap (GIVEN_IN or GIVEN_OUT)
swapsBatchSwapStep[]Array of steps in the batch swap
assetsIAsset[]Array of tokens used in the batch swap
fundsFundManagementSpecifies token sources and destinations
limitsint256[]Maximum amounts of each asset to be transferred
deadlineuint256UNIX timestamp by which the swap must complete
ReturnsTypeDescription
assetDeltasint256[]Net token balances resulting from the swap

​
queryBatchSwap

function queryBatchSwap(SwapKind kind,
          BatchSwapStep[] swaps,
          IAsset[] assets,
          FundManagement funds)
          returns (int256[] assetDeltas)
ReturnsTypeDescription
assetDeltasint256[]Simulated net token balances resulting from the swap
Use this function off-chain to estimate swap results and calculate appropriate limits.

​
Structs

​
BatchSwapStep

struct BatchSwapStep {
    bytes32 poolId;
    uint256 assetInIndex;
    uint256 assetOutIndex;
    uint256 amount;
    bytes userData;
}
FieldTypeDescription
poolIdbytes32The id of the pool to swap with
assetInIndexuint256The index of the input token within the assets array
assetOutIndexuint256The index of the output token within the assets array
amountuint256The amount to swap, interpretation depends on kind
userDatabytesAdditional data required by the pool for the swap
Important: When amount is set to 0 in a multi-hop swap, BEX will use the full output of the previous step as input.

​
FundManagement

struct FundManagement {
    address sender;
    bool fromInternalBalance;
    address payable recipient;
    bool toInternalBalance;
}
FieldTypeDescription
senderaddressThe address providing tokens for the swap
fromInternalBalanceboolWhether to use tokens from internal balance
recipientaddress payableThe address receiving tokens after the swap
toInternalBalanceboolWhether to send tokens to internal balance
The SwapKind parameter in the batchSwap function determines how swap amounts are interpreted:
  • GIVEN_IN: Specify the exact amount of tokens to swap in. The function calculates and returns the amount of tokens you’ll receive. Example: “Swap exactly 100 USDC for as much ETH as possible.”
  • GIVEN_OUT: Specify the exact amount of tokens to receive. The function calculates and returns the amount of tokens you need to swap in. Example: “Receive exactly 1 ETH, how much USDC do I need to swap?”
The choice between GIVEN_IN and GIVEN_OUT affects how the amount field in the BatchSwapStep struct is interpreted and how swap calculations are performed.

​
Examples

The following examples demonstrate different ways to use batch swaps in BEX. These patterns can help you optimize trading strategies and reduce gas costs by combining multiple operations into single transactions.

​
Multi-hop examples

Multi-hop swaps allow trading between tokens that don’t have direct liquidity pools by routing through intermediate tokens. This can often result in better pricing than direct swaps.

​
Example 1: GIVEN_IN (USDC−>USDC -> HONEY -> $DAI)

In this example, you want to swap 1000 USDCthroughUSDC through HONEY to get $DAI. The swap is executed in two steps:
StepAmountToken InToken OutDescription
01000$USDC$HONEYSwap exact 1000 USDCforUSDC for HONEY
10$HONEY$DAISwap all received HONEYforHONEY for DAI
By setting the second step’s amount to 0, you ensure all $HONEY received from step 0 is used in step 1.

​
Example 2: GIVEN_OUT (USDC−>USDC -> HONEY -> $DAI)

Here you want exactly 500 DAI,andBEXwillcalculatebackwardshowmuchDAI, and BEX will calculate backwards how much USDC you need:
StepAmountToken OutToken InDescription
0500$DAI$HONEYRequest exact 500 $DAI output
10$HONEY$USDCCalculate required $USDC input
The swap calculates first how much HONEYisneededfor500HONEY is needed for 500 DAI, then how much USDCisneededforthatamountofUSDC is needed for that amount of HONEY.

​
Parallel swap examples

Parallel swaps are batch swaps where multiple unrelated swaps are executed in parallel within a single transaction. This allows for efficient execution of multiple trades by batching them together, reducing overall gas costs compared to executing them separately.

​
Example 3: Parallel GIVEN_IN swaps

Execute multiple independent swaps in a single transaction:
StepAmountToken InToken OutDescription
01000$USDC$HONEYSwap 1000 USDCforUSDC for HONEY
10.5$WETH$DAISwap 0.5 WETHforWETH for DAI
20.01$WBTC$USDCSwap 0.01 WBTCforWBTC for USDC
Each swap is independent and executes in parallel, optimizing gas usage.

​
Example 4: Combined GIVEN_OUT swaps

This example demonstrates how to combine a multi-hop swap with a single-hop swap in parallel, all using GIVEN_OUT mode. It performs two independent swaps:
  1. A multi-hop swap A->B->C->D to get exactly 100 D
  2. A single swap E->F to get exactly 50 F
StepAmountToken OutToken InDescription
0100DCFirst step: Request exactly 100 D
10CBSecond step: Use all C from previous step
20BAThird step: Calculate required A input
350FEIndependent parallel swap: Get exactly 50 F
In this example:
  • Steps 0-2 form one multi-hop path (A->B->C->D) where you want exactly 100 D
  • Step 3 is a completely independent swap (E->F) where you want exactly 50 F
  • BEX will calculate the required amounts of tokens A and E needed as inputs
  • The two swaps execute in parallel in a single transaction
This pattern is useful when you need exact output amounts from completely independent swap paths.