Flux Protocol SDK

A TypeScript SDK for directly accessing Flux Protocol data from the Radix blockchain. This package provides a clean, type-safe interface for fetching protocol information without needing to rely on API endpoints.

Installation

npm install flux-protocol-sdk

Quick Start

import { FluxDataClient, collaterals } from "flux-protocol-sdk";

const client = new FluxDataClient();

// Get current prices
const prices = await client.getPrices();
console.log(`XRD: $${prices.xrdPrice}`);

// Get protocol statistics
const stats = await client.getProtocolStats();
console.log(`TVL: $${stats.totalValueLocked}`);

Core Features

📊 Direct Data Access

Fetch data directly from the Radix Gateway and external sources - no API dependencies.

🔗 Complete Protocol Coverage

• Price data (XRD/LSULP with oracle messages)
• Protocol statistics (TVL, debt, collateralization)
• CDP operations and management
• Interest rate calculations
• Stability pool operations
• Transaction manifest generation

🛡️ Type Safety

Full TypeScript support with comprehensive type definitions.

Usage

Setup

import { FluxDataClient } from "flux-protocol-sdk";
import { RadixNetwork } from "@radixdlt/babylon-gateway-api-sdk";

// For Stokenet (default)
const client = new FluxDataClient();

// For Mainnet
const mainnetClient = new FluxDataClient(RadixNetwork.Mainnet);

Price Data

// Get current prices with oracle message
const prices = await client.getPrices();
console.log(prices);
// Returns:
// {
//   xrdPrice: 0.0456,
//   lsulpPrice: 0.0410,
//   oracleMessage: ["0x123...", "0x456..."] // or null if no message
// }

Protocol Statistics

// Get comprehensive protocol data
const stats = await client.getProtocolStats();
console.log(stats);
// Returns:
// {
//   totalValueLocked: 1500000.50,
//   totalDebt: 750000.25,
//   totalDebtByCollateral: {
//     xrd: 500000.15,
//     lsulp: 250000.10
//   },
//   circulatingFusd: 750000.25,
//   averageInterestRates: {
//     xrd: 5.75,
//     lsulp: 6.20
//   },
//   activeInterestRates: 35,
//   collateralizationRatio: 200.00
// }

CDP Operations

// Get CDP information
const cdpData = await client.getCdpsInfo(["#1#", "#2#"]);
console.log(cdpData);
// Returns:
// {
//   translatedCdpsData: [
//     {
//       id: '#1#',
//       collateral: 'resource_tdx_2_1tknxxxxxxxxxradxrdxxxxxxxxx009923554798xxxxxxxxxtfd2jc',
//       debt: 130.79868425583456,
//       collateralAmount: 86262.2869049716,
//       interestRate: 0.348,
//       state: 'healthy'
//     },
//     {
//       id: '#2#',
//       collateral: 'resource_tdx_2_1tka404jaaw7kvtdq6ngj93eycnvscymfalctrehflvpjscfrqrlv5d',
//       debt: 75.50,
//       collateralAmount: 50000.00,
//       interestRate: 0.352,
//       state: 'healthy'
//     }
//   ]
// }

// Get historical CDP data with state version
const historicalData = await client.getCdpsInfo(["#1#"], 205725151);
// Returns same structure as above but with data from the specified state version

Interest Rates & Collateral

import { collaterals } from "flux-protocol-sdk";

// Get interest rate information
const xrdRates = await client.getInterestInfos(
  collaterals.xrd.collateralAddress
);
console.log(xrdRates);
// Returns:
// {
//   interests: [
//     [0.348, 500000.00],  // [interest rate, debt amount]
//     [0.352, 250000.00],
//     [0.355, 100000.00]
//   ],
//   averageApr: 0.350,
//   averageApy: 0.419,
//   average7DayYield: 0.0067
// }

// Get collateral debt information
const collateralInfo = await client.getCollateralInfos([
  collaterals.xrd.collateralAddress,
  collaterals.lsulp.collateralAddress,
]);
console.log(collateralInfo);
// Returns:
// {
//   xrd: {
//     totalDebt: 500000.15,
//     totalCollateral: 1000000.30
//   },
//   lsulp: {
//     totalDebt: 250000.10,
//     totalCollateral: 500000.20
//   }
// }

// Get redemption risk interest data
const redemptionRisk = await client.getRedemptionRiskInterest(
  collaterals.xrd.collateralAddress,
  20, // percentage before
  1000 // additional debt (optional)
);
console.log(redemptionRisk);
// Returns:
// {
//   riskLevel: 'medium',
//   amountInFront: 150000.00,
//   percentageInFront: 0.15
// }

Stability Pools (Reservoir)

// Get reservoir information
const reservoirData = await client.getReservoirDetails(
  collaterals.xrd.collateralAddress,
  12345678 // optional state version
);
console.log(reservoirData);
// Returns:
// {
//   poolSize: 1000000.00,
//   userDeposit: 50000.00,
//   userShare: 0.05,
//   totalEarnings: 2500.00,
//   userEarnings: 125.00
// }

// Get APR information
const aprData = await client.getReservoirApr(collaterals.xrd.collateralAddress);
console.log(aprData);
// Returns:
// {
//   apr: 5.75,
//   apy: 5.92,
//   dailyRate: 0.0157
// }

Transaction Generation

// Generate borrow transaction
const borrowTx = await client.getBorrowManifest({
  collateralAddress: collaterals.xrd.collateralAddress,
  collateralAmount: 1000,
  ltv: 80, // 80% loan-to-value
  interestRate: 5, // 5% annual interest
  accountAddress: "account_tdx_...",
  redemptionOptOut: false, // optional
});
console.log(borrowTx);
// Returns:
// {
//   manifest: "CALL_METHOD...",
//   message: "Borrow fUSD against XRD collateral"
// }

// Generate close position transaction
const closeTx = await client.getCloseManifest({
  nftId: "#1#",
  accountAddress: "account_tdx_...",
});
console.log(closeTx);
// Returns:
// {
//   manifest: "CALL_METHOD...",
//   message: "Close CDP position"
// }

// Generate stability pool deposit
const depositTx = await client.getReservoirDepositManifest({
  collateralAddress: collaterals.xrd.collateralAddress,
  amount: 1000,
  accountAddress: "account_tdx_...",
});
console.log(depositTx);
// Returns:
// {
//   manifest: "CALL_METHOD...",
//   message: "Deposit to stability pool"
// }

// Generate stability pool withdrawal
const withdrawTx = await client.getReservoirWithdrawManifest({
  collateralAddress: collaterals.xrd.collateralAddress,
  amount: 500,
  accountAddress: "account_tdx_...",
});
console.log(withdrawTx);
// Returns:
// {
//   manifest: "CALL_METHOD...",
//   message: "Withdraw from stability pool"
// }

Advanced Usage

Direct Module Access

// Access individual modules for specialized operations
const client = new FluxDataClient();

// Price module
const priceModule = client.prices;
const currentPrices = await priceModule.getPrices();
// Returns same structure as client.getPrices()

// CDP module with advanced filtering
const cdpModule = client.cdps;
const sortedCdps = await cdpModule.getCdpsSortedByInterest(
  ["#1#", "#2#"],
  true
);
// Returns same structure as client.getCdpsInfo() but sorted by interest rate

// Interest rate module
const interestModule = client.interestRates;
const interestInfo = await interestModule.getInterestInfos(
  collaterals.xrd.collateralAddress
);
// Returns same structure as client.getInterestInfos()

// Reservoir module
const reservoirModule = client.reservoir;
const reservoirDetails = await reservoirModule.getReservoirDetails(
  collaterals.xrd.collateralAddress
);
// Returns same structure as client.getReservoirDetails()

// Transaction module
const transactionModule = client.transactions;
const borrowManifest = await transactionModule.getBorrowManifest({
  collateralAddress: collaterals.xrd.collateralAddress,
  collateralAmount: 1000,
  ltv: 80,
  accountAddress: "account_tdx_...",
  interestRate: 5,
});
// Returns same structure as client.getBorrowManifest()

Error Handling

import { FluxError } from "flux-protocol-sdk";

try {
  const prices = await client.getPrices();
} catch (error) {
  if (error instanceof FluxError) {
    console.log("Flux Error:", error.message);
    if (error.statusCode) {
      console.log("Status Code:", error.statusCode);
    }
  }
}

API Reference

FluxDataClient

Core Methods

• getPrices() - Get current XRD and LSULP prices
• getProtocolStats() - Get protocol statistics
• getCdpsInfo(nftIds, stateVersion?) - Get CDP information
• getInterestInfos(collateralAddress) - Get interest rates
• getCollateralInfos(addresses) - Get collateral debt data
• getRedemptionRiskInterest(collateralAddress, percentageBefore, additionalDebt?) - Get redemption risk data
• getReservoirApr(collateralAddress) - Get stability pool APR
• getReservoirDetails(collateralAddress, stateVersion?) - Get pool details

Transaction Methods

• getBorrowManifest(borrowData) - Generate borrow transaction
• getCloseManifest(closeData) - Generate close transaction
• getReservoirDepositManifest(depositData) - Generate deposit transaction
• getReservoirWithdrawManifest(withdrawData) - Generate withdraw transaction

Module Access

• client.prices - Price module
• client.protocolStats - Protocol statistics module
• client.cdps - CDP operations module
• client.interestRates - Interest rate module
• client.reservoir - Stability pool module
• client.transactions - Transaction generation module
• client.gateway - Direct Radix Gateway access

License

MIT