@tapp-exchange/sdk

v0.7.2

Published

2 months ago

A fully typed, modular **TypeScript SDK** for interacting with the **TAPP Decentralized Exchange** on the **Aptos blockchain**.

0High
0Medium
0Low

TAPP Decentralized Exchange SDK

A fully typed, modular TypeScript SDK for interacting with the TAPP Decentralized Exchange on the Aptos blockchain.

This SDK simplifies tasks such as:

Pool discovery and querying
Swaps (AMM, CLMM, Stable pools)
Creating, adding and removing liquidity (AMM, CLMM, Stable pools)
Collecting fees

📚 Table of Contents

Installation

npm install @tapp-exchange/sdk

Initialization

The Tapp TypeScript SDK provides a convenient helper function initTappSDK to initialize the SDK. (Currently only supports MAINNET)

import { initTappSDK } from '@tapp-exchange/sdk';
import { Network } from '@aptos-labs/ts-sdk';

const sdk = initTappSDK({
    network: Network.MAINNET, // optional. Default: MAINNET 
    url: 'https://....' // optional. 
});

Pool

Get Pool List

Fetches a paginated list of available pools, optionally sorted by TVL or other fields.

Use sdk.Pool.getPools method.

Available params

page: number The page number to fetch (defaults to 1).
size: number Number of items per page (defaults to 10).
sortBy: string Field to sort by (defaults to "tvl").
type: string Optional pool type filter. (AMM, CLMM, STABLE)

const pools = await sdk.Pool.getPools({
  page: 1, 
  size: 10,
  sortBy: 'tvl',
});

Get Specific Pool Info

Retrieves detailed information about a specific pool by its ID.

const info = await sdk.Pool.getInfo('0xpoolid');

Swap

Estimate Swap Amount

Estimates the amount received or needed for a swap, depending on input direction.

Params

amount: number The amount for estimation (used as input or desired output depending on field).
poolId: string The identifier of the pool.
pair: [number, number] A tuple of token indexes to swap, e.g., [0, 1] means token at index 0 is being swapped for token at index 1.
a2b: boolean Swap direction — true for token at pair[0] to pair[1], false for pair[1] to pair[0].
field (optional): input | output Indicates if amount is an "input" or "output" amount (defaults to "input").

const getEstSwap = async () => {
    const result = await sdk.Swap.getEstSwapAmount({
        poolId: "0xpool",
        a2b: true,
        field: 'input', // input or output
        amount: 1000000000,
        pair: [0, 1]
    });
    
    if(result.error instanceof TradeSizeExceedsError) {
        console.error(result.error.message)
        console.error('max allowed amount', result.error.maxAmountIn);
    }

    console.log(result);
};

Get Swap Route

Retrieves the pool route information between two tokens.

Use sdk.Swap.getRoute method

Example

async function getRoute() {
    const token0 = '0xtoken1'
    const token1 = '0xtoken2'
    const poolInfo = await sdk.Swap.getRoute(token0, token1);

    console.log(poolInfo)
}

AMM Swap

Creates a swap payload for an AMM pool

Use sdk.Swap.swapAMMTransactionPayload method

Params:

poolId: string The address of the pool in which the swap is performed.
a2b: boolean Direction of the swap; true for token A to B, false for B to A.
fixedAmountIn: boolean Whether the input amount is fixed (defaults to true).
amount0: number Amount of token A.
amount1: number Amount of token B.

const { signAndSubmitTransaction, account } = useWallet();

async function swapAMM() {
    const params: SwapAMMParams = {
        poolId: '0xpool',
        a2b: true,
        fixedAmountIn: true,
        amount0: 100000000,
        amount1: 10000000,
    }
    const data = sdk.Swap.swapAMMTransactionPayload(params);

    await signAndSubmitTransaction({
        sender: account.address,
        data: data
    });
}

CLMM Swap

Creates a swap payload for a CLMM pool

Params:

poolId: string The address of the CLMM pool.
amountIn: number The input token amount for the swap.
minAmountOut: number The minimum acceptable output amount.
a2b: boolean Direction of the swap; true for token A to B, false for B to A.
fixedAmountIn: boolean Indicates whether amountIn is fixed (true).
targetSqrtPrice: number The target square root price.

const { signAndSubmitTransaction, account } = useWallet();

async function swapCLMM() {
    const params: SwapCLMMParams = {
        poolId: '0xpool',
        amountIn: 100000000,
        minAmountOut: 521850658,
        a2b: true,
        fixedAmountIn: true,
        targetSqrtPrice: 4295048016
    }
    const data = sdk.Swap.swapCLMMTransactionPayload(params);

    await signAndSubmitTransaction({
        sender: account.address,
        data: data
    });
}

Stable Swap

Creates a swap payload for a Stable pool

Params:

poolId: string The address of the Stable pool.
tokenIn: number The Index of the token to swap from.
tokenOut: number The Index of the token to swap to.
amountIn: number The input token amount for the swap.
minAmountOut: number The minimum amount of output tokens.

const { signAndSubmitTransaction, account } = useWallet();

async function swapStable() {
    const params: SwapStableParams = {
        poolId: "0xpool",
        tokenIn: 2,
        tokenOut: 3,
        amountIn: 100000000,
        minAmountOut: 0,
    }
    const data = sdk.Swap.swapStableTransactionPayload(params);

    await signAndSubmitTransaction({
        sender: account.address,
        data: data
    });
}

Estimate SOR Swap Amount

Estimates the amount received or needed for a swap, depending on input direction.

Params

amount: number The amount for estimation (used as input or desired output depending on field).
fromAddr: string
toAddr: string
field (optional): input | output Indicates if amount is an "input" or "output" amount (defaults to "input").

const getEstSwap = async () => {
    const estSwapParams: GetSOREstSwapParams = {
        amount: 100000,
        field: 'input', // input or output
        fromAddr: "0xtoken0",
        toAddr: "0xtoken1",
    }

    console.log(estSwapParams);
};

SOR Swap

Creates a swap payload for SOR

Params:

amounts: string[] The address of the Stable pool.
slippage: number. The slippage percentge. Default: 1
routeMatrix: RouteMatrix[]

const { signAndSubmitTransaction, account } = useWallet();

async function swapSOR() {
    const estSwapParams: GetSOREstSwapParams = {
        amount: 100000,
        field: 'input',
        fromAddr: "0xtoken0",
        toAddr: "0xtoken1",
    }

    const { amounts, routeMatrix } = await sdk.Swap.getSOREstSwapAmount()
    const params: SwapSORParams = {
        amounts: amounts,
        routeMatrix: routeMatrix,
        slippage: 1
    }

    const data = sdk.Swap.swapSORTransactionPayload(params);

    await signAndSubmitTransaction({
        sender: account.address,
        data: data
    });
}

Liquidity

Create Pool and Add Liquidity

AMM

Creates an AMM pool and adds initial liquidity.

Params

tokenAddress: string[] An array of token addresses.
fee: number The fee traders will pay to use your pool's liquidity.
amounts: number[] The initial token amounts.

const { signAndSubmitTransaction, account } = useWallet();

async function createAMMPoolAndAddLiquidity() {
    const params: CreateAMMPoolAndAddLiquidityParams = {
        tokenAddress: ['0xtoken1', '0xtoken2'],
        fee: 3000,
        amounts: [20000000000, 30000000000],
    }
    const data = sdk.Position.createAMMPoolAndAddLiquidity(params);

    await signAndSubmitTransaction({
        sender: account.address,
        data: data
    });
}

CLMM

Creates a CLMM pool and adds initial liquidity.

Params:

tokenAddress: string[] An array of token addresses.
fee: number The fee traders will pay to Use your pool's liquidity.
amounts: number[] The initial token amounts.
initialPrice: number Starting price for liquidity.
minPrice: number The lower bound price of the liquidity range.
maxPrice: number The upper bound price of the liquidity range.
isMaxAmountB: number Whether the second token amount (amountB) is flexible based on slippage.

const { signAndSubmitTransaction, account } = useWallet();

async function createCLMMPoolAndAddLiquidity() {
    const params: CreateCLMMPoolAndAddLiquidityParams = {
        tokenAddress: ['0xtoken1', '0xtoken2'],
        fee: 3000,
        amounts: [10000000000, 10000000000],
        initialPrice: 1,
        minPrice: 0.000001,
        maxPrice: Infinity,
        isMaxAmountB: true,
    }
    const data = sdk.Position.createCLMMPoolAndAddLiquidity(params);

    await signAndSubmitTransaction({
        sender: account.address,
        data: data
    });
}

Stable

Creates a Stable pool and adds initial liquidity.

Params:

tokenAddress: string[] An array of token addresses.
fee: number The fee traders will pay to Use your pool's liquidity.
amounts: number[] The initial token amounts.
amplificationFactor: number Amplification factor.
offpeg_fee_multiplier: number Optional. Multiplier applied to fee when assets are off-peg. Defaults to 20_000_000_000.

const { signAndSubmitTransaction, account } = useWallet();

async function createStablePoolAndAddLiquidity() {
    const params: CreateStablePoolAndAddLiquidityParams = {
        tokenAddress: ['0xtoken1', '0xtoken2', '0xtoken3'],
        fee: 500,
        amounts: [20000000000, 10000000000, 2000000000],
        amplificationFactor: 1000,
    }
    const data = sdk.Position.createStablePoolAndAddLiquidity(params);

    await signAndSubmitTransaction({
        sender: account.address,
        data: data
    });
}

Remove Liquidity

AMM

Removes liquidity from single or multiple AMM positions.

Single Params:

poolId: string The ID of the AMM pool.
positionAddr: string The address of the liquidity position.
mintedShare: number The amount of share tokens to burn.
minAmount0: number Minimum amount of token0.
minAmount1: number Minimum amount of token1.

const { signAndSubmitTransaction, account } = useWallet();

async function removeSingleAMMLiquidity() {
    const params: RemoveSingleAMMLiquidityParams = {
        poolId: '0xpool',
        positionAddr: '0xposition',
        mintedShare: 10000,
        minAmount0: 10000,
        minAmount1: 10000,
    }
    const data = sdk.Position.removeSingleAMMLiquidity(params);

    await signAndSubmitTransaction({
        sender: account.address,
        data: data
    });
}

Multiple Params:

poolId: The ID of the pool.
positions: An array of position objects, each containing:
- positionAddr: The address of the liquidity position.
- mintedShare: The amount of share tokens to burn.
- minAmount0: Minimum amount token0.
- minAmount1: Minimum amount token1.

const { signAndSubmitTransaction, account } = useWallet();

async function removeMultipleAMMLiquidity() {
    const params: RemoveMultipleAMMLiquidityParams = {
        poolId: '0xpool',
        positions: [
            {
                positionAddr: '0xposition1',
                mintedShare: 10000,
                minAmount0: 10000,
                minAmount1: 10000,
            },
            {
                positionAddr: '0xposition2',
                mintedShare: 20000,
                minAmount0: 20000,
                minAmount1: 20000,
            }
        ]
    }
    const data = sdk.Position.removeMultipleAMMLiquidity(params);

    await signAndSubmitTransaction({
        sender: account.address,
        data: data
    });
}

CLMM

Removes liquidity from single or multiple CLMM positions.

Single Use sdk.Position.removeSingleCLMMLiquidity method

Params:

poolId: string The ID of the CLMM pool.
positionAddr: string The address of the liquidity position.
mintedShare: number The amount of share tokens to burn.
minAmount0: number Minimum amount of token0.
minAmount1: number Minimum amount of token1.

const { signAndSubmitTransaction, account } = useWallet();

async function removeSingleCLMMLiquidity() {
    const params: RemoveSingleCLMMLiquidityParams = {
        poolId: '0xpool',
        positionAddr: '0xposition',
        mintedShare: 10000,
        minAmount0: 10000,
        minAmount1: 10000,
    }
    const data = sdk.Position.removeSingleCLMMLiquidity(params);

    await signAndSubmitTransaction({
        sender: account.address,
        data: data
    });
}

Multiple

Use sdk.Position.removeMultipleCLMMLiquidity method

Params:

poolId: string The ID of the CLMM pool.
positions: An array of objects, each describing a position with:
- positionAddr: string The address of the liquidity position.
- mintedShare: number The amount of share tokens to burn.
- minAmount0: number Minimum amount of token0.
- minAmount1: number Minimum amount of token1.

const { signAndSubmitTransaction, account } = useWallet();

async function removeMultipleCLMMLiquidity() {
    const params: RemoveMultipleCLMMLiquidityParams = {
        poolId: '0xpool',
        positions: [
            {
                positionAddr: '0xposition1',
                mintedShare: 10000,
                minAmount0: 10000,
                minAmount1: 10000,
            },
            {
                positionAddr: '0xposition2',
                mintedShare: 20000,
                minAmount0: 20000,
                minAmount1: 20000,
            }
        ]
    }
    const data = sdk.Position.removeMultipleCLMMLiquidity(params);

    await signAndSubmitTransaction({
        sender: account.address,
        data: data
    });
}

Stable

Removes liquidity from single or multiple STABLE positions.

Single

Use sdk.Position.removeSingleStableLiquidity method

Params:

poolId: string The ID of the stable pool.
liquidityType: LiquidityType.
- LiquidityType.SingleAsset: Single asset withdrawal
- LiquidityType.Imbalance: Imbalance withdrawal
- LiquidityType.Ratio: Ratio Withdrawal
position: The position object with (when liquidityType == LiquidityType.SingleAsset):
- positionAddr: string The address of the individual liquidity position.
- amount: number The minimum token amount to receive
- mintedShare: number The amount of share tokens to burn.
- tokenOutIndex: number The token index to receive.
position: The position object with (when liquidityType == LiquidityType.Imbalance):
- positionAddr: string The address of the individual liquidity position.
- maxMintedShare: number The maximum amount of share tokens to burn.
- amounts: number[] The minimum token amounts to receive.
position: The position object with (when liquidityType == LiquidityType.Ratio):
- positionAddr: string The address of the individual liquidity position.
- mintedShare: number The amount of share tokens to burn.
- amounts: number[] The minimum token amounts to receive.


const { signAndSubmitTransaction, account } = useWallet();

 
async function removeSingleStableLiquidity() {
    // use one of the followings

    // - liquidity type: LiquidityType.SingleAsset
    const params: RemoveSingleStableLiquidityParams = {
        poolId: '0xpool',
        liquidityType: LiquidityType.SingleAsset,
        position: {
           amount: 100,
           mintedShare: 10000,
           positionAddr: '0xposition',
           tokenOutIndex: 0,
        }
    }

    // - or liquidity type: LiquidityType.Imbalance
    const params: RemoveSingleStableLiquidityParams = {
        poolId: '0xpool',
        liquidityType: LiquidityType.Imbalance,
        position: {
            positionAddr: '0xposition',
            amounts: [100, 200, 300],
            maxMintedShare: 10000,
        }
    }

    // - or liquidity type: LiquidityType.Ratio
    const params: RemoveSingleStableLiquidityParams = {
        poolId: '0xpool',
        liquidityType: LiquidityType.Ratio,
        position: {
            positionAddr: '0xposition',
            mintedShare: 10000,
            amounts: [100, 200, 300]
        }
    }
    const data = sdk.Position.removeSingleStableLiquidity(params);

    await signAndSubmitTransaction({
        sender: account.address,
        data: data
    });
}

Multiple

Use sdk.Position.removeMultipleStableLiquidity method

Params

poolId: string The ID of the stable pool.
liquidityType: LiquidityType.
- LiquidityType.SingleAsset: Single asset withdrawal
- LiquidityType.Imbalance: Imbalance withdrawal
- LiquidityType.Ratio: Ratio Withdrawal
positions: An array of position objects, each containing (when liquidityType == LiquidityType.SingleAsset):
- positionAddr: string The address of the individual liquidity position.
- amount: number The minimum token amount to receive
- mintedShare: number The amount of share tokens to burn.
- tokenOutIndex: number The token index to receive.
positions: An array of position objects, each containing (when liquidityType == LiquidityType.Imbalance):
- positionAddr: string The address of the individual liquidity position.
- maxMintedShare: number The maximum amount of share tokens to burn.
- amounts: number[] The minimum token amounts to receive.
positions: An array of position objects, each containing (when liquidityType == LiquidityType.Ratio):
- positionAddr: string The address of the individual liquidity position.
- mintedShare: number The amount of share tokens to burn.
- amounts: number[] The minimum token amounts to receive.

const { signAndSubmitTransaction, account } = useWallet();

async function removeMultipleStableLiquidity() {
     // use one of the followings

     // - liquidity type: LiquidityType.SingleAsset
    const params: RemoveMultipleStableLiquidityParams = {
        poolId: '0xpool',
        liquidityType: LiquidityType.SingleAsset,
        positions: [
            {
                amount: 100,
                mintedShare: 10000,
                positionAddr: '0xposition1',
                tokenOutIndex: 0,
            },
            {
               amount: 100,
               mintedShare: 10000,
               positionAddr: '0xposition2',
               tokenOutIndex: 1,
            }
        ]
    }

     // - or liquidity type: LiquidityType.Imbalance
    const params: RemoveMultipleStableLiquidityParams = {
        poolId: '0xpool',
        liquidityType: LiquidityType.Imbalance,
        positions: [
            {
                positionAddr: '0xposition1',
                amounts: [100, 200, 300],
                maxMintedShare: 10000,
            },
            {
                positionAddr: '0xposition2',
                amounts: [300, 400, 500],
                maxMintedShare: 10000,
                
            }
        ]
    }

    // - or liquidity type: LiquidityType.Ratio
    const params: RemoveMultipleStableLiquidityParams = {
        poolId: '0xpool',
        liquidityType: LiquidityType.Ratio,
        positions: [
            {
                positionAddr: '0xposition1',
                mintedShare: 10000,
                amounts: [100, 200, 300]
            },
            {
                positionAddr: '0xposition2',
                mintedShare: 10000,
                amounts: [300, 400, 500]
            }
        ]
    }
    const data = sdk.Position.removeMultipleStableLiquidity(params);

    await signAndSubmitTransaction({
        sender: account.address,
        data: data
    });
}

Add Liquidity to Existing Pools

AMM

Adds liquidity to an AMM pool.

Params

poolId: string The ID of the AMM pool.
amountA: number The amount of token A to add as liquidity.
amountB: number The amount of token B to add as liquidity.

const txData = sdk.Position.addAMMLiquidity({
  poolId: '0xpool',
  amountA: 10000000000,
  amountB: 10000000000,
});

CLMM

Adds liquidity to a CLMM pool.

Params

poolId: string The unique identifier of the CLMM pool.
amountA: number The amount of token A to add.
amountB: number The amount of token B to add.
fee: number The fee tier of the pool.
isMaxAmountB: boolean Whether the second token amount (amountB) is flexible based on slippage (e.g. if true, it means amountB can be less than specified due to price movement).
minPrice: number The minimum price the liquidity range.
maxPrice: number The maximum price the liquidity range.

const txData = sdk.Position.addCLMMLiquidity({
  poolId: '0xpool',
  amountA: 10000000000,
  amountB: 10000000000,
  fee: 3000,
  isMaxAmountB: true,
  minPrice: 0.00001,
  maxPrice: 100000,
});

Stable

Adds liquidity to a stable pool.

Params

poolId: string The ID of the stable pool.
amounts: number[] An array of token amounts.

const txData = sdk.Position.addStableLiquidity({
  poolId: '0xpool',
  amounts: [10000000000, 20000000000],
});

Collect Fee

Collects fees from a specific liquidity position in a given pool.

Use sdk.Position.collectFee method. Params

poolId: string The address of the pool from which to collect fees.
positionAddr: string The address of the liquidity position.

const { signAndSubmitTransaction, account } = useWallet();

async function collectFee() {
    const params: CollectFeeParams = {
        poolId: "0xpool",
        positionAddr: "0xposition"
    }
    const data = sdk.Position.collectFee(params);

    await signAndSubmitTransaction({
        sender: account.address,
        data: data
    });
}

Position

Retrieves a paginated list of liquidity positions for a given user address.

Use sdk.Position.getPositions method.

Params:

userAddr: string The user's wallet address to fetch positions for.
page (optional): number The page number for pagination (defaults to 1).
size (optional): number The number of results per page (defaults to 10).

const { signAndSubmitTransaction, account } = useWallet();

async function getPositions() {
    const data = await sdk.Position.getPositions({
        userAddr: "0xuser",
        page: 1,
        size: 10
    });

    console.log(data)
}

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

TAPP Decentralized Exchange SDK

📚 Table of Contents

Installation

Initialization

Pool

Get Pool List

Get Specific Pool Info

Swap

Estimate Swap Amount

Get Swap Route

AMM Swap

CLMM Swap

Stable Swap

Estimate SOR Swap Amount

SOR Swap

Liquidity

Create Pool and Add Liquidity

AMM

CLMM

Stable

Remove Liquidity

AMM

CLMM

Stable

Add Liquidity to Existing Pools

AMM

CLMM

Stable

Collect Fee

Position

Position