AlphaLend JavaScript SDK

AlphaLend SDK for JavaScript/TypeScript applications built on the Sui blockchain. This SDK provides a comprehensive interface to interact with the AlphaLend lending protocol.

Features

• Supply assets as collateral
• Borrow assets against your collateral
• Repay borrowed assets
• Withdraw collateral
• Zap-in supply: Swap any token and supply as collateral in one transaction
• Zap-in withdraw: Withdraw collateral and swap to any token in one transaction
• Claim rewards
• Liquidate unhealthy positions
• Query protocol metrics and market data
• Track user portfolios and positions

Installation

npm install @alphafi/alphalend-sdk

v3.0.0 — Mysten Sui v2 / ESM-only (breaking)

• @mysten/sui v2 peer dependency (^2.17.0). Your app must provide it. Internally SuiClient/getFullnodeUrl were replaced with v2's SuiJsonRpcClient/getJsonRpcFullnodeUrl (from @mysten/sui/jsonRpc).
• ESM-only. The CommonJS build (dist/cjs) and the require export were dropped — require('@alphafi/alphalend-sdk') no longer works. Import it from an ESM context or via a bundler.
• No postinstall / patches. Earlier work-in-progress used a patch-package hook to fix @naviprotocol/lending under v2; that would have broken consumer installs. The flash-loan helpers are now vendored (src/vendor/naviFlashloan.ts), so installing this package runs no lifecycle scripts and pulls no Navi dependency.

Getting Started

Creating an instance of the AlphaLend client

import { AlphalendClient, Network } from "alphalend-sdk";

// Create AlphaLend client instance (uses default public GraphQL endpoint)
const alphalendClient = new AlphalendClient("mainnet");

// Or pass a custom GraphQL endpoint (e.g. a private proxy)
const alphalendClientCustom = new AlphalendClient(
  "mainnet",
  "https://my-graphql-proxy.example.com/graphql",
);

The constructor's network argument is typed as Network = "mainnet" | "testnet" | "devnet". Network is exported from the SDK so TypeScript callers can plumb the literal type through their own config without falling back to string.

Migrating from 1.x to 2.x

2.0.0 drops the JSON-RPC SuiClient from the public API. All reads now go through Sui's GraphQL endpoint.

| Before (1.x) | After (2.x) | | ---------------------------------------------------- | --------------------------------------------------------- | | new AlphalendClient("mainnet", suiClient) | new AlphalendClient("mainnet") | | new AlphalendClient("mainnet", suiClient, options) | new AlphalendClient("mainnet", undefined, options) | | new LendingProtocol("mainnet", suiClient) | new LendingProtocol("mainnet") | | getUserPositionCapId(suiClient, network, address) | getUserPositionCapId(blockchain, address) | | getUserPositionCapIds(suiClient, network, address) | getUserPositionCapIds(blockchain, address) | | getUserPositionIds(suiClient, network, address) | getUserPositionIds(blockchain, address) | | getAlphaReceipt(suiClient, address) | getAlphaReceipt(blockchain, address) | | receipt.content.type / receipt.content.fields.* | receipt.objectId / receipt.fields.* | | alc.getEstimatedGasBudget(suiClient, tx, address) | alc.getEstimatedGasBudget(tx, address) | | network: string (constructor arg) | network: Network ("mainnet" \| "testnet" \| "devnet") | | MarketType.priceIdentifier = { coinType, type } | MarketType.priceIdentifier = { coinType } |

Receipt is a breaking shape change in 2.x: the SDK now returns receipts as { objectId, fields } (GraphQL-flat), so any consumer reading receipt.content.type or receipt.content.fields.* must migrate to receipt.objectId and receipt.fields.*.

Update Prices

import { Transaction } from "@mysten/sui/transactions";

// Create a transaction
const tx = new Transaction();

// Update price information for assets from Pyth oracle
await alphalendClient.updatePrices(tx, [
  "0x2::sui::SUI",
  "0x5d4b302506645c37ff133b98c4b50a5ae14841659738d6d733d59d0d217a93bf::coin::USDC",
  // Add other coin types as needed
]);

// Set gas budget and execute the transaction
const wallet = await import("@mysten/wallet-kit");
tx.setGasBudget(100_000_000);
await wallet.signAndExecuteTransaction(tx);

Supply Collateral

import { Transaction } from "@mysten/sui/transactions";

// Supply tokens as collateral
const supplyParams = {
  marketId: "1", // Market ID to supply to
  amount: 1000000000n, // Amount in lowest denomination (in mists)
  coinType: "0x2::sui::SUI", // Coin type to supply
  positionCapId: "0xYOUR_POSITION_CAP_ID", // Optional: your position capability
  address: "0xYOUR_ADDRESS", // Address of the user supplying collateral
};

// Create supply transaction
const supplyTx = await alphalendClient.supply(supplyParams);

// Set gas budget and execute the transaction
const wallet = await import("@mysten/wallet-kit");
await wallet.signAndExecuteTransaction(supplyTx);

Borrow Assets

import { Transaction } from "@mysten/sui/transactions";

// Borrow against your collateral
const borrowParams = {
  marketId: "2", // Market ID to borrow from
  amount: 500000000n, // Amount to borrow (in mists)
  coinType:
    "0x5d4b302506645c37ff133b98c4b50a5ae14841659738d6d733d59d0d217a93bf::coin::USDC", // Coin type to borrow
  positionCapId: "0xYOUR_POSITION_CAP_ID", // Your position capability
  address: "0xYOUR_ADDRESS", // Address of the user
  priceUpdateCoinTypes: [
    "0x5d4b302506645c37ff133b98c4b50a5ae14841659738d6d733d59d0d217a93bf::coin::USDC",
    "0x2::sui::SUI",
  ], // Coin types to update prices for
};

// Create borrow transaction
const borrowTx = await alphalendClient.borrow(borrowParams);

// Execute the transaction
await wallet.signAndExecuteTransaction(borrowTx);

Repay Borrowed Assets

import { Transaction } from "@mysten/sui/transactions";

// Repay borrowed assets
const repayParams = {
  marketId: "2", // Market ID where debt exists
  amount: 500000000n, // Amount to repay (in mists)
  coinType:
    "0x5d4b302506645c37ff133b98c4b50a5ae14841659738d6d733d59d0d217a93bf::coin::USDC", // Coin type to repay
  positionCapId: "0xYOUR_POSITION_CAP_ID", // Your position capability
  address: "0xYOUR_ADDRESS", // Address of the user repaying the debt
};

// Create repay transaction
const repayTx = await alphalendClient.repay(repayParams);

// Execute the transaction
await wallet.signAndExecuteTransaction(repayTx);

Withdraw Collateral

import { Transaction } from "@mysten/sui/transactions";
import { MAX_U64 } from "alphalend-sdk";

// Withdraw collateral (partial amount)
const withdrawParams = {
  marketId: "1", // Market ID to withdraw from
  amount: 500000000n, // Amount to withdraw (in mists)
  coinType: "0x2::sui::SUI", // Coin type to withdraw
  positionCapId: "0xYOUR_POSITION_CAP_ID", // Your position capability
  address: "0xYOUR_ADDRESS", // Address of the user
  priceUpdateCoinTypes: ["0x2::sui::SUI"], // Coin types to update prices for
};

// To withdraw all collateral, use MAX_U64
const withdrawAllParams = {
  marketId: "1",
  amount: MAX_U64, // Special value to withdraw all collateral
  coinType: "0x2::sui::SUI",
  positionCapId: "0xYOUR_POSITION_CAP_ID",
  address: "0xYOUR_ADDRESS",
  priceUpdateCoinTypes: ["0x2::sui::SUI"], // Coin types to update prices for
};

// Create withdraw transaction
const withdrawTx = await alphalendClient.withdraw(withdrawParams);

// Execute the transaction
await wallet.signAndExecuteTransaction(withdrawTx);

Zap-in Supply (Swap and Supply in One Transaction)

import { Transaction } from "@mysten/sui/transactions";

// Swap any token and supply as collateral in a single transaction
const zapInSupplyParams = {
  marketId: "1", // Market ID where collateral is being added
  inputAmount: 1000000000n, // Amount of input tokens to swap (in mists)
  inputCoinType:
    "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC", // Token to swap from (USDC)
  marketCoinType: "0x2::sui::SUI", // Market's collateral token to swap to (SUI)
  slippage: 0.01, // Maximum allowed slippage (1%)
  positionCapId: "0xYOUR_POSITION_CAP_ID", // Optional: your position capability
  address: "0xYOUR_ADDRESS", // Address of the user
};

// Create zap-in supply transaction
const zapInSupplyTx = await alphalendClient.zapInSupply(zapInSupplyParams);

if (zapInSupplyTx) {
  // Execute the transaction
  await wallet.signAndExecuteTransaction(zapInSupplyTx);
} else {
  console.error("Failed to create zap-in supply transaction");
}

Zap-in Withdraw (Withdraw and Swap in One Transaction)

import { Transaction } from "@mysten/sui/transactions";
import { MAX_U64 } from "alphalend-sdk";

// Withdraw collateral and swap to desired token in a single transaction
const zapOutWithdrawParams = {
  marketId: "1", // Market ID from which to withdraw
  amount: 500000000n, // Amount to withdraw (in mists)
  marketCoinType: "0x2::sui::SUI", // Market's collateral token type (SUI)
  outputCoinType:
    "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC", // Token to swap to (USDC)
  slippage: 0.01, // Maximum allowed slippage (1%)
  positionCapId: "0xYOUR_POSITION_CAP_ID", // Your position capability
  address: "0xYOUR_ADDRESS", // Address of the user
  priceUpdateCoinTypes: [
    "0x2::sui::SUI",
    "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
  ], // Coin types to update prices for
};

// To withdraw all collateral and swap, use MAX_U64
const zapOutWithdrawAllParams = {
  marketId: "1",
  amount: MAX_U64, // Special value to withdraw all collateral
  marketCoinType: "0x2::sui::SUI",
  outputCoinType:
    "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
  slippage: 0.01,
  positionCapId: "0xYOUR_POSITION_CAP_ID",
  address: "0xYOUR_ADDRESS",
  priceUpdateCoinTypes: [
    "0x2::sui::SUI",
    "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
  ],
};

// Create zap-out withdraw transaction
const zapOutWithdrawTx =
  await alphalendClient.zapOutWithdraw(zapOutWithdrawParams);

if (zapOutWithdrawTx) {
  // Execute the transaction
  await wallet.signAndExecuteTransaction(zapOutWithdrawTx);
} else {
  console.error("Failed to create zap-out withdraw transaction");
}

Claim Rewards

import { Transaction } from "@mysten/sui/transactions";

// Claim accrued rewards
const claimRewardsParams = {
  positionCapId: "0xYOUR_POSITION_CAP_ID", // Your position capability
  address: "0xYOUR_ADDRESS", // Address of the user claiming rewards
  claimAndDepositAlpha: true, // Whether to claim and deposit Alpha token rewards
  claimAndDepositAll: true, // Whether to claim and deposit all other reward tokens
  // DEPRECATED: Use claimAndDepositAlpha and claimAndDepositAll instead
  // claimAlpha: true, // ⚠️ DEPRECATED - use claimAndDepositAlpha instead
  // claimAll: true,  // ⚠️ DEPRECATED - use claimAndDepositAll instead
};

// Create claim rewards transaction
const claimRewardsTx = await alphalendClient.claimRewards(claimRewardsParams);

// Execute the transaction
await wallet.signAndExecuteTransaction(claimRewardsTx);

Liquidate Unhealthy Position

import { Transaction } from "@mysten/sui/transactions";

// Create a transaction
const tx = new Transaction();

// Get a coin to use for repayment
const repayAmount = 500000000n;
const repayCoin = await someFunction.getCoinForRepayment(tx, repayAmount);

// Liquidate an unhealthy position
const liquidateParams = {
  tx: tx, // Optional: use existing transaction
  liquidatePositionId: "0xPOSITION_ID_TO_LIQUIDATE", // Position to liquidate
  borrowMarketId: "2", // Market ID where debt is repaid
  withdrawMarketId: "1", // Market ID where collateral is seized
  repayCoin: repayCoin, // Transaction argument for repay coin
  borrowCoinType:
    "0x5d4b302506645c37ff133b98c4b50a5ae14841659738d6d733d59d0d217a93bf::coin::USDC", // Coin type of debt
  withdrawCoinType: "0x2::sui::SUI", // Coin type of collateral to seize
  priceUpdateCoinTypes: [
    "0x5d4b302506645c37ff133b98c4b50a5ae14841659738d6d733d59d0d217a93bf::coin::USDC",
    "0x2::sui::SUI",
  ], // Coin types to update prices for
};

// Liquidate the position
const [repaidCoin, seizedCoin] =
  await alphalendClient.liquidate(liquidateParams);

// Transfer the seized collateral to the liquidator
tx.transferObjects([seizedCoin], "0xLIQUIDATOR_ADDRESS");

// Execute the transaction
await wallet.signAndExecuteTransaction(tx);

Types

The SDK includes TypeScript definitions for all operations, making it easy to use in TypeScript projects:

• SupplyParams: Parameters for supplying collateral

  • marketId: Market ID where collateral is being added
  • amount: Amount to supply as collateral in base units (bigint, in mists)
  • coinType: Fully qualified coin type to supply (e.g., "0x2::sui::SUI")
  • positionCapId?: Object ID of the position capability object (optional)
  • address: Address of the user supplying collateral

• WithdrawParams: Parameters for withdrawing collateral

  • marketId: Market ID from which to withdraw
  • amount: Amount to withdraw in base units (bigint, in mists, use MAX_U64 constant to withdraw all)
  • coinType: Fully qualified coin type to withdraw (e.g., "0x2::sui::SUI")
  • positionCapId: Object ID of the position capability object
  • address: Address of the user withdrawing collateral
  • priceUpdateCoinTypes: Array of coin types to update prices for

• BorrowParams: Parameters for borrowing assets

  • marketId: Market ID to borrow from
  • amount: Amount to borrow in base units (bigint, in mists)
  • coinType: Fully qualified coin type to borrow (e.g., "0x2::sui::SUI")
  • positionCapId: Object ID of the position capability object
  • address: Address of the user borrowing tokens
  • priceUpdateCoinTypes: Array of coin types to update prices for

• RepayParams: Parameters for repaying borrowed assets

  • marketId: Market ID where the debt exists
  • amount: Amount to repay in base units (bigint, in mists)
  • coinType: Fully qualified coin type to repay (e.g., "0x2::sui::SUI")
  • positionCapId: Object ID of the position capability object
  • address: Address of the user repaying the debt

• ClaimRewardsParams: Parameters for claiming rewards

  • positionCapId: Object ID of the position capability object
  • address: Address of the user claiming rewards
  • claimAndDepositAlpha: Whether to claim and deposit Alpha token rewards (boolean)
  • claimAndDepositAll: Whether to claim and deposit all other reward tokens (boolean)
  • claimAlpha: ⚠️ DEPRECATED - Use claimAndDepositAlpha instead (boolean)
  • claimAll: ⚠️ DEPRECATED - Use claimAndDepositAll instead (boolean)

• LiquidateParams: Parameters for liquidating unhealthy positions

  • tx?: Optional existing transaction to build upon
  • liquidatePositionId: Object ID of the position to liquidate
  • borrowMarketId: Market ID where debt is repaid
  • withdrawMarketId: Market ID where collateral is seized
  • repayCoin: Transaction argument representing the repay coin
  • borrowCoinType: Fully qualified coin type for debt repayment
  • withdrawCoinType: Fully qualified coin type for collateral to seize
  • priceUpdateCoinTypes: Array of coin types to update prices for

• ZapInSupplyParams: Parameters for zap-in supply operation (swap and supply in one transaction)

  • marketId: Market ID where collateral is being added
  • inputAmount: Amount of input tokens to swap and supply (bigint, in mists)
  • inputCoinType: Fully qualified type of the input token to swap from (e.g., "0x2::sui::SUI")
  • marketCoinType: Fully qualified type of the market's collateral token to swap to
  • slippage: Maximum allowed slippage percentage for the swap (e.g., 0.01 for 1%)
  • positionCapId?: Object ID of the position capability object (optional)
  • address: Address of the user performing the zap-in supply

• ZapOutWithdrawParams: Parameters for zap-out withdraw operation (withdraw and swap in one transaction)

  • marketId: Market ID from which to withdraw
  • amount: Amount to withdraw (bigint, in mists, use MAX_U64 constant to withdraw all)
  • marketCoinType: Fully qualified type of the market's collateral token to withdraw from
  • outputCoinType: Fully qualified type of the desired output token to swap to
  • slippage: Maximum allowed slippage percentage for the swap (e.g., 0.01 for 1%)
  • positionCapId: Object ID of the position capability object
  • address: Address of the user performing the zap-in withdraw
  • priceUpdateCoinTypes: Array of coin types to update prices for

• updatePrices: Function to update price feeds

  • Parameters:
    • tx: Transaction object to add price update calls to
    • coinTypes: Array of fully qualified coin types to update prices for

Query Methods

Get All Markets

// Get all markets with their details
const markets = await alphalendClient.getAllMarkets();

console.log(markets);
// Example output:
// [
//   {
//     marketId: "1",
//     price: new Decimal("1.546187202"),
//     coinType: "0x2::sui::SUI",
//     decimalDigit: 9,
//     totalSupply: new Decimal("1000000000"),
//     totalBorrow: new Decimal("500000000"),
//     utilizationRate: new Decimal("0.5"),
//     supplyApr: {
//       interestApr: new Decimal("0.04"),
//       rewards: [
//         { coinType: "0x..::alpha::ALPHA", rewardApr: new Decimal("0.02") }
//       ]
//     },
//     borrowApr: {
//       interestApr: new Decimal("0.1"),
//       rewards: []
//     },
//     ltv: new Decimal("0.7"),
//     liquidationThreshold: new Decimal("0.8"),
//     availableLiquidity: new Decimal("500000000"),
//     borrowFee: new Decimal("0.001"),
//     allowedBorrowAmount: new Decimal("10000000000"),
//     allowedDepositAmount: new Decimal("1000000000000"),
//     borrowWeight: new Decimal("1"),
//     xtokenRatio: new Decimal("1.05")
//   },
//   // ... more markets
// ]

Get market data for a particular market

// Get market data for a particular market
const marketData = await alphalendClient.getMarketDataFromId(1);

Get Markets Chain Data (Caching)

// Get market chain data for caching and reuse
const marketsChain = await alphalendClient.getMarketsChain();

// Later use the cached markets with other functions

Get All Markets with Cached Markets

// Use cached markets to get market data more efficiently
const marketsChain = await alphalendClient.getMarketsChain();
const markets =
  await alphalendClient.getAllMarketsWithCachedMarkets(marketsChain);

console.log(markets);
// Same output format as getAllMarkets but more efficient when called multiple times

Get Protocol Stats

// Get protocol statistics
const stats = await alphalendClient.getProtocolStats();

console.log(stats);
// Example output:
// {
//   totalSuppliedUsd: "1000000.00", // Total value supplied across all markets (USD)
//   totalBorrowedUsd: "500000.00"   // Total value borrowed across all markets (USD)
// }

Get User Portfolio

// Get user portfolio information including supplied/borrowed assets
const userPortfolio = await alphalendClient.getUserPortfolio("0xUSER_ADDRESS");

console.log(userPortfolio);
// Example output:
// [
//   {
//     positionId: "0x...",
//     netWorth: new Decimal("1500.00"),
//     dailyEarnings: new Decimal("0.82"),
//     netApr: new Decimal("0.02"),
//     safeBorrowLimit: new Decimal("700.00"),
//     borrowLimitUsed: new Decimal("0.35"),
//     liquidationThreshold: new Decimal("800.00"),
//     totalSuppliedUsd: new Decimal("1000.00"),
//     aggregatedSupplyApr: new Decimal("0.04"),
//     totalBorrowedUsd: new Decimal("300.00"),
//     aggregatedBorrowApr: new Decimal("0.08"),
//     suppliedAmounts: new Map([
//       [1, new Decimal("100000000000")], // Key is marketId, value is amount
//       [3, new Decimal("50000000")]
//     ]),
//     borrowedAmounts: new Map([
//       [2, new Decimal("300000000")]
//     ]),
//     rewardsToClaimUsd: new Decimal("5.72"),
//     rewardsToClaim: [
//       {
//         coinType: "0x..::alpha::ALPHA",
//         rewardAmount: new Decimal("10.5")
//       }
//     ]
//   }
// ]

Get User Portfolio with Cached Markets

// Get user portfolio using cached markets for better performance
const marketsChain = await alphalendClient.getMarketsChain();
const userPortfolio = await alphalendClient.getUserPortfolioWithCachedMarkets(
  "0xUSER_ADDRESS",
  marketsChain,
);

// Same output format as getUserPortfolio but more efficient when retrieving multiple portfolios
// or when used in combination with other market data queries

Get User Portfolio from Position

// Get user portfolio information for a specific position ID
const userPortfolio =
  await alphalendClient.getUserPortfolioFromPosition("0xPOSITION_ID");

console.log(userPortfolio);
// Example output:
// {
//   positionId: "0x...",
//   netWorth: new Decimal("1500.00"),
//   dailyEarnings: new Decimal("0.82"),
//   netApr: new Decimal("0.02"),
//   safeBorrowLimit: new Decimal("700.00"),
//   borrowLimitUsed: new Decimal("0.35"),
//   liquidationThreshold: new Decimal("800.00"),
//   totalSuppliedUsd: new Decimal("1000.00"),
//   aggregatedSupplyApr: new Decimal("0.04"),
//   totalBorrowedUsd: new Decimal("300.00"),
//   aggregatedBorrowApr: new Decimal("0.08"),
//   suppliedAmounts: new Map([
//     [1, new Decimal("100000000000")], // Key is marketId, value is amount
//     [3, new Decimal("50000000")]
//   ]),
//   borrowedAmounts: new Map([
//     [2, new Decimal("300000000")]
//   ]),
//   rewardsToClaimUsd: new Decimal("5.72"),
//   rewardsToClaim: [
//     {
//       coinType: "0x..::alpha::ALPHA",
//       rewardAmount: new Decimal("10.5")
//     }
//   ]
// }

Testing