bonds + marketplace

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

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

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):

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

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()).

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:

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:

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?)`

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:

const { bondVault } = await lumina.getContracts()

Getting started

Core concepts

For AI agents

MCP

SDK

Contracts

Reference

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

Redeeming a bond

Check redemption status first (throttle)

`lumina.marketplace.listings(params?)`

Looking up the BondVault address

​lumina.bonds.list({ wallet? })

​Redeeming a bond

​Check redemption status first (throttle)

​lumina.marketplace.listings(params?)

​Looking up the BondVault address

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

Redeeming a bond

Check redemption status first (throttle)

`lumina.marketplace.listings(params?)`

Looking up the BondVault address