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

# bonds + marketplace

> lumina.bonds + lumina.marketplace — read bond positions, check redemption status, and browse listings.

<Note>
  See [/concepts/lifecycle](/concepts/lifecycle) for the end-to-end flow (policy → trigger → bond → wait/sell decision).
</Note>

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

```ts theme={null}
const bonds = await lumina.bonds.list()
//   [{ bondId, owner, amount, faceValueUsdc, pricePerBondUsdc?, maturityEpoch? }]
```

Defaults to the calling wallet. Pass `wallet` to target an explicit
address (must match the API key's owner — otherwise 403):

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

The shape is intentionally loose — fields beyond `bondId / owner / amount /
faceValueUsdc` may be undefined depending on whether the API has indexed
them yet.

Bonds are issued at 80% of the triggered policy's coverage and mature at
**730 days** at 2.00× collateral margin.

## Redeeming a bond

<Note>
  There is **no `lumina.bonds.redeem()`** REST method. `lumina.bonds` exposes
  only `list()`. Redemption is an **on-chain** action against `BondVault`, and
  the SDK helps you (a) check whether a redemption would settle now or be
  throttled (`BondQueue.getRedemptionStatus`) and (b) resolve the `BondVault`
  address (`getContracts()`).
</Note>

Redemption is performed on-chain by calling `BondVault.redeemBond(epochId, usdAmount)`
from the bond holder's wallet (`usdAmount` is the requested USD face in integer
dollars). Pull the address at runtime so a redeploy never strands your bot:

```ts theme={null}
import { BondQueue, bondVaultAbi } from '@lumina-org/sdk'
import { ethers } from 'ethers'

const { bondVault } = await lumina.getContracts()
const bv = new ethers.Contract(bondVault, bondVaultAbi, signer)
await bv.redeemBond(202805, 250)   // epochId, USD face (integer dollars)
```

### Check redemption status first (throttle)

BondVault enforces a **per-epoch redemption throttle** + a solvency floor. Use
the `BondQueue` helper to learn whether a redemption settles immediately
(`ready`), would be queued (`queued`), or the epoch is not yet matured
(`matured-pending`) — before sending the on-chain tx:

```ts theme={null}
import { BondQueue } from '@lumina-org/sdk'

const queue = new BondQueue(bv)
const status = await queue.getRedemptionStatus(/* holder, epochId, usdAmount */)
//   { status: 'ready' | 'queued' | 'matured-pending', ... }
```

If a redemption is over the epoch cap it is **queued** (FIFO) and paid when
`processQueue()` is called against the target epoch — not reverted.

## `lumina.marketplace.listings(params?)`

```ts theme={null}
const listings = await lumina.marketplace.listings({
  limit: 50,                     // default 50
  offset: 0,                     // default 0
  sortBy: 'price-asc',           // 'price-asc' | 'price-desc' | 'createdAt-desc' | 'listedAt-desc'
  maxPriceUsdc: '5000000000',    // optional; filter active listings to ≤ this price
})
```

Returns active listings only (status='active'). To see your own listings
that have been executed, query the on-chain marketplace directly via your
RPC.

## Looking up the BondVault address

If you need to call `BondVault` directly (e.g. for an off-chain redemption
path your bot already implements), pull the address from
`getContracts()` so a redeploy doesn't strand your bot on a stale address:

```ts theme={null}
const { bondVault } = await lumina.getContracts()
```