Skip to main content
npm · Source on GitHub · API spec 
npm install @lumina-org/sdk@^0.6.0 ethers
# or
pnpm add @lumina-org/sdk@^0.6.0 ethers
# or
yarn add @lumina-org/sdk@^0.6.0 ethers
@lumina-org/sdk@^0.6.0 is the V5.4 minimum. Older 0.5.x releases are pinned to the legacy 9-product catalog and will not resolve the V5.4 flash product names. ethers v6 is a peer-ish dependency — used for asset bytes32 encoding and for the Signer type accepted by agent.onboard(signer).

​
Verify connectivity

import { LuminaClient } from '@lumina-org/sdk'

const lumina = new LuminaClient({ apiKey: '' })  // empty for unauthenticated /health
const health = await lumina.health()
console.log(health.chain.chainId)   // 8453 (Base mainnet)

​
Configuration

new LuminaClient({
  apiKey: 'lk_…',                                                   // required (pass "" for onboard / sandbox / health)
  apiUrl: 'https://lumina-api-production-ac85.up.railway.app',      // default
})
For local dev against a checked-out lumina-api: 
const lumina = new LuminaClient({ apiKey: 'lk_test', apiUrl: 'http://localhost:3000' })

​
Runtime address resolution

Starting in 0.5.2 (and carried into 0.6.0), the SDK resolves contract addresses at runtime from /health rather than embedding a hard-coded deployment manifest. The result is cached for the lifetime of the LuminaClient instance: 
const contracts = await lumina.getContracts()
//   { bondVault, coverRouter, luminaOracleV2, marketplace, … }
This means a LuminaClient built today automatically picks up any redeploy without an SDK bump — provided the new addresses are reflected in /health.

​
Product catalog (6 products in 0.6.0)

PRODUCT_ASSET_MAP was reduced from 9 to 6 entries in 0.6.0. The three retired names (FLASHBTC4H-001, MICRODEPEG-001, RATESHOCK-001) are no longer in the catalog. The 6 active V5.4 flash products are:
productNameAssetTrigger
FLASHBTC1H-001BTC-2.5% / 1h
FLASHBTC24-001BTC-6.0% / 24h
FLASHBTC48-001BTC-10.0% / 48h
FLASHETH1H-001ETH-4.0% / 1h
FLASHETH24-001ETH-8.5% / 24h
FLASHETH48-001ETH-14.0% / 48h

​
TypeScript

The SDK is written in TypeScript and ships its own .d.ts. No @types/lumina-org__sdk — types are bundled.

​
Node version

Node 18+ is required (the SDK uses the global fetch).

​
Migrating from v0.5.x to v0.6.0

v0.6.0 signals V5.4 protocol live. Breaking changes for legacy consumers:
  • PRODUCT_ASSET_MAP is now 6 entries (was 9). Calls to getExpectedAsset("FLASHBTC4H-001" | "MICRODEPEG-001" | "RATESHOCK-001") now throw Unknown product. Migrate to one of the 6 active flash names.
  • No breaking changes to public method signatures. LuminaClient, policies.*, bonds.*, marketplace.*, webhooks.*, sandbox.*, agent.*, getContracts() all keep the same shape.
  • Recommended: pin to ^0.6.0 in package.json to track V5.4 protocol updates without re-publishing your bot.