{"_id":"@cardalabs/sdk","name":"@cardalabs/sdk","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@cardalabs/sdk","version":"1.0.0","description":"LLM Toolkit for Cardano ecosystem - A comprehensive SDK for interacting with Cardano data providers","license":"GPL-3.0-only","author":{"name":"cardalabs"},"type":"module","main":"dist/esm/index.js","module":"dist/esm/index.js","types":"dist/types/index.d.ts","exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/esm/index.js","require":"./dist/cjs/index.js","default":"./dist/esm/index.js"}},"keywords":["cardano","blockchain","crypto","sdk","api","llm","toolkit"],"scripts":{"build":"npm run build:cjs && npm run build:esm && npm run build:types && npm run build:package-json","build:cjs":"tsc -p tsconfig.cjs.json && tsc-alias -p tsconfig.cjs.json","build:esm":"tsc -p tsconfig.esm.json && tsc-alias -p tsconfig.esm.json && echo '{\"type\":\"module\"}' > dist/esm/package.json","build:types":"tsc -p tsconfig.types.json","build:package-json":"echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json","build:watch":"tsc -p tsconfig.build.json --watch","clean":"rimraf dist","start":"node dist/cjs/index.js","test":"jest","test:watch":"jest --watch","test:coverage":"jest --coverage","lint":"eslint src/**/*.ts","lint:fix":"eslint src/**/*.ts --fix","format":"prettier --write .","format:check":"prettier --check .","typecheck":"tsc --noEmit","prepare":"npm run build","prepublishOnly":"npm run clean && npm run build && npm run test && npm run security","prepack":"npm run build","security":"npm audit --audit-level moderate"},"devDependencies":{"@eslint/js":"^9.28.0","@semantic-release/changelog":"^6.0.3","@semantic-release/git":"^10.0.1","@trivago/prettier-plugin-sort-imports":"^5.2.2","@types/jest":"^29.5.14","@types/node":"^20.19.0","eslint":"^9.28.0","jest":"^29.7.0","prettier":"^3.5.3","rimraf":"^6.0.1","semantic-release":"^22.0.12","ts-jest":"^29.1.1","tsc-alias":"^1.8.16","typescript":"^5.8.3","typescript-eslint":"^8.33.1"},"engines":{"node":">=16.0.0"},"repository":{"type":"git","url":"git+https://github.com/CardaLabs/sdk.git"},"bugs":{"url":"https://github.com/CardaLabs/sdk/issues"},"homepage":"https://github.com/CardaLabs/sdk#readme","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"funding":{"type":"github","url":"https://github.com/sponsors/CardaLabs"},"_id":"@cardalabs/sdk@1.0.0","gitHead":"ddc4ba0874c4d11decd65a992dd15d9e4acd475a","_nodeVersion":"23.10.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-W4jfHB3LNCXip35UULWC7Py0wzg/sLEduxQo3cC4VpQoy1bbvAonp98iia8KrNKTMUTW91LOlPJhaQiT6Yr4fg==","shasum":"6edc6e01a3e9e1936c94c2f2416a30bea5aef30f","tarball":"https://registry.npmjs.org/@cardalabs/sdk/-/sdk-1.0.0.tgz","fileCount":109,"unpackedSize":459551,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDvFxYXj4W5K/SvgrGMxK1hrgrCx1cF2isZ5FD869K4jAIgchzJadYlR+Qrf8C5nI4pH+alvzcR1WLlUgb2X40MXZA="}]},"_npmUser":{"name":"omnikevf","email":"cardalabs@proton.me"},"directories":{},"maintainers":[{"name":"omnikevf","email":"cardalabs@proton.me"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_1.0.0_1749549468576_0.8075550399623275"},"_hasShrinkwrap":false}},"time":{"created":"2025-06-10T09:57:48.481Z","1.0.0":"2025-06-10T09:57:48.775Z","modified":"2025-06-10T09:57:49.038Z"},"maintainers":[{"name":"omnikevf","email":"cardalabs@proton.me"}],"description":"LLM Toolkit for Cardano ecosystem - A comprehensive SDK for interacting with Cardano data providers","homepage":"https://github.com/CardaLabs/sdk#readme","keywords":["cardano","blockchain","crypto","sdk","api","llm","toolkit"],"repository":{"type":"git","url":"git+https://github.com/CardaLabs/sdk.git"},"author":{"name":"cardalabs"},"bugs":{"url":"https://github.com/CardaLabs/sdk/issues"},"license":"GPL-3.0-only","readme":"# 🚀 Cardalabs SDK\n\n**The LLM Toolkit for the Cardano Ecosystem** - A TypeScript SDK that provides unified access to multiple Cardano data providers through a single interface.\n\n## Installation\n\n```bash\nnpm install @cardalabs/sdk\n```\n\n## Quick Start\n\n```typescript\nimport { CardalabsSDK } from '@cardalabs/sdk';\n\n// Initialize SDK with provider configurations\nconst sdk = new CardalabsSDK({\n  providers: {\n    blockfrost: {\n      projectId: 'your-blockfrost-project-id',\n    },\n    coingecko: {\n      apiKey: 'your-coingecko-api-key',\n    },\n  },\n});\n\n// Initialize the SDK\nawait sdk.initialize();\n\n// Get token data (price from CoinGecko, metadata from Blockfrost)\nconst tokenData = await sdk.getTokenData(\n  'lovelace', // ADA\n  ['price', 'marketCap', 'name', 'symbol'],\n);\n\nconsole.log(`ADA Price: $${tokenData.data.price}`);\nconsole.log(`Market Cap: $${tokenData.data.marketCap}`);\n\n// Get wallet data\nconst walletData = await sdk.getWalletData(\n  'addr1...', // Cardano address\n  ['balance', 'portfolio'],\n);\n\nconsole.log(`ADA Balance: ${walletData.data.balance?.lovelace} lovelace`);\n```\n\n## Configuration\n\n### Basic Configuration\n\n```typescript\nimport { type CardalabsConfig, CardalabsSDK } from '@cardalabs/sdk';\n\nconst config: CardalabsConfig = {\n  // Provider configurations\n  providers: {\n    blockfrost: {\n      projectId: process.env.BLOCKFROST_PROJECT_ID!,\n      baseUrl: 'https://cardano-mainnet.blockfrost.io/api/v0',\n      enabled: true,\n    },\n    coingecko: {\n      apiKey: process.env.COINGECKO_API_KEY!,\n      pro: true, // Use CoinGecko Pro API\n      enabled: true,\n    },\n  },\n\n  // Cache configuration\n  cache: {\n    defaultTtl: 300, // 5 minutes\n    maxSize: 1000,\n    fieldTtl: {\n      // Field-specific cache durations\n      price: 30, // 30 seconds for prices\n      marketCap: 60, // 1 minute for market cap\n      name: 600, // 10 minutes for metadata\n      symbol: 600,\n      balance: 120, // 2 minutes for balances\n    },\n  },\n\n  // Provider priorities for each field\n  providerPriorities: {\n    price: ['coingecko', 'dexscreener'],\n    marketCap: ['coingecko'],\n    name: ['blockfrost', 'coingecko'],\n    balance: ['blockfrost'],\n    portfolio: ['taptools', 'blockfrost'],\n  },\n\n  // Health check configuration\n  healthCheck: {\n    enabled: true,\n    interval: 300, // Check every 5 minutes\n    timeout: 10000, // 10 second timeout\n  },\n\n  // Default request options\n  defaultRequestOptions: {\n    timeout: 10000,\n    maxRetries: 3,\n    useCache: true,\n  },\n};\n\nconst sdk = new CardalabsSDK(config);\n```\n\n### Environment Variables\n\nCreate a `.env` file:\n\n```env\nBLOCKFROST_PROJECT_ID=your_blockfrost_project_id\nCOINGECKO_API_KEY=your_coingecko_api_key\nTAPTOOLS_API_KEY=your_taptools_api_key\n```\n\n## Core Concepts\n\n### 1. **Data Fields**\n\nThe SDK uses a field-based approach where you specify exactly what data you need:\n\n```typescript\n// Token data fields\ntype TokenDataField =\n  | 'price'\n  | 'priceUsd'\n  | 'marketCap'\n  | 'volume24h'\n  | 'priceChange24h'\n  | 'name'\n  | 'symbol'\n  | 'decimals'\n  | 'totalSupply'\n  | 'holders'\n  | 'liquidity';\n// ... and more\n\n// Wallet data fields\ntype WalletDataField = 'balance' | 'portfolio' | 'transactions' | 'staking';\n// ... and more\n```\n\n### 2. **Provider Routing**\n\nThe SDK automatically determines which provider to use for each field:\n\n```typescript\n// This request will:\n// - Get price from CoinGecko (best for market data)\n// - Get name/symbol from Blockfrost (authoritative on-chain data)\n// - Get balance from Blockfrost (only provider with wallet data)\nconst data = await sdk.getTokenData('asset_id', [\n  'price', // → CoinGecko\n  'name', // → Blockfrost\n  'symbol', // → Blockfrost\n  'balance', // → Blockfrost\n]);\n```\n\n### 3. **Data Aggregation**\n\nWhen multiple providers can supply the same field, the SDK aggregates intelligently:\n\n```typescript\n// Multiple providers might return price data\n// SDK will use priority order, fallbacks, and conflict resolution\nconst tokenData = await sdk.getTokenData('asset_id', ['price'], {\n  preferredProviders: ['coingecko'],\n  fallbackProviders: ['dexscreener', 'coinmarketcap'],\n});\n```\n\n### 4. **Caching Strategy**\n\nDifferent data types have different cache durations:\n\n- **Prices**: 30 seconds (frequently changing)\n- **Market Cap/Volume**: 1 minute\n- **Metadata**: 10 minutes (rarely changes)\n- **Balances**: 2 minutes\n- **Transaction History**: 5 minutes\n\n## API Reference\n\n### CardalabsSDK Class\n\n#### Constructor\n\n```typescript\nconstructor(config: CardalabsConfig = {})\n```\n\n#### Methods\n\n##### `initialize(): Promise<void>`\n\nInitializes the SDK with configured providers.\n\n```typescript\nawait sdk.initialize();\n```\n\n##### `getTokenData(assetUnit, fields, options): Promise<SDKResponse<TokenData>>`\n\nGets token data for a specific asset.\n\n**Parameters:**\n\n- `assetUnit: AssetUnit` - Asset identifier (policy ID + asset name or 'lovelace' for ADA)\n- `fields: TokenDataField[]` - Array of fields to retrieve\n- `options?: SDKMethodOptions` - Request options\n\n**Returns:** `Promise<SDKResponse<TokenData>>`\n\n```typescript\nconst response = await sdk.getTokenData('lovelace', ['price', 'marketCap', 'volume24h'], {\n  useCache: true,\n  timeout: 5000,\n  preferredProviders: ['coingecko'],\n});\n\nconsole.log(response.data.price);\nconsole.log(response.metadata.dataSources); // ['coingecko']\nconsole.log(response.metadata.responseTime); // 245ms\n```\n\n##### `getWalletData(address, fields, options): Promise<SDKResponse<WalletData>>`\n\nGets wallet data for a Cardano address.\n\n**Parameters:**\n\n- `address: CardanoAddress` - Cardano wallet address\n- `fields: WalletDataField[]` - Array of fields to retrieve\n- `options?: SDKMethodOptions` - Request options\n\n```typescript\nconst response = await sdk.getWalletData(\n  'addr1qx2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer3n0d3vllmyqwsx5wktcd8cc3sq835lu7drv2xwl2wywfgse35a3x',\n  ['balance', 'portfolio', 'transactions'],\n);\n\nconsole.log(response.data.balance);\nconsole.log(response.data.portfolio?.totalValue);\n```\n\n##### `getProviderHealth(): Promise<Record<string, ProviderHealth>>`\n\nGets health status of all providers.\n\n```typescript\nconst health = await sdk.getProviderHealth();\nconsole.log(health.blockfrost.healthy); // true\nconsole.log(health.coingecko.responseTime); // 150ms\n```\n\n##### `getStats(): Promise<SDKStats>`\n\nGets SDK usage statistics.\n\n```typescript\nconst stats = await sdk.getStats();\nconsole.log(stats.requests.total); // 1250\nconsole.log(stats.cache.hitRate); // 0.85\nconsole.log(stats.providers.coingecko.avgResponseTime); // 180ms\n```\n\n### Data Types\n\n#### TokenData\n\n```typescript\ninterface TokenData {\n  // Price data\n  price?: number;\n  priceUsd?: number;\n  marketCap?: number;\n  volume24h?: number;\n\n  // Price changes\n  priceChange24h?: number;\n  priceChangePercentage24h?: number;\n  priceChangePercentage7d?: number;\n\n  // Token metadata\n  name?: string;\n  symbol?: string;\n  decimals?: number;\n  description?: string;\n  logo?: string;\n\n  // Supply data\n  totalSupply?: number;\n  circulatingSupply?: number;\n  maxSupply?: number;\n  holders?: number;\n\n  // Trading data\n  high24h?: number;\n  low24h?: number;\n  ath?: number;\n  atl?: number;\n\n  // Metadata\n  lastUpdated?: Date;\n  dataSource?: string[];\n}\n```\n\n#### WalletData\n\n```typescript\ninterface WalletData {\n  // Balance information\n  balance?: { [assetUnit: string]: number };\n  balanceUsd?: number;\n\n  // Portfolio data\n  portfolio?: PortfolioData;\n\n  // Transaction history\n  transactions?: TransactionData[];\n\n  // Staking information\n  staking?: StakingData;\n\n  // Metadata\n  lastUpdated?: Date;\n  dataSource?: string[];\n}\n```\n\n## Examples\n\n### Example 1: Basic Token Price Lookup\n\n```typescript\nimport { CardalabsSDK } from '@cardalabs/sdk';\n\nasync function getAdaPrice() {\n  const sdk = new CardalabsSDK({\n    providers: {\n      coingecko: { apiKey: process.env.COINGECKO_API_KEY! },\n    },\n  });\n\n  await sdk.initialize();\n\n  const ada = await sdk.getTokenData('lovelace', ['price', 'priceChangePercentage24h']);\n\n  console.log(`ADA Price: $${ada.data.price}`);\n  console.log(`24h Change: ${ada.data.priceChangePercentage24h}%`);\n\n  await sdk.destroy();\n}\n```\n\n### Example 2: Portfolio Analysis\n\n```typescript\nimport { CardalabsSDK } from '@cardalabs/sdk';\n\nasync function analyzePortfolio(walletAddress: string) {\n  const sdk = new CardalabsSDK({\n    providers: {\n      blockfrost: { projectId: process.env.BLOCKFROST_PROJECT_ID! },\n      coingecko: { apiKey: process.env.COINGECKO_API_KEY! },\n    },\n  });\n\n  await sdk.initialize();\n\n  // Get wallet portfolio\n  const wallet = await sdk.getWalletData(walletAddress, ['balance', 'portfolio']);\n\n  console.log('Portfolio Analysis:');\n  console.log(`Total Value: $${wallet.data.portfolio?.totalValue}`);\n\n  // Analyze each asset\n  for (const asset of wallet.data.portfolio?.assets || []) {\n    console.log(`${asset.symbol}: ${asset.balance} ($${asset.valueUsd})`);\n\n    // Get detailed token data for each holding\n    const tokenData = await sdk.getTokenData(asset.assetUnit, [\n      'price',\n      'priceChangePercentage24h',\n      'marketCap',\n    ]);\n\n    console.log(`  Price: $${tokenData.data.price}`);\n    console.log(`  24h Change: ${tokenData.data.priceChangePercentage24h}%`);\n  }\n\n  await sdk.destroy();\n}\n```\n\n### Example 3: Multi-Provider Data Aggregation\n\n```typescript\nimport { CardalabsSDK } from '@cardalabs/sdk';\n\nasync function comprehensiveTokenAnalysis(assetUnit: string) {\n  const sdk = new CardalabsSDK({\n    providers: {\n      blockfrost: { projectId: process.env.BLOCKFROST_PROJECT_ID! },\n      coingecko: { apiKey: process.env.COINGECKO_API_KEY! },\n      dexscreener: { enabled: true },\n    },\n    providerPriorities: {\n      price: ['coingecko', 'dexscreener'],\n      name: ['blockfrost'],\n      totalSupply: ['blockfrost'],\n      volume24h: ['coingecko', 'dexscreener'],\n    },\n  });\n\n  await sdk.initialize();\n\n  // Get comprehensive token data from multiple providers\n  const token = await sdk.getTokenData(assetUnit, [\n    'price', // From CoinGecko\n    'name', // From Blockfrost\n    'symbol', // From Blockfrost\n    'marketCap', // From CoinGecko\n    'volume24h', // From CoinGecko/DexScreener\n    'totalSupply', // From Blockfrost\n    'holders', // From TapTools (if configured)\n    'priceChange24h', // From CoinGecko\n  ]);\n\n  console.log('Token Analysis:');\n  console.log(`Name: ${token.data.name} (${token.data.symbol})`);\n  console.log(`Price: $${token.data.price}`);\n  console.log(`Market Cap: $${token.data.marketCap?.toLocaleString()}`);\n  console.log(`24h Volume: $${token.data.volume24h?.toLocaleString()}`);\n  console.log(`Total Supply: ${token.data.totalSupply?.toLocaleString()}`);\n  console.log(`Data Sources: ${token.metadata?.dataSources.join(', ')}`);\n\n  await sdk.destroy();\n}\n```\n\n### Example 4: Real-time Price Monitoring\n\n```typescript\nimport { CardalabsSDK } from '@cardalabs/sdk';\n\nasync function monitorPrices(assets: string[]) {\n  const sdk = new CardalabsSDK({\n    providers: {\n      coingecko: { apiKey: process.env.COINGECKO_API_KEY! },\n    },\n    cache: {\n      fieldTtl: {\n        price: 10, // 10 second cache for real-time monitoring\n      },\n    },\n  });\n\n  await sdk.initialize();\n\n  // Monitor prices every 15 seconds\n  setInterval(async () => {\n    console.log('\\n--- Price Update ---');\n\n    for (const asset of assets) {\n      try {\n        const data = await sdk.getTokenData(asset, ['price', 'priceChangePercentage24h']);\n\n        const change = data.data.priceChangePercentage24h || 0;\n        const arrow = change >= 0 ? '🟢' : '🔴';\n\n        console.log(`${asset}: $${data.data.price} ${arrow} ${change.toFixed(2)}%`);\n      } catch (error) {\n        console.error(`Error fetching ${asset}:`, error);\n      }\n    }\n  }, 15000);\n\n  // Cleanup after 5 minutes\n  setTimeout(async () => {\n    await sdk.destroy();\n    process.exit(0);\n  }, 300000);\n}\n\n// Monitor ADA and popular Cardano tokens\nmonitorPrices(['lovelace', 'other-asset-ids']);\n```\n\n### Example 5: Error Handling and Fallbacks\n\n```typescript\nimport { CardalabsSDK } from '@cardalabs/sdk';\n\nasync function robustDataFetching() {\n  const sdk = new CardalabsSDK({\n    providers: {\n      blockfrost: { projectId: process.env.BLOCKFROST_PROJECT_ID! },\n      coingecko: { apiKey: process.env.COINGECKO_API_KEY! },\n    },\n  });\n\n  await sdk.initialize();\n\n  try {\n    const response = await sdk.getTokenData('lovelace', ['price', 'name'], {\n      preferredProviders: ['coingecko'],\n      fallbackProviders: ['blockfrost'],\n      maxRetries: 3,\n      timeout: 5000,\n    });\n\n    console.log('Data:', response.data);\n    console.log('Sources:', response.metadata?.dataSources);\n\n    // Check for any errors\n    if (response.errors && response.errors.length > 0) {\n      console.log('Partial errors occurred:');\n      response.errors.forEach((error) => {\n        console.log(`- ${error.provider}: ${error.error}`);\n      });\n    }\n  } catch (error) {\n    console.error('Complete failure:', error);\n  }\n\n  await sdk.destroy();\n}\n```\n\n### Request Flow\n\n```\n1. SDK.getTokenData() called\n2. Check cache for existing data\n3. If cache miss, create routing plan\n4. Execute requests to providers in parallel\n5. Aggregate responses and resolve conflicts\n6. Store result in cache\n7. Return unified response\n```\n\n### Cache Architecture\n\n```\n┌─────────────────┐\n│  Cache Manager  │\n└─────────────────┘\n          │\n┌─────────┬─────────┬─────────┐\n│ Memory  │  Redis  │  File   │ ← Pluggable cache backends\n└─────────┴─────────┴─────────┘\n```\n\n### Provider Capabilities\n\nEach provider declares its capabilities:\n\n```typescript\n// Blockfrost\n{\n  tokenData: ['name', 'symbol', 'decimals', 'totalSupply'],\n  walletData: ['balance', 'transactions'],\n  features: { historical: true, realtime: false }\n}\n\n// CoinGecko\n{\n  tokenData: ['price', 'marketCap', 'volume24h', 'priceChange24h'],\n  walletData: [],\n  features: { historical: true, realtime: false }\n}\n```\n","readmeFilename":"README.md","_rev":"1-6c08a89ee7c66f611795dd6bc48cc399"}