SDK API Reference

The SDK API Reference is a comprehensive guide to the Berancer SDK's API. It includes all the functions and classes available in the SDK, as well as their parameters and return values.

API Initialization

The BalancerApi class provides helper functions for interacting with the Berancer API.

Constructor

typescript

const balancerApi = new BalancerApi(apiUrl: string, chainId: ChainId);

Name	Type	Description	Mainnet Value
apiUrl	string	Url of API	https://api.berachain.com/
chainId	number	Chain that will be queried	80094

Properties

The BalancerApi class initializes the following properties:

Pools - Methods for interacting with individual pools
NestedPools - Methods for working with nested pools
SorSwapPaths - Methods for optimizing swap paths

Pools

pools.fetchPoolState

Finds state of given pool.

typescript

pools.fetchPoolState(id: string): Promise<PoolState>

Parameters

Name	Type	Description
id	string	ID of pool, v2=poolId, v3=address

Returns

typescript

Promise<PoolState>;

PoolState - State of given pool.

pools.fetchPoolStateWithBalances

Finds state of given pool including token balances and pool shares.

typescript

fetchPoolStateWithBalances(
  id: string,
): Promise<PoolStateWithBalances>

Parameters

Name	Type	Description
id	string	poolId

Returns

typescript

Promise<PoolStateWithBalances>;

PoolStateWithBalances - State of given pool including token balances and pool shares.

Nested Pools

nestedPools.fetchPoolState

Finds state of a set of nested pools.

typescript

fetchNestedPoolState(id: string): Promise<NestedPoolState>

Parameters

Name	Type	Description
id	string	ID of pool, v2=poolId, v3=address

Returns

typescript

Promise<NestedPoolState>;

NestedPoolState - state of a set of nested pools.

SorSwapPaths

sorSwapPaths.fetchSorSwapPaths

Finds optimized swap paths for a given swap config.

typescript

fetchSorSwapPaths(sorInput: SorInput): Promise<Path[]>

Parameters

Name	Type	Description
sorInput	SorInput	Swap configs

Returns

typescript

Promise<Path[]>;

Path[] - optimized swap paths for the given swap.

AddLiquidity

This class provides functionality to:

Perform on-chain queries to see the result of an addLiquidity operation
Build an addLiquidity transaction, with slippage, for a consumer to submit
Supported add types: SingleToken, Unbalanced, Proportional

Constructor

typescript

const addLiquidity = new AddLiquidity();

Methods

query

Simulate addLiquidity operation by using an onchain call.

typescript

query(
  input: AddLiquidityInput,
  poolState: PoolState
): Promise<AddLiquidityQueryOutput>

Parameters

Name	Type	Description
input	AddLiquidityInput	User defined inputs
poolState	PoolState	Current state of pool that liquidity is being added to

Returns

typescript

Promise<AddLiquidityQueryOutput>;

AddLiquidityQueryOutput - Data that can be passed to buildCall. Includes updated bptOut amount.

buildCall

Builds the addLiquidity transaction using user defined slippage.

typescript

buildCall(input: AddLiquidityBuildCallInput): AddLiquidityBuildCallOutput

Parameters

Name	Type	Description
input	AddLiquidityBuildCallInput	Parameters required to build the call including user defined slippage

Returns

typescript

AddLiquidityBuildCallOutput;

AddLiquidityBuildCallOutput - Encoded call data for addLiquidity that user can submit.

buildCallWithPermit2

Builds the addLiquidity transaction using user defined slippage and Permit2 signature for token approval.

Permit2 Signature

Check out Permit2 Helper section on how to generate a Permit2 signature.

typescript

buildCallWithPermit2(input: AddLiquidityBuildCallInput, permit2: Permit2): AddLiquidityBuildCallOutput

Parameters

Name	Type	Description
input	AddLiquidityBuildCallInput	Parameters required to build the call including user defined slippage
permit2	Permit2	Permit2 object with metadata and encoded signature

Returns

typescript

AddLiquidityBuildCallOutput;

AddLiquidityBuildCallOutput - Encoded call data for addLiquidity that user can submit.

RemoveLiquidity

This class provides functionality to:

Perform on-chain queries to see the result of an removeLiquidity operation
Build a removeLiquidity transaction, with slippage, for a consumer to submit
Supported remove types: Unbalanced, SingleTokenExactOutInput, SingleTokenExactInInput, Proportional

Constructor

typescript

const removeLiquidity = new RemoveLiquidity();

Methods

query

Simulate removeLiquidity operation by using an onchain call.

typescript

query(
  input: RemoveLiquidityInput,
  poolState: PoolState,
): Promise<RemoveLiquidityQueryOutput>

Parameters

Name	Type	Description
input	RemoveLiquidityInput	User defined inputs
poolState	PoolState	Current state of pool that liquidity is being removed from

Returns

typescript

Promise<RemoveLiquidityQueryOutput>;

RemoveLiquidityQueryOutput - Data that can be passed to buildCall. Includes updated amountsOut amount.

queryRemoveLiquidityRecovery

Calculates proportional exit using pool state. Note - this does not do an onchain query.

typescript

queryRemoveLiquidityRecovery(
  input: RemoveLiquidityRecoveryInput,
  poolState: PoolState,
): Promise<RemoveLiquidityQueryOutput>

Parameters

Name	Type	Description
input	RemoveLiquidityRecoveryInput	User defined inputs
poolState	PoolState	Current state of pool that liquidity is being removed from

Returns

typescript

Promise<RemoveLiquidityQueryOutput>;

RemoveLiquidityQueryOutput - Data that can be passed to buildCall. Includes updated amountsOut amount.

buildCall

Builds the removeLiquidity transaction using user defined slippage.

typescript

buildCall(
  input: RemoveLiquidityBuildCallInput,
): RemoveLiquidityBuildCallOutput

Parameters

Name	Type	Description
input	RemoveLiquidityBuildCallInput	Input with user defined slippage

Returns

typescript

RemoveLiquidityBuildCallOutput;

RemoveLiquidityBuildCallOutput - Encoded call data for addLiquidity that user can submit.

buildCallWithPermit

Builds the removeLiquidity transaction using user defined slippage and Permit signature for token approval.

Permit Signature

Check out Permit Helper section on how to generate a Permit signature.

typescript

buildCallWithPermit(
  input: RemoveLiquidityBuildCallInput,
  permit: Permit,
): RemoveLiquidityBuildCallOutput

Parameters

Name	Type	Description
input	RemoveLiquidityBuildCallInput	Input with user defined slippage
permit	Permit	Permit object with metadata and encoded signature

Returns

typescript

RemoveLiquidityBuildCallOutput;

RemoveLiquidityBuildCallOutput - Encoded call data for addLiquidity that user can submit.

Swap

This class provides functionality to:

Perform on-chain queries to see the result of a Swap operation
Build a Swap transaction, with slippage, for a consumer to submit

Constructor

typescript

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.

Methods

query

Gets up to date swap result by querying onchain.

typescript

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

typescript

Promise<ExactInQueryOutput | ExactOutQueryOutput>;

ExactInQueryOutput | ExactOutQueryOutput

The updated return for the given swap, either expectedAmountOut or expectedAmountIn depending on swap kind.

buildCall

Builds the swap transaction using user defined slippage.

typescript

buildCall(
  input: SwapBuildCallInput,
): SwapBuildOutputExactIn | SwapBuildOutputExactOut

Parameters

Name	Type	Description
input	SwapBuildCallInput	Input with user defined slippage

Returns

typescript

SwapBuildOutputExactIn | SwapBuildOutputExactOut;

SwapBuildOutputExactIn | SwapBuildOutputExactOut - Encoded call data for swap that user can submit. Includes minAmountOut or maxAmountIn depending on swap kind.

buildCallWithPermit2

Builds the swap transaction using user defined slippage and Permit2 signature for token approval.

Permit2 Signature

Check out Permit2 Helper section on how to generate a Permit2 signature.

typescript

buildCallWithPermit2(
  input: SwapBuildCallInput,
  permit2: Permit2,
): SwapBuildOutputExactIn | SwapBuildOutputExactOut

Parameters

Name	Type	Description
input	SwapBuildCallInput	Input with user defined slippage
permit2	Permit2	Permit2 object with metadata and encoded signature

Returns

typescript

SwapBuildOutputExactIn | SwapBuildOutputExactOut;

SwapBuildOutputExactIn | SwapBuildOutputExactOut - Encoded call data for swap that user can submit. Includes minAmountOut or maxAmountIn depending on swap kind.

quote

Gives the combined return amount for all paths. Note - this always uses the original path amounts provided in constructor and does not get updated.

typescript

public get quote(): TokenAmount

Returns

typescript

TokenAmount;

TokenAmount - Gives the combined return amount for all paths (output amount for givenIn, input amount for givenOut).

inputAmount

typescript

public get inputAmount(): TokenAmount

Returns

typescript

TokenAmount;

TokenAmount - Gives the combined input amount for all paths.

outputAmount

typescript

public get outputAmount(): TokenAmount

Returns

typescript

TokenAmount;

TokenAmount - Gives the combined output amount for all paths.

queryCallData

typescript

public queryCallData(): string

Returns

typescript

string;

Encoded query data for swap that a user can call to get an updated amount.

PriceImpact

This class provides helper functions to calculate Price Impact for add/remove/swap actions.

Methods

addLiquiditySingleToken

Calculate price impact on add liquidity single token operations.

typescript

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 liquidity is being added to

Returns

typescript

Promise<PriceImpactAmount>;

PriceImpactAmount - Price impact for operation.

addLiquidityUnbalanced

Calculate price impact on add liquidity unbalanced operations.

typescript

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 liquidity is being added to

Returns

typescript

Promise<PriceImpactAmount>;

PriceImpactAmount - Price impact for operation.

addLiquidityNested

Calculate price impact on add liquidity nested token operations.

typescript

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

typescript

Promise<PriceImpactAmount>;

PriceImpactAmount - Price impact for operation.

removeLiquidity

Calculate price impact on remove liquidity operations.

typescript

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 liquidity is being removed from

Returns

typescript

Promise<PriceImpactAmount>;

PriceImpactAmount - Price impact for operation.

removeLiquidityNested

Calculate price impact on remove liquidity single token nested operations.

typescript

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

typescript

Promise<PriceImpactAmount>;

PriceImpactAmount - Price impact for operation.

swap

Calculate price impact on swap operations.

typescript

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

typescript

Promise<PriceImpactAmount>;

PriceImpactAmount - Price impact for operation.

Utils

Helper functions.

calculateProportionalAmounts

Given pool balances (including BPT) and a reference token amount, it calculates all other amounts proportional to the reference amount.

typescript

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

typescript

{
  tokenAmounts: InputAmount[];
  bptAmount: InputAmount;
}

Amounts proportional to the reference amount.

Permit2 Helper

Balancer v3 handles token approval through Pemit2 and this helper facilitates Permit2 signature generation.

Each operation (i.e. addLiquidity, addLiquidityNested, addLiquidityBoosted and swap) has its own method that leverages the same input type of the operation itself in order to simplify signature generation.

Function

typescript

static async signAddLiquidityApproval(
    input: AddLiquidityBaseBuildCallInput & {
        client: PublicWalletClient;
        owner: Address;
        nonces?: number[];
        expirations?: number[];
    },
): Promise<Permit2>

Parameters

Name	Type	Description
input	AddLiquidityBaseBuildCallInput	Add Liquidity Input
client	PublicWalletClient	Viem's wallet client with public actions
owner	Address	User address
nonces (optional)	number[]	Nonces for each token
expirations (optional)	number[]	Expirations for each token

Returns

typescript

Promise<Permit2>;

Permit2 - Permit2 object with metadata and encoded signature

Permit Helper

Balancer v3 conforms with EIP-2612 and this helper facilitates Permit signature generation.

Each operation (i.e. removeLiquidity, removeLiquidityNested and removeLiquidityBoosted) has its own method that leverages the same input type of the operation itself in order to simplify signature generation.

Function

typescript

static signRemoveLiquidityApproval = async (
    input: RemoveLiquidityBaseBuildCallInput & {
        client: PublicWalletClient;
        owner: Hex;
        nonce?: bigint;
        deadline?: bigint;
    },
): Promise<Permit>

Parameters

Name	Type	Description
input	RemoveLiquidityBaseBuildCallInput	Remove Liquidity Input
client	PublicWalletClient	Viem's wallet client with public actions
owner	Address	User address
nonces (optional)	number[]	Nonces for each token
expirations (optional)	number[]	Expirations for each token

Returns

typescript

Promise<Permit>;

Permit - Permit object with metadata and encoded signature

SDK API Reference ​

API Initialization ​

Constructor ​

Properties ​

Pools ​

pools.fetchPoolState ​

pools.fetchPoolStateWithBalances ​

Nested Pools ​

nestedPools.fetchPoolState ​

SorSwapPaths ​

sorSwapPaths.fetchSorSwapPaths ​

AddLiquidity ​

Constructor ​

Methods ​

query ​

buildCall ​

buildCallWithPermit2 ​

RemoveLiquidity ​

Constructor ​

Methods ​

query ​

queryRemoveLiquidityRecovery ​

buildCall ​

buildCallWithPermit ​

Swap ​

Constructor ​

Methods ​

query ​

buildCall ​

buildCallWithPermit2 ​

quote ​

inputAmount ​

outputAmount ​

queryCallData ​

PriceImpact ​

Methods ​

addLiquiditySingleToken ​

addLiquidityUnbalanced ​

addLiquidityNested ​

removeLiquidity ​

removeLiquidityNested ​

swap ​

Utils ​

calculateProportionalAmounts ​

Permit2 Helper ​

Permit Helper ​

SDK API Reference

API Initialization

Constructor

Properties

Pools

pools.fetchPoolState

pools.fetchPoolStateWithBalances

Nested Pools

nestedPools.fetchPoolState

SorSwapPaths

sorSwapPaths.fetchSorSwapPaths

AddLiquidity

Constructor

Methods

query

buildCall

buildCallWithPermit2

RemoveLiquidity

Constructor

Methods

query

queryRemoveLiquidityRecovery

buildCall

buildCallWithPermit

Swap

Constructor

Methods

query

buildCall

buildCallWithPermit2

quote

inputAmount

outputAmount

queryCallData

PriceImpact

Methods

addLiquiditySingleToken

addLiquidityUnbalanced

addLiquidityNested

removeLiquidity

removeLiquidityNested

swap

Utils

calculateProportionalAmounts

Permit2 Helper

Permit Helper