WIP SDK for Balancer Protocol. Interfaces may have frequent breaking changes until a stable release.
pnpm install
fetch
If your platform does not support one of the required features, it is also possible to import a polyfill.
fetch
-> node-fetchpnpm test
Testing runs against a local anvil fork and requires the following RPC URL to be configured in your .env file:
ETHEREUM_RPC_URL
POLYGON_RPC_URL
FANTOM_RPC_URL
SEPOLIA_RPC_URL
Anvil Client
To download and install the anvil client, run the following commands (MacOS):
curl -L https://foundry.paradigm.xyz | bash
brew install libusb
source /Users/$(whoami)/.zshenv
foundryup
The Balancer SDK is a Typescript/Javascript library for interfacing with the Balancer protocol and can be installed with:
pnpm add @balancer-labs/sdk
This class provides functionality to:
See the addLiqudity example.
const addLiquidity = new AddLiquidity();
Simulate addLiquidity operation by using an onchain call.
query(
input: AddLiquidityInput,
poolState: PoolState
): Promise<AddLiquidityQueryOutput>
Parameters
Name | Type | Description |
---|---|---|
input | AddLiquidityInput | User defined inputs |
poolState | PoolState | Current state of pool that liqudity is being added to |
Returns
Promise<AddLiquidityQueryOutput>
AddLiquidityQueryOutput - Data that can be passed to buildCall
. Includes updated bptOut
amount.
Builds the addLiquidity transaction using user defined slippage.
buildCall(input: AddLiquidityBuildCallInput): AddLiquidityBuildCallOutput
Parameters
Name | Type | Description |
---|---|---|
input | AddLiquidityBuildCallInput | Parameters required to build the call including user defined slippage |
Returns
AddLiquidityBuildCallOutput
AddLiquidityBuildCallOutput - Encoded call data for addLiquidity that user can submit.
This class provides functionality to:
See the removeLiqudity example.
const removeLiquidity = new RemoveLiquidity();
Simulate removeLiquidity operation by using an onchain call.
query(
input: RemoveLiquidityInput,
poolState: PoolState,
): Promise<RemoveLiquidityQueryOutput>
Parameters
Name | Type | Description |
---|---|---|
input | RemoveLiquidityInput | User defined inputs |
poolState | PoolState | Current state of pool that liqudity is being removed from |
Returns
Promise<RemoveLiquidityQueryOutput>
RemoveLiquidityQueryOutput - Data that can be passed to buildCall
. Includes updated amountsOut
amount.
Calculates proportional exit using pool state. Note - this does not do an onchain query.
queryRemoveLiquidityRecovery(
input: RemoveLiquidityRecoveryInput,
poolState: PoolState,
): Promise<RemoveLiquidityQueryOutput>
Parameters
Name | Type | Description |
---|---|---|
input | RemoveLiquidityRecoveryInput | User defined inputs |
poolState | PoolState | Current state of pool that liqudity is being removed from |
Returns
Promise<RemoveLiquidityQueryOutput>
RemoveLiquidityQueryOutput - Data that can be passed to buildCall
. Includes updated amountsOut
amount.
Builds the removeLiquidity transaction using user defined slippage.
buildCall(
input: RemoveLiquidityBuildCallInput,
): RemoveLiquidityBuildCallOutput
Parameters
Name | Type | Description |
---|---|---|
input | RemoveLiquidityBuildCallInput | Input with user defined slippage |
Returns
RemoveLiquidityBuildCallOutput
RemoveLiquidityBuildCallOutput - Encoded call data for addLiquidity that user can submit.
This class provides functionality to:
See the swap example.
const swap = new Swap(swapInput: SwapInput);
Name | Type | Description |
---|---|---|
swapInput | SwapInput | Swap input including path information. |
Note: SwapInput
data is normally returned from an API SOR query but may be constructed manually.
Gets up to date swap result by querying onchain.
query(
rpcUrl?: string,
block?: bigint,
): Promise<ExactInQueryOutput | ExactOutQueryOutput>
Parameters
Name | Type | Description |
---|---|---|
rpcUrl (optional) | string | RPC URL, e.g. Infura/Alchemy |
block (optional) | bigint | Block no to perform the query |
Returns
Promise<ExactInQueryOutput | ExactOutQueryOutput>
ExactInQueryOutput ExactOutQueryOutput
The upated return for the given swap, either expectedAmountOut
or expectedAmountIn
depending on swap kind.
Builds the swap transaction using user defined slippage.
buildCall(
input: SwapBuildCallInput,
): SwapBuildOutputExactIn | SwapBuildOutputExactOut
Parameters
Name | Type | Description |
---|---|---|
input | SwapBuildCallInput | Input with user defined slippage |
Returns
SwapBuildOutputExactIn | SwapBuildOutputExactOut
SwapBuildOutputExactIn SwapBuildOutputExactOut
RemoveLiquidityBuildCallOutput - Encoded call data for swap that user can submit. Includes minAmountOut
or maxAmountIn
depending on swap kind.
Gives the combined return amount for all paths. Note - this always uses the original path amounts provided in constructor and does not get updated.
public get quote(): TokenAmount
Returns
TokenAmount
TokenAmount - Gives the combined return amount for all paths (output amount for givenIn, input amount for givenOut).
public get inputAmount(): TokenAmount
Returns
TokenAmount
TokenAmount - Gives the combined input amount for all paths.
public get outputAmount(): TokenAmount
Returns
TokenAmount
TokenAmount - Gives the combined output amount for all paths.
public queryCallData(): string
Returns
string
Encoded query data for swap that a user can call to get an updated amount.
This class provides helper functions to calculate Price Impact for add/remove/swap actions.
See the price impact example.
Calculate price impact on add liquidity single token operations.
addLiquiditySingleToken(
input: AddLiquiditySingleTokenInput,
poolState: PoolState,
): Promise<PriceImpactAmount>
Parameters
Name | Type | Description |
---|---|---|
input | AddLiquiditySingleTokenInput | Same input used in the corresponding add liquidity operation |
poolState | PoolState | Current state of pool that liqudity is being added to |
Returns
Promise<PriceImpactAmount>
PriceImpactAmount - Price impact for operation.
Calculate price impact on add liquidity unbalanced operations.
addLiquidityUnbalanced = async (
input: AddLiquidityUnbalancedInput,
poolState: PoolState,
): Promise<PriceImpactAmount>
Parameters
Name | Type | Description |
---|---|---|
input | AddLiquidityUnbalancedInput | Same input used in the corresponding add liquidity operation |
poolState | PoolState | Current state of pool that liqudity is being added to |
Returns
Promise<PriceImpactAmount>
PriceImpactAmount - Price impact for operation.
Calculate price impact on add liquidity nested token operations.
addLiquidityNested = async (
input: AddLiquidityNestedInput,
nestedPoolState: NestedPoolState,
): Promise<PriceImpactAmount>
Parameters
Name | Type | Description |
---|---|---|
input | AddLiquidityNestedInput | Same input used in the corresponding add liquidity operation |
nestedPoolState | NestedPoolState | Current state of nested pools |
Returns
Promise<PriceImpactAmount>
PriceImpactAmount - Price impact for operation.
Calculate price impact on remove liquidity operations.
removeLiquidity = async (
input:
| RemoveLiquiditySingleTokenExactInInput
| RemoveLiquidityUnbalancedInput,
poolState: PoolState,
): Promise<PriceImpactAmount>
Parameters
Name | Type | Description |
---|---|---|
input | RemoveLiquiditySingleTokenExactInInput | Same input used in the corresponding remove liquidity operation |
input | RemoveLiquidityUnbalancedInput | Same input used in the corresponding remove liquidity operation |
poolState | PoolState | Current state of pool that liqudity is being removed from |
Returns
Promise<PriceImpactAmount>
PriceImpactAmount - Price impact for operation.
Calculate price impact on remove liquidity single token nested operations.
removeLiquidityNested = async (
input: RemoveLiquidityNestedSingleTokenInput,
nestedPoolState: NestedPoolState,
): Promise<PriceImpactAmount>
Parameters
Name | Type | Description |
---|---|---|
input | RemoveLiquidityNestedSingleTokenInput | Same input used in the corresponding remove liquidity operation |
nestedPoolState | NestedPoolState | Current state of nested pools |
Returns
Promise<PriceImpactAmount>
PriceImpactAmount - Price impact for operation.
Calculate price impact on swap operations.
swap = async (
swapInput: SwapInput,
rpcUrl?: string,
block?: bigint,
): Promise<PriceImpactAmount>
Parameters
Name | Type | Description |
---|---|---|
swapInput | SwapInput | Swap input including path information. |
rpcUrl (optional) | string | RPC URL, e.g. Infura/Alchemy |
block (optional) | bigint | Block no to perform the query |
Note: SwapInput
data is normally returned from an API SOR query but may be constructed manually.
Returns
Promise<PriceImpactAmount>
PriceImpactAmount - Price impact for operation.
This class provides helper functions for interacting with the Balancer API.
See the examples for add/remove/swap linked above as these use BalancerApi to fetch required data.
const balancerApi = new BalancerApi(balancerApiUrl: string, chainId: ChainId);
Name | Type | Description |
---|---|---|
balancerApiUrl | string | Url of Balancer API |
chainId | ChainId | Chain that will be queried |
Finds state of given pool.
pools.fetchPoolState(id: string): Promise<PoolState>
Parameters
Name | Type | Description |
---|---|---|
id | string | ID of pool, V2=poolId, V3=address |
Returns
Promise<PoolState>
PoolState - State of given pool.
Finds state of given pool including token balances and pool shares.
fetchPoolStateWithBalances(
id: string,
): Promise<PoolStateWithBalances>
Parameters
Name | Type | Description |
---|---|---|
id | string | ID of pool, V2=poolId, V3=address |
Returns
Promise<PoolStateWithBalances>
PoolStateWithBalances - State of given pool including token balances and pool shares.
Finds state of a set of nested pools.
fetchNestedPoolState(id: string): Promise<NestedPoolState>
Parameters
Name | Type | Description |
---|---|---|
id | string | ID of pool, V2=poolId, V3=address |
Returns
Promise<NestedPoolState>
NestedPoolState - state of a set of nested pools.
Finds optimised swap paths for a given swap config.
fetchSorSwapPaths(sorInput: SorInput): Promise<Path[]>
Parameters
Name | Type | Description |
---|---|---|
sorInput | SorInput | Swap configs |
Returns
Promise<Path[]>
Path[] - optimised swap paths for the given swap.
Helper functions.
Given pool balances (including BPT) and a reference token amount, it calculates all other amounts proportional to the reference amount.
See the price impact example.
calculateProportionalAmounts(
pool: {
address: Address;
totalShares: HumanAmount;
tokens: {
address: Address;
balance: HumanAmount;
decimals: number
}[];
},
referenceAmount: InputAmount,
): {
tokenAmounts: InputAmount[];
bptAmount: InputAmount;
}
Parameters
Name | Type | Description |
---|---|---|
pool | See above | Pool state |
referenceAmount | InputAmount | Ref token amount |
Returns
{
tokenAmounts: InputAmount[];
bptAmount: InputAmount;
}
Amounts proportional to the reference amount.