npm package: @lendliq/sdk
Description: LendLiq SDK - DEX aggregation, routing, and trading utilities for LendLiq protocol
Author: LendLiq Team
Latest version: 1.0.0

# @lendliq/sdk

DEX aggregation, routing, and trading utilities for LendLiq protocol.

## Features

- **Multi-DEX Support**: Uniswap V3 and Curve-style StableSwap pools
- **Optimal Routing**: Automatic path finding with split routing for better prices
- **Precise Math**: High-precision calculations using JSBI and BigNumber.js
- **Full TypeScript Support**: Complete type definitions included

## Installation

```bash
npm install @lendliq/sdk
# or
yarn add @lendliq/sdk
# or
pnpm add @lendliq/sdk
```

## Quick Start

```typescript
import { Trade, Token, BSC_TESTNET_TOKENS } from "@lendliq/sdk";
import { createPublicClient, http } from "viem";
import { bscTestnet } from "viem/chains";
import { BigNumber } from "bignumber.js";

// Create viem client
const client = createPublicClient({
  chain: bscTestnet,
  transport: http()
});

// Use pre-defined tokens or create your own
const tokenIn = BSC_TESTNET_TOKENS.USDT;
const tokenOut = BSC_TESTNET_TOKENS.ETH;

// Find the best trade route
const trade = await Trade.fromRoute(
  client,
  tokenIn,
  tokenOut,
  new BigNumber("100000000000000000000"), // 100 USDT (18 decimals)
  {
    v3Factory: "0x8400eCADA82f56d5b8E8e02057C21cFD48c0Df9c",
    stableFactory: "0x600d66fBeA066cC5D2edc0cd02DCa001EEb82C17",
    bridgeTokens: [BSC_TESTNET_TOKENS.WBNB, BSC_TESTNET_TOKENS.USDT],
    enableSplitRouting: true,
  }
);

if (trade) {
  console.log(trade.toString());
  // "Trade: 100 USDT → 0.0202 ETH (Impact: 0.05%)"

  // Get params for smart contract execution
  const params = trade.toAggregatorParams(
    "0xYourAddress",
    50, // 0.5% slippage in basis points
    1200 // 20 minutes deadline
  );
}
```

## Core Classes

### Token

Represents a token on a specific chain.

```typescript
import { Token, createToken } from "@lendliq/sdk";

// Using constructor
const usdt = new Token(
  56,                                           // chainId
  "0x55d398326f99059fF775485246999027B3197955", // address
  18,                                           // decimals
  "USDT",                                       // symbol
  "Tether USD"                                  // name (optional)
);

// Using factory function
const usdc = createToken({
  chainId: 56,
  address: "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d",
  decimals: 18,
  symbol: "USDC",
  name: "USD Coin"
});

// Sort tokens (required for pool creation)
const [token0, token1] = Token.sortTokens(usdt, usdc);
```

### CurrencyAmount

Handles token amounts with automatic decimal handling.

```typescript
import { CurrencyAmount, tryParseCurrencyAmount } from "@lendliq/sdk";

// From raw amount (smallest unit)
const amount1 = CurrencyAmount.fromRawAmount(usdt, "1000000000000000000"); // 1 USDT

// From decimal amount (human readable)
const amount2 = CurrencyAmount.fromDecimalAmount(usdt, "1.5"); // 1.5 USDT

// Parse user input safely
const amount3 = tryParseCurrencyAmount(usdt, "100.50"); // 100.50 USDT or undefined

// Formatting
console.log(amount1.formatted);      // "1.0"
console.log(amount1.toExact());      // "1.0 USDT"
console.log(amount1.toDisplay(4));   // "1"
console.log(amount1.raw);            // 1000000000000000000n
```

### Price

Handles token prices with proper decimal adjustments.

```typescript
import { Price, tickToDisplayPrice } from "@lendliq/sdk";

// From Uniswap V3 tick
const price = Price.fromTick(eth, usdt, -197000);

// From decimal price
const price2 = Price.fromDecimalPrice(eth, usdt, "2500.00");

// Get display values
console.log(price.toDisplay());           // "2,500.00"
console.log(price.toDisplayWithSymbols()); // "1 ETH = 2,500.00 USDT"

// Convert amounts
const usdtAmount = price.quote(ethAmount);
```

### Pool

Represents a Uniswap V3 style liquidity pool.

```typescript
import { Pool } from "@lendliq/sdk";

const pool = Pool.create(
  "0xPoolAddress",
  token0,
  token1,
  3000, // 0.3% fee
  0,    // DEX ID
  -197000, // current tick
  sqrtPriceX96 // optional
);

// Get prices
const price = pool.getCurrentPrice();
const displayPrice = pool.getCurrentPriceNumber();

// Calculate amounts for concentrated liquidity
const token1Needed = pool.getToken1ForToken0InRange(
  1.0,    // 1 token0
  -198000, // tick lower
  -196000  // tick upper
);
```

### Trade

Represents a complete trade with optimal routing.

```typescript
import { Trade, TradeType } from "@lendliq/sdk";

const trade = await Trade.fromRoute(client, tokenIn, tokenOut, amountIn, config);

if (trade) {
  // Trade info
  console.log(trade.formattedAmountIn);  // "100.000000"
  console.log(trade.formattedAmountOut); // "0.020200"
  console.log(trade.priceImpact);        // 0.05

  // Execution price
  const price = trade.getExecutionPriceFormatted();

  // Minimum output with slippage
  const minOut = trade.getMinimumOutput(50); // 0.5% slippage

  // For contract execution
  const params = trade.toAggregatorParams(recipient, slippageBps);

  // Serialize for storage/display
  const json = trade.toJSON();
}
```

### PathFinder

Low-level route finding engine.

```typescript
import { PathFinder } from "@lendliq/sdk";

const pathFinder = new PathFinder(client, {
  v3Factory: "0x...",
  stableFactory: "0x...",
  bridgeTokens: [wbnb, usdt, eth],
  feeTiers: [500, 2500, 10000],
  maxHops: 3,
  enableSplitRouting: true,
  maxSplitRoutes: 3,
  minSplitPercentage: 500, // 5%
});

const result = await pathFinder.findBestRoute(
  tokenIn.address,
  tokenOut.address,
  amountIn
);

if (result) {
  console.log(result.routes);      // Route details
  console.log(result.amountOut);   // Total output
  console.log(result.priceImpact); // Price impact %
}
```

## Math Utilities

### PoolMath

Uniswap V3 concentrated liquidity mathematics.

```typescript
import { PoolMath } from "@lendliq/sdk";

// Calculate swap output
const result = PoolMath.getAmountOut(
  sqrtPriceX96,
  liquidity,
  amountIn,
  zeroForOne,
  fee,
  token0Decimals,
  token1Decimals
);

// Encode/decode swap path
const path = PoolMath.encodePath(
  [token0, token1, token2],
  [3000, 500]
);
const decoded = PoolMath.decodePath(path);
```

### StableMath

Curve-style StableSwap mathematics.

```typescript
import { StableMath } from "@lendliq/sdk";

// Calculate swap output for stable pools
const result = StableMath.getAmountOut(pool, indexIn, indexOut, amountIn);

// Get exchange rate
const rate = StableMath.getExchangeRate(pool, 0, 1);

// Calculate invariant
const D = StableMath.getD(balances, amplificationFactor);
```

## Pre-defined Tokens

```typescript
import { BSC_TESTNET_TOKENS, BSC_MAINNET_TOKENS } from "@lendliq/sdk";

// BSC Testnet (Chain ID: 97)
BSC_TESTNET_TOKENS.WBNB
BSC_TESTNET_TOKENS.USDT
BSC_TESTNET_TOKENS.USDC
BSC_TESTNET_TOKENS.ETH
BSC_TESTNET_TOKENS.BTCB

// BSC Mainnet (Chain ID: 56)
BSC_MAINNET_TOKENS.WBNB
BSC_MAINNET_TOKENS.USDT
BSC_MAINNET_TOKENS.USDC
BSC_MAINNET_TOKENS.BUSD
BSC_MAINNET_TOKENS.ETH
BSC_MAINNET_TOKENS.BTCB
```

## License

MIT