> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumina-org.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install @lumina-org/sdk and verify connectivity in 30 seconds.

[![npm](https://img.shields.io/npm/v/@lumina-org/sdk)](https://www.npmjs.com/package/@lumina-org/sdk) · [Source on GitHub](https://github.com/org-lumina/lumina-sdk) · [API spec](https://lumina-api-production-ac85.up.railway.app/openapi.json)

```bash theme={null}
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

```ts theme={null}
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

```ts theme={null}
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:

```ts theme={null}
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:

```ts theme={null}
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:

| productName      | Asset | Trigger      |
| ---------------- | ----- | ------------ |
| `FLASHBTC1H-001` | BTC   | -2.5% / 1h   |
| `FLASHBTC24-001` | BTC   | -6.0% / 24h  |
| `FLASHBTC48-001` | BTC   | -10.0% / 48h |
| `FLASHETH1H-001` | ETH   | -4.0% / 1h   |
| `FLASHETH24-001` | ETH   | -8.5% / 24h  |
| `FLASHETH48-001` | ETH   | -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.