AlphaFi SDK for JavaScript

A comprehensive TypeScript/JavaScript SDK for interacting with the AlphaFi DeFi platform on Sui blockchain. This SDK provides seamless integration with multiple DeFi protocols and strategies including lending, LP farming, leveraged yield farming, and more.

Features

Multi-Protocol Support: Bluefin, Navi, Cetus, Bucket, AlphaLend, and AlphaFi protocols
Complete DeFi Suite: Deposits, withdrawals, swaps, portfolio management, and reward claims
Advanced Strategies: Lending, LP farming, leveraged yield farming (LYF), looping, and Alpha vaults
Portfolio Management: Real-time portfolio tracking with aggregated metrics and alpha rewards
Token Swaps: Integrated Cetus aggregator for optimal token routing
Type Safety: Full TypeScript support with comprehensive type definitions
Options-Based API: Consistent, easy-to-use interface across all methods

Installation

npm install @alphafi/alphafi-sdk

Quick Start

import { AlphaFiSDK } from '@alphafi/alphafi-sdk';
import { SuiClient } from '@mysten/sui/client';

// Initialize the SDK
const suiClient = new SuiClient({ url: 'https://fullnode.mainnet.sui.io:443' });
const sdk = new AlphaFiSDK({
  suiClient,
  network: 'mainnet',
});

const userAddress = 'your_sui_address_here';

// Get all available pools
const pools = await sdk.getPoolsData();
console.log('Available pools:', pools);

// Get user portfolio
const portfolio = await sdk.getUserPortfolio(userAddress);
console.log('Portfolio:', {
  netWorth: portfolio.netWorth.toString(),
  aggregatedApy: portfolio.aggregatedApy.toString(),
  alphaRewards: portfolio.alphaRewardsToClaim.toString(),
});

// Build an unsigned deposit transaction
const depositTx = await sdk.deposit({
  poolId: '0x...', // Pool ID
  address: userAddress,
  amount: 1000000000n, // 1 SUI in base units
  isAmountA: true, // For LP pools: which token this amount represents
});
// Sign & execute with your wallet / client
// await suiClient.signAndExecuteTransactionBlock({ transactionBlock: depositTx, signer });

// Build an unsigned withdraw transaction
const withdrawTx = await sdk.withdraw({
  poolId: '0x...',
  address: userAddress,
  amount: '500000000', // Amount to withdraw
  withdrawMax: false, // Set to true to withdraw entire position
});

// Claim all rewards (builds unsigned transaction)
const claimTx = await sdk.claim({
  address: userAddress,
});

How transactions work: deposit, withdraw, zapDeposit, swaps, and reward helpers return unsigned Transaction objects from @mysten/sui/transactions. You must sign and execute them with your wallet or client of choice.

Amounts & precision:

Deposits and zap inputs use bigint in base units (1000000000n = 1 SUI).

Withdraw inputs and most quotes use string for flexibility across strategies.

Responses return Decimal instances (from decimal.js) to avoid floating-point errors.

Supported Protocols

Bluefin Protocol

Pool Types: SUI-USDC, USDT-USDC, STSUI-SUI, and more
Strategies: Regular liquidity pools, autobalance pools, fungible pools
Special Features: Support for different tick ranges (175, zero-zero)

Navi Protocol

Pool Types: Single-asset pools (SUI, USDC, USDT, etc.)
Strategies: Regular lending, looping strategies
Special Features: Support for NAVI-LOOP pools with supply/borrow mechanics

Cetus Protocol

Pool Types: CETUS-SUI, ALPHA-SUI, and other trading pairs
Strategies: Concentrated liquidity with tick-based ranges
Special Features: Support for different pool configurations

Bucket Protocol

Pool Types: BUCK token pools
Strategies: Single-asset staking
Special Features: Simple deposit/withdraw mechanics

AlphaLend Protocol

Pool Types: SUI-STSUI looping, single-loop pools (TBTC, SUIBTC, XAUM)
Strategies: Looping strategies, single-asset looping
Special Features: Advanced lending strategies with leverage

API Reference

AlphaFiSDK Class

Constructor

new AlphaFiSDK(config: AlphaFiSDKConfig)

Configuration Interface

interface AlphaFiSDKConfig {
  suiClient: SuiClient; // Sui blockchain client
  network: 'mainnet' | 'testnet' | 'devnet' | 'localnet';
}

Core Methods

getPoolsData(strategiesType?: StrategyType[]): Promise<Map<string, PoolData>>

Get comprehensive data for all available DeFi pools.

const pools = await sdk.getPoolsData(['Lending', 'Lp']); // Filter by strategy types
const allPools = await sdk.getPoolsData(); // Get all pools

getSinglePoolData(poolId: string): Promise<PoolData>

Get data for a single pool.

const poolData = await sdk.getSinglePoolData('0x...'); // Get data for specific pool

getUserSinglePoolBalance(address: string, poolId: string): Promise<PoolBalance>

Get balance for a single pool.

const balance = await sdk.getUserSinglePoolBalance(userAddress, '0x...');

getUserPortfolio(address: string, strategiesType?: StrategyType[]): Promise<UserPortfolioData>

Get complete portfolio summary for a user address.

const portfolio = await sdk.getUserPortfolio(userAddress);
console.log({
  netWorth: portfolio.netWorth.toString(),
  aggregatedApy: portfolio.aggregatedApy.toString(),
  alphaRewards: portfolio.alphaRewardsToClaim.toString(),
  poolBalances: portfolio.poolBalances,
});

Transaction Methods

deposit(options: DepositOptions): Promise<Transaction>

Build an unsigned transaction to deposit assets into a DeFi pool.

interface DepositOptions {
  poolId: string; // Unique pool identifier
  address: string; // User's wallet address
  amount: bigint; // Amount in base units
  isAmountA?: boolean; // For LP pools: which token this amount represents
}

withdraw(options: WithdrawOptions): Promise<Transaction>

Build an unsigned transaction to withdraw assets from a DeFi pool.

interface WithdrawOptions {
  poolId: string; // Unique pool identifier
  address: string; // User's wallet address
  amount: string; // Amount to withdraw (ignored if withdrawMax is true)
  isAmountA?: boolean; // For LP pools: specify withdrawal in terms of token A
  withdrawMax: boolean; // If true, withdraw entire position
}

estimateLpAmounts(options: EstimateLpAmountsOptions): Promise<[string, string]>

Calculate required token amounts for balanced LP deposits.

interface EstimateLpAmountsOptions {
  poolId: string; // LP pool identifier
  amount: string; // Input token amount
  isAmountA: boolean; // True if amount refers to token A
}

claim(options: ClaimOptions): Promise<Transaction>

Build an unsigned transaction to claim accumulated rewards (all pools or a specific pool).

interface ClaimOptions {
  address: string; // User's wallet address
  poolId?: string; // Optional: specific pool ID
}

dev-testing

replace the code in fetchPoolLabelsByIds with the below code block to test transactions with testing pools.

const { TEST_POOLS } = await import('../utils/testing-pools.js');
for (const pool of TEST_POOLS) {
  poolLabels.set(pool.poolId, pool);
}

vote(voteIndex: number, proposalId: string): Promise<Transaction | undefined>

Build an unsigned transaction to vote on a governance proposal.

// voteIndex: The index of the vote to cast (e.g. 0 = Against, 1 = For, etc.)
// proposalId: The object ID of the proposal to vote on
const voteTx = await sdk.vote(1, '0x...'); // Vote "For" on proposal 0x...
// Sign & execute with your wallet / client

Returns undefined if voteIndex is undefined (and logs an error). Otherwise returns a Transaction ready for signing and execution.

Alpha Token Methods

initiateWithdrawAlpha(options: WithdrawOptions): Promise<Transaction>

Initiate ALPHA token withdrawal (creates withdrawal ticket).

claimWithdrawAlpha(options: ClaimWithdrawAlphaOptions): Promise<Transaction>

Complete ALPHA token withdrawal using previously created ticket.

interface ClaimWithdrawAlphaOptions {
  ticketId: string; // Withdrawal ticket ID
  address: string; // User's wallet address
}

claimAirdrop(options: ClaimAirdropOptions): Promise<Transaction>

Claim available airdrop tokens.

interface ClaimAirdropOptions {
  address: string; // User's wallet address
  transferToWallet: boolean; // Whether to transfer directly to wallet
}

Zap Deposit Methods

zapDepositQuote(options: ZapDepositQuoteOptions): Promise<[string, string] | undefined>

Get quote for zap deposit operation (single token to LP).

interface ZapDepositQuoteOptions {
  poolId: string; // LP pool identifier
  inputCoinAmount: bigint; // Input token amount in base units
  isInputA: boolean; // True if input token is token A
  slippage: number; // Max slippage (e.g., 0.005 = 0.5%)
}

zapDeposit(options: ZapDepositOptions): Promise<Transaction | undefined>

Execute zap deposit: convert single token to balanced LP position.

interface ZapDepositOptions {
  poolId: string; // LP pool identifier
  inputCoinAmount: bigint; // Input token amount in base units
  isInputA: boolean; // True if input token is token A
  address: string; // User's wallet address
  slippage: number; // Max slippage (e.g., 0.005 = 0.5%)
}

Token Swap Methods

getCetusSwapQuote(options: CetusSwapQuoteOptions): Promise<RouterDataV3 | undefined>

Get quote for token swap via Cetus aggregator.

interface CetusSwapQuoteOptions {
  from: string; // Source token type/address
  target: string; // Destination token type/address
  amount: string; // Amount to swap in source token units
  byAmountIn: boolean; // True to fix input amount, false to fix output
}

cetusSwapTxb(options: CetusSwapOptions): Promise<Transaction>

Execute token swap using Cetus aggregator.

interface CetusSwapOptions {
  router: RouterDataV3; // Router data from getCetusSwapQuote
  slippage: number; // Max slippage (e.g., 0.01 = 1%)
}

Supported Strategies

The SDK supports multiple DeFi strategies across various protocols:

Strategy Types

Lending: Single-asset yield farming on protocols like Navi and Bucket
Lp: Liquidity provision on AMMs like Cetus and Bluefin
Lyf (Leveraged Yield Farming): Amplified returns with borrowed capital
AutobalanceLp: Self-rebalancing liquidity positions
AlphaVault: Optimized staking for ALPHA tokens
Looping: Leveraged single-asset positions with recursive borrowing
SingleAssetLooping: Single-token leverage strategies
FungibleLp: Fungible liquidity tokens for easy transfer
SlushLending: Slush protocol lending integration

Pool Discovery

Use the SDK methods to discover available pools:

// Get all pools
const allPools = await sdk.getPoolsData();

// Filter by strategy type
const lendingPools = await sdk.getPoolsData(['Lending']);
const lpPools = await sdk.getPoolsData(['Lp', 'AutobalanceLp']);

// Explore pool details
for (const [poolId, poolData] of allPools) {
  console.log(`${poolData.poolName} (${poolId})`, {
    apy: poolData.apr.apy.toString(),
    tvl: poolData.tvl, // contains alphafi and parent TVL; see types section
  });
}

SDK Initialization

import { AlphaFiSDK } from '@alphafi/alphafi-sdk';
import { SuiClient } from '@mysten/sui/client';

const suiClient = new SuiClient({
  url: process.env.SUI_RPC_URL || 'https://fullnode.mainnet.sui.io:443',
});

const sdk = new AlphaFiSDK({
  suiClient,
  network: (process.env.NETWORK as any) || 'mainnet',
});

const userAddress = process.env.USER_ADDRESS;

Data Types

Key Response Types

type AprData = {
  baseApr: Decimal;
  alphaMiningApr: Decimal;
  apy: Decimal;
  lastAutocompounded: Date;
};

type SingleTvl = { tokenAmount: Decimal; usdValue: Decimal };
type DoubleTvl = { tokenAmountA: Decimal; tokenAmountB: Decimal; usdValue: Decimal };
type TvlData =
  | { alphafi: SingleTvl; parent: SingleTvl }
  | { alphafi: DoubleTvl; parent: DoubleTvl };

type PoolData =
  | {
      poolId: string;
      poolName: string;
      apr: AprData;
      tvl: TvlData;
      lpBreakdown: { token1Amount: Decimal; token2Amount: Decimal; totalLiquidity: Decimal };
      parentLpBreakdown: { token1Amount: Decimal; token2Amount: Decimal; totalLiquidity: Decimal };
      currentLPPoolPrice: Decimal;
      positionRange: { lowerPrice: Decimal; upperPrice: Decimal };
    }
  | {
      poolId: string;
      poolName: string;
      apr: AprData;
      tvl: TvlData;
    };

type PoolBalance =
  | { tokenAAmount: Decimal; tokenBAmount: Decimal; usdValue: Decimal }
  | { tokenAmount: Decimal; usdValue: Decimal }
  | {
      stakedAlphaAmount: Decimal;
      stakedAlphaUsdValue: Decimal;
      pendingDeposits: Decimal;
      withdrawals: {
        ticketId: string;
        alphaAmount: string;
        status: number; // 0 pending, 1 accepted, 2 claimable
        withdrawalEtaTimestamp: number;
      }[];
      claimableAirdrop: Decimal;
      totalAirdropClaimed: Decimal;
    };

type UserPortfolioData = {
  netWorth: Decimal;
  aggregatedApy: Decimal;
  alphaRewardsToClaim: Decimal;
  poolBalances: Map<string, PoolBalance>;
};

type StrategyType =
  | 'Lending'
  | 'Lp'
  | 'Lyf'
  | 'AutobalanceLp'
  | 'AlphaVault'
  | 'Looping'
  | 'SingleAssetLooping'
  | 'FungibleLp'
  | 'SlushLending';

Security Guidelines

Never commit your .env file to version control
Store private keys securely and never expose them in client-side code
Use environment variables for sensitive configuration
Always test on testnet first before mainnet deployment
Verify pool IDs and amounts before executing transactions
Check transaction gas estimates before submission
Implement proper error handling for all SDK calls
Use appropriate slippage settings for swaps (typically 0.5-2%)

Support

For issues, questions, or contributions, please refer to the project repository or contact the AlphaFi team.

Name		Name	Last commit message	Last commit date
Latest commit History 285 Commits
.github		.github
scripts		scripts
src		src
.gitignore		.gitignore
.markdownlint.json		.markdownlint.json
.npmignore		.npmignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.prettierrc		.prettierrc
CLAUDE.md		CLAUDE.md
PRE-COMMIT.md		PRE-COMMIT.md
README.md		README.md
eslint.config.mjs		eslint.config.mjs
jest.config.cjs.js		jest.config.cjs.js
package-lock.json		package-lock.json
package.json		package.json
prettier.config.js		prettier.config.js
tsconfig.cjs.json		tsconfig.cjs.json
tsconfig.esm.json		tsconfig.esm.json
tsconfig.json		tsconfig.json
typedoc.json		typedoc.json

Folders and files

Latest commit

History

Repository files navigation

AlphaFi SDK for JavaScript

Features

Installation

Quick Start

Supported Protocols

Bluefin Protocol

Navi Protocol

Cetus Protocol

Bucket Protocol

AlphaLend Protocol

API Reference

AlphaFiSDK Class

Constructor

Configuration Interface

Core Methods

getPoolsData(strategiesType?: StrategyType[]): Promise<Map<string, PoolData>>

getSinglePoolData(poolId: string): Promise<PoolData>

getUserSinglePoolBalance(address: string, poolId: string): Promise<PoolBalance>

getUserPortfolio(address: string, strategiesType?: StrategyType[]): Promise<UserPortfolioData>

Transaction Methods

deposit(options: DepositOptions): Promise<Transaction>

withdraw(options: WithdrawOptions): Promise<Transaction>

estimateLpAmounts(options: EstimateLpAmountsOptions): Promise<[string, string]>

claim(options: ClaimOptions): Promise<Transaction>

dev-testing

vote(voteIndex: number, proposalId: string): Promise<Transaction | undefined>

Alpha Token Methods

initiateWithdrawAlpha(options: WithdrawOptions): Promise<Transaction>

claimWithdrawAlpha(options: ClaimWithdrawAlphaOptions): Promise<Transaction>

claimAirdrop(options: ClaimAirdropOptions): Promise<Transaction>

Zap Deposit Methods

zapDepositQuote(options: ZapDepositQuoteOptions): Promise<[string, string] | undefined>

zapDeposit(options: ZapDepositOptions): Promise<Transaction | undefined>

Token Swap Methods

getCetusSwapQuote(options: CetusSwapQuoteOptions): Promise<RouterDataV3 | undefined>

cetusSwapTxb(options: CetusSwapOptions): Promise<Transaction>

Supported Strategies

Strategy Types

Pool Discovery

SDK Initialization

Data Types

Key Response Types

Security Guidelines

Support

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages