SDK Integration

The Kasu TypeScript SDK (@kasufinance/kasu-sdk) provides a high-level API for external applications and wallets to integrate with Kasu lending pools. It handles contract interactions, subgraph queries, epoch management, and KYC flows.

Installation

npm install @kasufinance/kasu-sdk

Quick Start

import { Kasu } from '@kasufinance/kasu-sdk';

// Initialize with a supported chain (base, xdc, plume)
const kasu = Kasu.create({ chain: 'base', signerOrProvider: provider });

// Browse strategies (lending pools)
const strategies = await kasu.strategies.getAll();

// Deposit into a pool
const tx = await kasu.deposits.deposit({
  poolId: '0x...',
  trancheId: '0x...',
  amount: parseUnits('1000', 6), // 1,000 USDC
  kycSignature: { blockExpiration, signature },
});

// Fetch user positions
const positions = await kasu.portfolio.getPositions('0xUser...');

Supported Chains

The SDK includes built-in configurations for all Kasu-supported networks:

Chain	Chain ID	Deployment Mode	KSU Token
Base	8453	Full	Yes
XDC	50	Lite	No
Plume	98866	Lite	No

Custom chain configurations can be passed directly:

const kasu = Kasu.create({
  chain: { chainId: 123, name: 'MyChain', isLiteDeployment: true, ... },
  signerOrProvider: provider,
});

Facades

The SDK exposes three domain facades on the Kasu instance:

kasu.strategies — Browse Lending Pools

Method	Description
getAll(poolIds?)	Fetch all active lending strategies (pools). Returns APY, TVL, capacity, tranches, fixed-term options
getById(poolId)	Fetch a single strategy by pool address
getPlatformStats()	Aggregate platform statistics (total TVL, loans, yield, loss rate)
calculateDepositLimits(tranche)	Min/max deposit and available capacity for a tranche

Each Strategy includes:

interface Strategy {
  id: string;               // Pool address
  name: string;             // Pool name
  apy: number;              // Weighted-average APY (decimal, 0.08 = 8%)
  tvl: { total, offchain }; // Total value locked
  availableCapacity: string; // Remaining capacity (USDC)
  tranches: StrategyTranche[];
  assetClass: string;       // e.g. "Tax Receivables"
  apyStructure: 'Variable' | 'Fixed';
}

Each StrategyTranche includes:

interface StrategyTranche {
  id: string;               // Tranche address
  name: string;             // e.g. "Senior"
  apy: number;              // Current base APY
  minimumDeposit: string;   // Min USDC deposit
  maximumDeposit: string;   // Max USDC deposit
  availableCapacity: string;
  fixedTermOptions: FixedTermOption[];
}

kasu.deposits — Deposit & Withdraw

Method	Description
deposit(params)	Submit a deposit request (requires KYC signature)
withdraw(params)	Submit a withdrawal request for a specific USDC amount
withdrawMax(poolId, trancheId, userAddress)	Withdraw entire balance from a tranche
buildKycParams(userAddress)	Build parameters for the Compilot KYC signature flow
isClearingPending(poolId)	Check if the pool is in a clearing period
getCurrentEpoch()	Get current epoch number

Deposit Parameters

interface DepositParams {
  poolId: string;
  trancheId: string;
  amount: BigNumberish;        // USDC in base units (6 decimals)
  kycSignature: {
    blockExpiration: BigNumberish;
    signature: BytesLike;
  };
  fixedTermConfigId?: BigNumberish; // Pass 0 for variable deposits
  swapData?: BytesLike;            // Pass '0x' for direct USDC deposits
  depositData?: BytesLike;         // Pass '0x' when not needed
}

kasu.portfolio — User Positions

Method	Description
getPositions(userAddress, provider?)	Fetch per-pool positions and aggregate summary
getTransactionHistory(userAddress)	Fetch full deposit/withdrawal/cancellation history

Returns:

interface UserPositions {
  pools: PortfolioLendingPool[];  // Per-pool breakdown
  summary: PortfolioSummary;      // Aggregate: invested, yields, APY
}

KYC Integration Flow

Deposits require a KYC signature from Compilot. The integrator's flow:

1. Call kasu.deposits.buildKycParams(userAddress) to get the signature request parameters

2. Send these parameters to your backend, which calls the Compilot API (https://api.compilot.ai/customer-tx-auth-signature)

3. If the user is KYC-verified, Compilot returns a signature and block expiration

4. Pass the signature to kasu.deposits.deposit() in the kycSignature field

5. The on-chain KasuAllowList contract verifies the signature during the transaction

Advanced: Low-Level Services

For power users who need direct contract access, the underlying KasuSdk services are available via kasu.services:

// Direct service access
const locks = await kasu.services.Locking.getUserLocks(address);
const poolData = await kasu.services.DataService.getPoolOverview(epochId);

Available services:

Service	Description
Locking	KSU lock/unlock, fee claims, lock periods
UserLending	Direct contract calls for deposits, withdrawals, epoch queries
DataService	Pool overviews, subgraph queries, Directus CMS data
Portfolio	User portfolio and position calculations
Swapper	Token swap utilities

Configuration

The Kasu.create() method accepts optional overrides:

const kasu = Kasu.create({
  chain: 'base',
  signerOrProvider: signer,
  configOverrides: {
    subgraphUrl: 'https://custom-subgraph-url.com',
    directusUrl: 'https://custom-cms-url.com',
    contracts: { ... },       // Override contract addresses
    isLiteDeployment: false,
    UNUSED_LENDING_POOL_IDS: ['0x...'],
    poolMetadataMapping: {},  // Map pool addresses to metadata sources
  },
});

Data Sources

The SDK combines data from three sources:

Source	Data
On-chain contracts	Balances, interest rates, epoch state, clearing status
Goldsky subgraph	User requests, transaction history, pool events
Directus CMS	Pool names, descriptions, images, asset class labels

If the Directus URL is omitted, the SDK returns on-chain and subgraph data only (pool descriptions and images will be empty).