AMM SDK

The AMMSDK provides AMM operations for swaps, liquidity management, and pool queries.

Important: AMMSDK methods return TransactionRequest objects that must be signed and sent by the caller.

Swap Operations

swapExactTokensForTokens

Swap an exact amount of input tokens for a minimum amount of output tokens.

Signature:

async swapExactTokensForTokens(
  userAddress: string,
  amountIn: bigint,
  amountOutMin: bigint,
  path: string[],
  to: string,
  deadline: bigint
): Promise<TransactionRequest>

Parameters:

• userAddress: string - User's wallet address
• amountIn: bigint - Exact input token amount
• amountOutMin: bigint - Minimum output token amount
• path: string[] - Token swap path (array of token addresses)
• to: string - Recipient address
• deadline: bigint - Transaction deadline (Unix timestamp)

Returns: Promise<TransactionRequest>

Note: Validates token approval and balance before building transaction.

swapTokensForExactTokens

Swap a maximum amount of input tokens for an exact amount of output tokens.

Signature:

async swapTokensForExactTokens(
  userAddress: string,
  amountOut: bigint,
  amountInMax: bigint,
  path: string[],
  to: string,
  deadline: bigint
): Promise<TransactionRequest>

Parameters:

• userAddress: string - User's wallet address
• amountOut: bigint - Exact output token amount
• amountInMax: bigint - Maximum input token amount
• path: string[] - Token swap path
• to: string - Recipient address
• deadline: bigint - Transaction deadline

Returns: Promise<TransactionRequest>

swapExactETHForTokens

Swap exact ETH for a minimum amount of tokens.

Signature:

async swapExactETHForTokens(
  userAddress: string,
  amountIn: bigint,
  amountOutMin: bigint,
  path: string[],
  to: string,
  deadline: bigint
): Promise<TransactionRequest>

Parameters:

• userAddress: string - User's wallet address
• amountIn: bigint - Exact ETH amount
• amountOutMin: bigint - Minimum output token amount
• path: string[] - Token swap path (first token must be WETH)
• to: string - Recipient address
• deadline: bigint - Transaction deadline

Returns: Promise<TransactionRequest>

swapETHForExactTokens

Swap a maximum amount of ETH for exact tokens.

Signature:

async swapETHForExactTokens(
  userAddress: string,
  amountOut: bigint,
  amountInMax: bigint,
  path: string[],
  to: string,
  deadline: bigint
): Promise<TransactionRequest>

Parameters:

• userAddress: string - User's wallet address
• amountOut: bigint - Exact output token amount
• amountInMax: bigint - Maximum ETH amount
• path: string[] - Token swap path (first token must be WETH)
• to: string - Recipient address
• deadline: bigint - Transaction deadline

Returns: Promise<TransactionRequest>

swapExactTokensForETH

Swap exact tokens for a minimum amount of ETH.

Signature:

async swapExactTokensForETH(
  userAddress: string,
  amountIn: bigint,
  amountOutMin: bigint,
  path: string[],
  to: string,
  deadline: bigint
): Promise<TransactionRequest>

Parameters:

• userAddress: string - User's wallet address
• amountIn: bigint - Exact input token amount
• amountOutMin: bigint - Minimum ETH output
• path: string[] - Token swap path (last token must be WETH)
• to: string - Recipient address
• deadline: bigint - Transaction deadline

Returns: Promise<TransactionRequest>

swapTokensForExactETH

Swap a maximum amount of tokens for exact ETH.

Signature:

async swapTokensForExactETH(
  userAddress: string,
  amountOut: bigint,
  amountInMax: bigint,
  path: string[],
  to: string,
  deadline: bigint
): Promise<TransactionRequest>

Parameters:

• userAddress: string - User's wallet address
• amountOut: bigint - Exact ETH output
• amountInMax: bigint - Maximum input token amount
• path: string[] - Token swap path (last token must be WETH)
• to: string - Recipient address
• deadline: bigint - Transaction deadline

Returns: Promise<TransactionRequest>

swapExactTokensForTokensHybrid

Hybrid swap that routes through either AMM or CLOB based on better pricing.

Signature:

async swapExactTokensForTokensHybrid(
  userAddress: string,
  amountIn: bigint,
  amountOutMin: bigint,
  path: string[],
  to: string,
  deadline: bigint
): Promise<TransactionRequest>

Parameters:

• userAddress: string - User's wallet address
• amountIn: bigint - Exact input token amount
• amountOutMin: bigint - Minimum output token amount
• path: string[] - Token swap path
• to: string - Recipient address
• deadline: bigint - Transaction deadline

Returns: Promise<TransactionRequest>

swapExactTokensForTokensHybridWithIndex

Hybrid swap with a specific price index for CLOB routing.

Signature:

async swapExactTokensForTokensHybridWithIndex(
  userAddress: string,
  amountIn: bigint,
  amountOutMin: bigint,
  path: string[],
  to: string,
  deadline: bigint,
  priceIndex: bigint
): Promise<TransactionRequest>

Parameters:

• userAddress: string - User's wallet address
• amountIn: bigint - Exact input token amount
• amountOutMin: bigint - Minimum output token amount
• path: string[] - Token swap path
• to: string - Recipient address
• deadline: bigint - Transaction deadline
• priceIndex: bigint - CLOB price index

Returns: Promise<TransactionRequest>

Liquidity Operations

addLiquidity

Add liquidity to a token-token pool.

Signature:

async addLiquidity(
  userAddress: string,
  tokenA: string,
  tokenB: string,
  amountADesired: bigint,
  amountBDesired: bigint,
  amountAMin: bigint,
  amountBMin: bigint,
  to: string,
  deadline: bigint
): Promise<TransactionRequest>

Parameters:

• userAddress: string - User's wallet address
• tokenA: string - First token address
• tokenB: string - Second token address
• amountADesired: bigint - Desired amount of token A
• amountBDesired: bigint - Desired amount of token B
• amountAMin: bigint - Minimum amount of token A
• amountBMin: bigint - Minimum amount of token B
• to: string - LP token recipient address
• deadline: bigint - Transaction deadline

Returns: Promise<TransactionRequest>

Note: Validates approvals and balances for both tokens.

addLiquidityETH

Add liquidity to a token-ETH pool.

Signature:

async addLiquidityETH(
  userAddress: string,
  token: string,
  amountTokenDesired: bigint,
  amountTokenMin: bigint,
  amountETHMin: bigint,
  amountETH: bigint,
  to: string,
  deadline: bigint
): Promise<TransactionRequest>

Parameters:

• userAddress: string - User's wallet address
• token: string - Token address
• amountTokenDesired: bigint - Desired token amount
• amountTokenMin: bigint - Minimum token amount
• amountETHMin: bigint - Minimum ETH amount
• amountETH: bigint - ETH amount to add
• to: string - LP token recipient address
• deadline: bigint - Transaction deadline

Returns: Promise<TransactionRequest>

removeLiquidity

Remove liquidity from a token-token pool.

Signature:

async removeLiquidity(
  userAddress: string,
  tokenA: string,
  tokenB: string,
  liquidity: bigint,
  amountAMin: bigint,
  amountBMin: bigint,
  to: string,
  deadline: bigint
): Promise<TransactionRequest>

Parameters:

• userAddress: string - User's wallet address
• tokenA: string - First token address
• tokenB: string - Second token address
• liquidity: bigint - LP token amount to burn
• amountAMin: bigint - Minimum amount of token A to receive
• amountBMin: bigint - Minimum amount of token B to receive
• to: string - Token recipient address
• deadline: bigint - Transaction deadline

Returns: Promise<TransactionRequest>

Note: Validates LP token approval and balance.

removeLiquidityETH

Remove liquidity from a token-ETH pool.

Signature:

async removeLiquidityETH(
  userAddress: string,
  token: string,
  liquidity: bigint,
  amountTokenMin: bigint,
  amountETHMin: bigint,
  to: string,
  deadline: bigint
): Promise<TransactionRequest>

Parameters:

• userAddress: string - User's wallet address
• token: string - Token address
• liquidity: bigint - LP token amount to burn
• amountTokenMin: bigint - Minimum token amount to receive
• amountETHMin: bigint - Minimum ETH amount to receive
• to: string - Recipient address
• deadline: bigint - Transaction deadline

Returns: Promise<TransactionRequest>

removeLiquidityWithPermit

Remove liquidity using permit signature (no prior approval needed).

Signature:

async removeLiquidityWithPermit(
  userAddress: string,
  tokenA: string,
  tokenB: string,
  liquidity: bigint,
  amountAMin: bigint,
  amountBMin: bigint,
  to: string,
  deadline: bigint,
  approveMax: boolean,
  v: number,
  r: string,
  s: string
): Promise<TransactionRequest>

Parameters:

• userAddress: string - User's wallet address
• tokenA: string - First token address
• tokenB: string - Second token address
• liquidity: bigint - LP token amount to burn
• amountAMin: bigint - Minimum amount of token A
• amountBMin: bigint - Minimum amount of token B
• to: string - Recipient address
• deadline: bigint - Transaction deadline
• approveMax: boolean - Approve maximum amount
• v: number - Signature v component (27 or 28)
• r: string - Signature r component (64 hex chars)
• s: string - Signature s component (64 hex chars)

Returns: Promise<TransactionRequest>

removeLiquidityETHWithPermit

Remove liquidity from token-ETH pool using permit signature.

Signature:

async removeLiquidityETHWithPermit(
  userAddress: string,
  token: string,
  liquidity: bigint,
  amountTokenMin: bigint,
  amountETHMin: bigint,
  to: string,
  deadline: bigint,
  approveMax: boolean,
  v: number,
  r: string,
  s: string
): Promise<TransactionRequest>

Parameters:

• userAddress: string - User's wallet address
• token: string - Token address
• liquidity: bigint - LP token amount to burn
• amountTokenMin: bigint - Minimum token amount
• amountETHMin: bigint - Minimum ETH amount
• to: string - Recipient address
• deadline: bigint - Transaction deadline
• approveMax: boolean - Approve maximum amount
• v: number - Signature v component
• r: string - Signature r component
• s: string - Signature s component

Returns: Promise<TransactionRequest>

Quote and Calculation Operations

getAmountOut

Calculate output amount given reserves and input amount.

Signature:

async getAmountOut(
  amountIn: bigint,
  reserveIn: bigint,
  reserveOut: bigint
): Promise<bigint>

Parameters:

• amountIn: bigint - Input token amount
• reserveIn: bigint - Input token reserve
• reserveOut: bigint - Output token reserve

Returns: Promise<bigint> - Output amount

getAmountIn

Calculate required input amount given reserves and desired output.

Signature:

async getAmountIn(
  amountOut: bigint,
  reserveIn: bigint,
  reserveOut: bigint
): Promise<bigint>

Parameters:

• amountOut: bigint - Desired output amount
• reserveIn: bigint - Input token reserve
• reserveOut: bigint - Output token reserve

Returns: Promise<bigint> - Required input amount

getAmountsOut

Calculate output amounts for each step in a multi-hop swap path.

Signature:

async getAmountsOut(amountIn: bigint, path: string[]): Promise<bigint[]>

Parameters:

• amountIn: bigint - Input amount
• path: string[] - Token swap path

Returns: Promise<bigint[]> - Array of amounts for each step

getAmountsIn

Calculate required input amounts for each step to achieve desired output.

Signature:

async getAmountsIn(amountOut: bigint, path: string[]): Promise<bigint[]>

Parameters:

• amountOut: bigint - Desired output amount
• path: string[] - Token swap path

Returns: Promise<bigint[]> - Array of required input amounts

quote

Calculate equivalent amount of token B for a given amount of token A.

Signature:

async quote(
  amountA: bigint,
  reserveA: bigint,
  reserveB: bigint
): Promise<bigint>

Parameters:

• amountA: bigint - Amount of token A
• reserveA: bigint - Reserve of token A
• reserveB: bigint - Reserve of token B

Returns: Promise<bigint> - Equivalent amount of token B

getHybridAmountOut

Get output amount for hybrid routing (AMM or CLOB).

Signature:

async getHybridAmountOut(
  amountIn: bigint,
  path: string[]
): Promise<{ amountOut: bigint; useAMM: boolean; price: bigint }>

Parameters:

• amountIn: bigint - Input amount
• path: string[] - Token swap path

Returns: Promise<{ amountOut: bigint; useAMM: boolean; price: bigint }>

getHybridAmountOutWithIndex

Get output amount for hybrid routing with specific CLOB price index.

Signature:

async getHybridAmountOutWithIndex(
  amountIn: bigint,
  path: string[],
  priceIndex: bigint
): Promise<{ amountOut: bigint; useAMM: boolean; price: bigint }>

Parameters:

• amountIn: bigint - Input amount
• path: string[] - Token swap path
• priceIndex: bigint - CLOB price index

Returns: Promise<{ amountOut: bigint; useAMM: boolean; price: bigint }>

Factory Operations

getPair

Get the pair contract address for two tokens.

Signature:

async getPair(tokenA: string, tokenB: string): Promise<string>

Parameters:

• tokenA: string - First token address
• tokenB: string - Second token address

Returns: Promise<string> - Pair contract address (0x0 if doesn't exist)

allPairs

Get the pair address at a specific index.

Signature:

async allPairs(index: bigint): Promise<string>

Parameters:

• index: bigint - Pair index

Returns: Promise<string> - Pair contract address

allPairsLength

Get the total number of pairs created.

Signature:

async allPairsLength(): Promise<bigint>

Returns: Promise<bigint> - Total pair count

feeTo

Get the fee recipient address.

Signature:

async feeTo(): Promise<string>

Returns: Promise<string> - Fee recipient address

feeToSetter

Get the address that can set the fee recipient.

Signature:

async feeToSetter(): Promise<string>

Returns: Promise<string> - Fee setter address

pairCodeHash

Get the initialization code hash for pairs.

Signature:

async pairCodeHash(): Promise<string>

Returns: Promise<string> - Code hash

createPair

Create a new liquidity pair.

Signature:

async createPair(
  userAddress: string,
  tokenA: string,
  tokenB: string
): Promise<TransactionRequest>

Parameters:

• userAddress: string - User's wallet address
• tokenA: string - First token address
• tokenB: string - Second token address

Returns: Promise<TransactionRequest>

Note: Validates that pair doesn't already exist.

Pair Operations

getReserves

Get token reserves and last update timestamp for a pair.

Signature:

async getReserves(
  pairAddress: string
): Promise<{ reserve0: bigint; reserve1: bigint; blockTimestampLast: number }>

Parameters:

• pairAddress: string - Pair contract address

Returns: Promise<{ reserve0: bigint; reserve1: bigint; blockTimestampLast: number }>

token0

Get the first token address of a pair.

Signature:

async token0(pairAddress: string): Promise<string>

Parameters:

• pairAddress: string - Pair contract address

Returns: Promise<string> - Token0 address

token1

Get the second token address of a pair.

Signature:

async token1(pairAddress: string): Promise<string>

Parameters:

• pairAddress: string - Pair contract address

Returns: Promise<string> - Token1 address

totalSupply

Get the total supply of LP tokens for a pair.

Signature:

async totalSupply(pairAddress: string): Promise<bigint>

Parameters:

• pairAddress: string - Pair contract address

Returns: Promise<bigint> - Total LP token supply

balanceOf

Get LP token balance for an account.

Signature:

async balanceOf(pairAddress: string, account: string): Promise<bigint>

Parameters:

• pairAddress: string - Pair contract address
• account: string - Account address

Returns: Promise<bigint> - LP token balance

swapFee

Get the swap fee for a pair.

Signature:

async swapFee(pairAddress: string): Promise<number>

Parameters:

• pairAddress: string - Pair contract address

Returns: Promise<number> - Swap fee

devFee

Get the developer fee for a pair.

Signature:

async devFee(pairAddress: string): Promise<number>

Parameters:

• pairAddress: string - Pair contract address

Returns: Promise<number> - Developer fee

Token Operations

approve

Approve tokens for spending by a spender address.

Signature:

async approve(
  userAddress: string,
  tokenAddress: string,
  spenderAddress: string,
  amount: bigint
): Promise<TransactionRequest>

Parameters:

• userAddress: string - User's wallet address
• tokenAddress: string - Token contract address
• spenderAddress: string - Spender address (e.g., router)
• amount: bigint - Amount to approve

Returns: Promise<TransactionRequest>

allowance

Check the approved token amount for a spender.

Signature:

async allowance(
  tokenAddress: string,
  ownerAddress: string,
  spenderAddress: string
): Promise<bigint>

Parameters:

• tokenAddress: string - Token contract address
• ownerAddress: string - Token owner address
• spenderAddress: string - Spender address

Returns: Promise<bigint> - Approved amount

tokenBalanceOf

Get token balance for an account.

Signature:

async tokenBalanceOf(tokenAddress: string, account: string): Promise<bigint>

Parameters:

• tokenAddress: string - Token contract address
• account: string - Account address

Returns: Promise<bigint> - Token balance

decimals

Get the decimal places for a token.

Signature:

async decimals(tokenAddress: string): Promise<number>

Parameters:

• tokenAddress: string - Token contract address

Returns: Promise<number> - Token decimals

symbol

Get the symbol for a token.

Signature:

async symbol(tokenAddress: string): Promise<string>

Parameters:

• tokenAddress: string - Token contract address

Returns: Promise<string> - Token symbol

name

Get the name for a token.

Signature:

async name(tokenAddress: string): Promise<string>

Parameters:

• tokenAddress: string - Token contract address

Returns: Promise<string> - Token name