> ## 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.

# policies

> lumina.policies — list, get, purchase.

## `lumina.policies.list({ wallet? })`

```ts theme={null}
const policies = await lumina.policies.list()
//   [{ policyId, productId, buyer, coverageAmount, premiumPaid, txHash, status, … }]
```

Defaults to the calling wallet (server-side filter from the API key).
Passing an explicit `wallet` is supported but ignored unless the API key
owns that wallet — cross-wallet listing returns 403.

```ts theme={null}
const mine = await lumina.policies.list({ wallet: '0xabc…' })
```

## `lumina.policies.get(productId, policyId)`

Public — no API key required.

```ts theme={null}
const p = await lumina.policies.get(
  '0xdc5bcc7d…',         // bytes32 productId
  '42'                    // policyId
)
```

## `lumina.policies.purchase({ productName, buyer, coverageAmount })`

The SDK auto-resolves both the `productId` keccak hash AND the per-shield
`asset` literal from `productName`. Pass `productName` whenever you can:

```ts theme={null}
const receipt = await lumina.policies.purchase({
  productName: 'FLASHBTC24-001',  // resolves productId + asset='BTC'
  buyer: '0x…',
  coverageAmount: '1000000000',   // $1,000 in 6-dec USDC base units
  idempotencyKey: 'uuid-v4',      // optional but recommended
})
```

`productName` must be one of the 6 V5.3 catalog entries:

* `FLASHBTC1H-001`
* `FLASHBTC24-001`
* `FLASHBTC48-001`
* `FLASHETH1H-001`
* `FLASHETH24-001`
* `FLASHETH48-001`

Any other product name will throw `Unknown product` at the SDK boundary
before any network call is made.

Or pass `productId` explicitly — the SDK still auto-resolves the asset by
reverse-lookup against the canonical registry:

```ts theme={null}
const receipt = await lumina.policies.purchase({
  productId: '0xe87625ef…',       // FLASHBTC1H-001 hash
  buyer: '0x…',
  coverageAmount: '1000000000',
})
```

Returns:

```ts theme={null}
{
  txHash: '0x…',
  blockNumber: 12345,
  policyId: '7',
  buyer: '0x…',
  productId: '0x…',
  coverageAmount: '1000000000',
  premiumPaid: '52600000',         // 6-dec USDC base units; FLASHBTC24-001 = $52.60 per $1k cover
}
```

### Premium reference (per \$1k coverage)

| productName      | Premium  |
| ---------------- | -------- |
| `FLASHBTC1H-001` | \$2.92   |
| `FLASHBTC24-001` | \$52.60  |
| `FLASHBTC48-001` | \$148.67 |
| `FLASHETH1H-001` | \$1.68   |
| `FLASHETH24-001` | \$45.80  |
| `FLASHETH48-001` | \$123.01 |

Quotes can be re-fetched live via `lumina.products.quote(productId,
coverageAmount)` and are the authoritative source if you're displaying a
price to a user.

### Asset encoding

The `asset` field is **optional** when `productName` or a registered
`productId` is supplied. To override, pass a symbol (`'BTC' | 'ETH' | 'USDC' | 'USDT'`) or a 32-byte hex string:

```ts theme={null}
asset: 'BTC'    // encoded to 0x4254430000…0000 for you
asset: '0x4554480000000000000000000000000000000000000000000000000000000000'
```

See [Products and assets](/agents/products-and-assets) for the full per-shield
table and a list of `InvalidAsset` failure modes.

### Idempotency

Always pass `idempotencyKey` on retryable purchases. The header value is
forwarded as `Idempotency-Key`. Replays return the original response; no
double-charge.