{"_id":"@compx/orbital-lending-sdk","_rev":"2-b519e5e3b1e49f4db4902dc63781c593","name":"@compx/orbital-lending-sdk","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.1":{"name":"@compx/orbital-lending-sdk","version":"1.0.1","keywords":["orbital","algorand","defi","lending","sdk"],"author":"","license":"MIT","_id":"@compx/orbital-lending-sdk@1.0.1","maintainers":[{"name":"xxiled_compx","email":"kieran@compx.io"}],"dist":{"shasum":"fc7b59d3a8f90b0104bfa02611c4357685032ade","tarball":"https://registry.npmjs.org/@compx/orbital-lending-sdk/-/orbital-lending-sdk-1.0.1.tgz","fileCount":8,"integrity":"sha512-WulTXFvw6U/sgFxYCkCpo18h2vMeQJzpLeAUS5ACfE5dnyaoW+a8R1wS/Ws/Jzb1UE/745mko5pTnbFcfLQkCA==","signatures":[{"sig":"MEUCIQDSGiHjG4bWlLdAU8AzLQEeJPe/N2PA/0ifjsgqXv0e9QIgeChdHoaYOCJxQmmqRZCWZ7jwmg0vAb/Ylcvm5gVAKek=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":311911},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","gitHead":"ff80b0980185763b2cede3cadb79a7ee238d0045","scripts":{"dev":"tsup src/index.ts --format cjs,esm --dts --watch --sourcemap","lint":"eslint src --ext .ts","test":"vitest run","build":"tsup src/index.ts --format cjs,esm --dts --clean --sourcemap","debug":"tsx src/debug.ts","test:ui":"vitest --ui","typecheck":"tsc --noEmit","debug:file":"tsx","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"pnpm run build"},"_npmUser":{"name":"xxiled_compx","email":"kieran@compx.io"},"_npmVersion":"10.8.2","description":"TypeScript SDK for Orbital Lending protocol, by CompX","directories":{},"_nodeVersion":"20.19.0","dependencies":{"@algorandfoundation/algokit-utils":"^6.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.6","tsup":"^8.0.1","eslint":"^8.54.0","vitest":"^1.0.4","@vitest/ui":"^1.0.4","typescript":"^5.3.2","@types/node":"^20.10.0","@vitest/coverage-v8":"^1.0.4","@typescript-eslint/parser":"^6.13.0","@typescript-eslint/eslint-plugin":"^6.13.0"},"peerDependencies":{"algosdk":"^2.7.0"},"_npmOperationalInternal":{"tmp":"tmp/orbital-lending-sdk_1.0.1_1762986032609_0.7158238755895168","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@compx/orbital-lending-sdk","version":"1.0.2","description":"TypeScript SDK for Orbital Lending protocol, by CompX","main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","scripts":{"build":"tsup src/index.ts --format cjs,esm --dts --clean --sourcemap","dev":"tsup src/index.ts --format cjs,esm --dts --watch --sourcemap","debug":"tsx src/debug.ts","debug:file":"tsx","test":"vitest run","test:watch":"vitest","test:ui":"vitest --ui","test:coverage":"vitest run --coverage","typecheck":"tsc --noEmit","lint":"eslint src --ext .ts","prepublishOnly":"pnpm run build"},"keywords":["orbital","algorand","defi","lending","sdk"],"author":"","license":"MIT","publishConfig":{"access":"public"},"peerDependencies":{"algosdk":"^2.7.0"},"devDependencies":{"@types/node":"^20.10.0","@typescript-eslint/eslint-plugin":"^6.13.0","@typescript-eslint/parser":"^6.13.0","@vitest/coverage-v8":"^1.0.4","@vitest/ui":"^1.0.4","eslint":"^8.54.0","tsup":"^8.0.1","tsx":"^4.20.6","typescript":"^5.3.2","vitest":"^1.0.4"},"dependencies":{"@algorandfoundation/algokit-utils":"^6.0.0"},"_id":"@compx/orbital-lending-sdk@1.0.2","gitHead":"6419aba49d1d50948fee6ca3a20c37afa486e6ca","_nodeVersion":"20.19.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-2AHVrUQWR29bMhkVKpGpm7+eGxNj9oZvLHjmZxsBUdu70rax9ar0xDDvsxhIifjtxaDcvhdec6TBIMXTx1Pwdg==","shasum":"e6e02b28361283b0eca938e607f71a1e3f1821e9","tarball":"https://registry.npmjs.org/@compx/orbital-lending-sdk/-/orbital-lending-sdk-1.0.2.tgz","fileCount":8,"unpackedSize":311557,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCICXQaTAW206FtDLAhZaSs4Aq5Hh4Ihi3hlDjQ0ikeCMkAiA+2w+AZtxjknWH92RrjRgda76LbmQZFQvOTtIghzayOA=="}]},"_npmUser":{"name":"xxiled_compx","email":"kieran@compx.io"},"directories":{},"maintainers":[{"name":"xxiled_compx","email":"kieran@compx.io"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/orbital-lending-sdk_1.0.2_1763151492790_0.11705437314629008"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-12T22:20:32.531Z","modified":"2025-11-14T20:18:13.205Z","1.0.1":"2025-11-12T22:20:32.806Z","1.0.2":"2025-11-14T20:18:12.971Z"},"license":"MIT","keywords":["orbital","algorand","defi","lending","sdk"],"description":"TypeScript SDK for Orbital Lending protocol, by CompX","maintainers":[{"name":"xxiled_compx","email":"kieran@compx.io"}],"readme":"# Orbital Finance SDK\n\nTypeScript SDK for interacting with the Orbital Finance lending protocol on Algorand.\n\n## Installation\n\n```bash\nnpm install @orbital-finance/sdk\n# or\npnpm add @orbital-finance/sdk\n# or\nyarn add @orbital-finance/sdk\n```\n\n## Quick Start\n\n```typescript\nimport { OrbitalSDK } from '@orbital-finance/sdk';\nimport algosdk from 'algosdk';\n\n// Initialize the SDK with custom Algod configuration\nconst algodClient = new algosdk.Algodv2(\n  'your-token',              // API token (empty string for public nodes)\n  'https://testnet-api.algonode.cloud',  // Algod URL\n  ''                         // Port (empty for default)\n);\n\n// Optional: Initialize indexer for historical queries\nconst indexerClient = new algosdk.Indexer(\n  'your-token',\n  'https://testnet-idx.algonode.cloud',\n  ''\n);\n\nconst sdk = new OrbitalSDK({\n  algodClient,               // Required: Configured Algod client\n  network: 'testnet',        // Required: 'mainnet' or 'testnet'\n  indexerClient,             // Optional: For historical data\n  apiBaseUrl: 'https://api.orbitalfinance.io' // Optional: Custom backend URL\n});\n\n// Get market information (no wallet needed!)\nconst market = await sdk.getMarket(12345678);\nconsole.log('Supply APY:', market.supplyApy);\n\n// Get asset metadata from Algorand (no wallet needed!)\nconst asset = await sdk.getAssetInfo(31566704);\nconsole.log('Asset:', asset.name, asset.unitName);\n```\n\n### Configuration Options\n\nThe SDK accepts pre-configured `algosdk` clients, allowing you to:\n- Use custom node providers (AlgoNode, PureStake, your own node)\n- Configure authentication tokens\n- Set custom ports and endpoints\n- Use testnet or mainnet\n\n## Features\n\n- 📊 **Market Data**: Fetch formatted market information including TVL, utilization, and interest rates\n- 💰 **APY Calculations**: Get current supply and borrow APYs using the protocol's interest rate model\n- 🪙 **LST Pricing**: Calculate LST token prices based on pool composition\n- 🔍 **User Positions**: Query user deposits, borrows, and collateral\n- ⚡ **Type-Safe**: Full TypeScript support with detailed type definitions\n\n## API Reference\n\n### OrbitalSDK\n\nMain SDK class for interacting with Orbital Finance.\n\n#### Methods\n\n##### `getMarket(appId: number): Promise<MarketData>`\n\nFetches comprehensive market data for a specific lending market.\n\n**Parameters:**\n- `appId`: The application ID of the lending market\n\n**Returns:** Promise resolving to `MarketData` object containing:\n- Supply and borrow APYs\n- Total deposits and borrows\n- Utilization rate\n- Available liquidity\n- Interest rate model parameters\n- And more...\n\n##### `getAPY(appId: number): Promise<APYData>`\n\nCalculates current supply and borrow APYs for a market.\n\n**Parameters:**\n- `appId`: The application ID of the lending market\n\n**Returns:** Promise resolving to `APYData` object with supply and borrow APYs\n\n##### `getLSTPrice(appId: number): Promise<number>`\n\nCalculates the current price of the LST token in terms of the underlying asset.\n\n**Parameters:**\n- `appId`: The application ID of the lending market\n\n**Returns:** Promise resolving to the LST price (1 LST = X underlying tokens)\n\n##### `getMarkets(appIds: number[]): Promise<MarketData[]>`\n\nFetches multiple markets in parallel. **No wallet required.**\n\n**Parameters:**\n- `appIds`: Array of market application IDs\n\n**Returns:** Promise resolving to array of `MarketData` objects\n\n**Example:**\n```typescript\nconst markets = await sdk.getMarkets([12345678, 23456789, 34567890]);\nmarkets.forEach(market => {\n  console.log(`Market ${market.appId}: ${market.supplyApy}% APY`);\n});\n```\n\n##### `getAllMarkets(): Promise<MarketData[]>`\n\nFetches all available markets from the Orbital backend API and enriches with on-chain data. **No wallet required.**\n\n**Returns:** Promise resolving to array of all `MarketData` objects\n\n**Example:**\n```typescript\nconst allMarkets = await sdk.getAllMarkets();\nconsole.log(`Found ${allMarkets.length} markets`);\n```\n\n##### `getMarketList(): Promise<MarketInfo[]>`\n\nFetches basic market information from the backend API without on-chain data. This is faster than `getAllMarkets()` if you only need market IDs and token IDs. **No wallet required.**\n\n**Returns:** Promise resolving to array of `MarketInfo` objects with basic market data\n\n**Example:**\n```typescript\nconst marketList = await sdk.getMarketList();\n// Returns: [{ appId, baseTokenId, lstTokenId, network }, ...]\n```\n\n##### `getOraclePrice(oracleAppId: number, assetId: number): Promise<OraclePrice>`\n\nFetches the current price for an asset from the oracle contract. **No wallet required.**\n\n**Parameters:**\n- `oracleAppId`: The oracle application ID\n- `assetId`: The asset ID to get price for\n\n**Returns:** Promise resolving to `OraclePrice` object with price, timestamp, and metadata\n\n**Example:**\n```typescript\nconst price = await sdk.getOraclePrice(789012, 31566704);\nconsole.log(`Asset price: $${price.price}`);\nconsole.log(`Last updated: ${price.lastUpdatedDate}`);\n```\n\n##### `getOraclePrices(oracleAppId: number, assetIds: number[]): Promise<OraclePriceMap>`\n\nFetches prices for multiple assets in parallel from the oracle contract. **No wallet required.**\n\n**Parameters:**\n- `oracleAppId`: The oracle application ID\n- `assetIds`: Array of asset IDs to get prices for\n\n**Returns:** Promise resolving to a Map of asset ID to `OraclePrice` objects\n\n**Example:**\n```typescript\nconst prices = await sdk.getOraclePrices(789012, [0, 31566704, 386192725]);\nprices.forEach((price, assetId) => {\n  console.log(`Asset ${assetId}: $${price.price}`);\n});\n```\n\n##### `getAssetInfo(assetId: number): Promise<AssetInfo>`\n\nFetches asset metadata directly from the Algorand blockchain. **No wallet required.**\n\n**Parameters:**\n- `assetId`: Asset ID to fetch (use 0 for ALGO)\n\n**Returns:** Promise resolving to `AssetInfo` with name, symbol, decimals, supply, etc.\n\n**Example:**\n```typescript\nconst asset = await sdk.getAssetInfo(31566704);\nconsole.log(`${asset.name} (${asset.unitName})`);\nconsole.log(`Decimals: ${asset.decimals}`);\n```\n\n##### `getAssetsInfo(assetIds: number[]): Promise<AssetInfo[]>`\n\nFetches metadata for multiple assets in parallel from Algorand. **No wallet required.**\n\n**Parameters:**\n- `assetIds`: Array of asset IDs to fetch\n\n**Returns:** Promise resolving to array of `AssetInfo` objects\n\n**Example:**\n```typescript\nconst assets = await sdk.getAssetsInfo([0, 31566704, 386192725]);\nassets.forEach(asset => {\n  console.log(`${asset.name}: ${asset.decimals} decimals`);\n});\n```\n\n##### `getMarketLoanRecords(appId: number): Promise<LoanRecord[]>`\n\nFetches all active loan records from a market. **No wallet required.**\n\n**Parameters:**\n- `appId`: Market application ID\n\n**Returns:** Promise resolving to array of `LoanRecord` objects\n\n**Example:**\n```typescript\nconst loanRecords = await sdk.getMarketLoanRecords(12345678);\nconsole.log(`Found ${loanRecords.length} active loans`);\n```\n\n##### `getAllDebtPositions(marketAppIds: number[]): Promise<DebtPosition[]>`\n\nFetches all debt positions from multiple markets with calculated metrics. **No wallet required.**\n\n**Parameters:**\n- `marketAppIds`: Array of market application IDs\n\n**Returns:** Promise resolving to array of `DebtPosition` objects with health ratios, totals, etc.\n\n**Example:**\n```typescript\nconst positions = await sdk.getAllDebtPositions([12345, 23456]);\npositions.forEach(pos => {\n  console.log(`${pos.borrowerAddress}: Health ${pos.healthRatio}`);\n});\n```\n\n##### `getAllDebtPositionsFromAllMarkets(): Promise<DebtPosition[]>`\n\nFetches all debt positions from all available markets. **No wallet required.**\n\n**Returns:** Promise resolving to array of all `DebtPosition` objects across all markets\n\n**Example:**\n```typescript\nconst allPositions = await sdk.getAllDebtPositionsFromAllMarkets();\nconst atRisk = allPositions.filter(p => p.healthRatio < p.liquidationThreshold);\nconsole.log(`${atRisk.length} positions at risk`);\n```\n\n##### `getUserPosition(appId: number, userAddress: string): Promise<UserPosition>`\n\nFetches a user's position in a specific market, including deposits, LST balance, borrows, and collateral.\n\n**Parameters:**\n- `appId`: Market application ID\n- `userAddress`: User's Algorand address\n\n**Returns:** Promise resolving to `UserPosition` object with user's complete position\n\n**Example:**\n```typescript\nconst position = await sdk.getUserPosition(12345678, 'USERADDRESS...');\nconsole.log(`Supplied: ${position.supplied}`);\nconsole.log(`Borrowed: ${position.borrowed}`);\nconsole.log(`Health Factor: ${position.healthFactor}`);\n```\n\n##### `getAllUserPositions(userAddress: string): Promise<UserAllPositions>`\n\nFetches all positions (deposits and borrows) for a user across all active markets. This method checks deposit records and loan records across all markets and aggregates the results.\n\n**Parameters:**\n- `userAddress`: User's Algorand address\n\n**Returns:** Promise resolving to `UserAllPositions` object containing:\n- `address`: User's address\n- `positions`: Array of individual market positions\n- `totalSupplied`: Sum of supplied amounts across all markets\n- `totalBorrowed`: Sum of borrowed amounts across all markets\n- `totalCollateral`: Sum of collateral across all markets\n- `overallHealthFactor`: Minimum health factor across all positions\n- `activeMarkets`: Number of markets with active positions\n\n**Example:**\n```typescript\nconst allPositions = await sdk.getAllUserPositions('USERADDRESS...');\n\nconsole.log(`Active in ${allPositions.activeMarkets} markets`);\nconsole.log(`Total Supplied: ${allPositions.totalSupplied}`);\nconsole.log(`Total Borrowed: ${allPositions.totalBorrowed}`);\nconsole.log(`Health Factor: ${allPositions.overallHealthFactor}`);\n\n// Check individual positions\nallPositions.positions.forEach(pos => {\n  console.log(`Market ${pos.appId}:`);\n  console.log(`  Supplied: ${pos.supplied}`);\n  console.log(`  Borrowed: ${pos.borrowed}`);\n});\n```\n\n##### `getUserPositionsForMarkets(userAddress: string, marketAppIds: number[]): Promise<UserAllPositions>`\n\nFetches user positions across specific markets. Similar to `getAllUserPositions()` but only checks the specified markets.\n\n**Parameters:**\n- `userAddress`: User's Algorand address\n- `marketAppIds`: Array of market application IDs to check\n\n**Returns:** Promise resolving to `UserAllPositions` object with positions from specified markets\n\n**Example:**\n```typescript\nconst positions = await sdk.getUserPositionsForMarkets(\n  'USERADDRESS...',\n  [12345678, 23456789]\n);\n\nconsole.log(`Total across ${positions.activeMarkets} specified markets`);\nconsole.log(`Total Borrowed: ${positions.totalBorrowed}`);\n```\n\n## Development\n\n```bash\n# Install dependencies\npnpm install\n\n# Build the SDK\npnpm run build\n\n# Watch mode for development\npnpm run dev\n\n# Run tests\npnpm run test\n\n# Run tests in watch mode\npnpm run test:watch\n\n# Run tests with UI\npnpm run test:ui\n\n# Run tests with coverage\npnpm run test:coverage\n\n# Type checking\npnpm run typecheck\n\n# Linting\npnpm run lint\n```\n\n## Testing\n\nThe SDK includes a comprehensive test suite using Vitest. Tests cover:\n\n- **Calculation utilities** - APY calculations, LST pricing, unit conversions\n- **State utilities** - Box encoding/decoding, state fetching\n- **Client methods** - Market data, APY, LST price, user positions\n- **Integration** - Full SDK workflow tests\n\nRun the tests:\n\n```bash\n# Run all tests\npnpm run test\n\n# Watch mode for development\npnpm run test:watch\n\n# Generate coverage report\npnpm run test:coverage\n\n# Interactive UI\npnpm run test:ui\n```\n\n## License\n\nMIT\n\n","readmeFilename":"README.md"}