Monitor your bonds

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

Once a policy triggers, the bond shows up in lumina.bonds.list(). The agent’s job is to notice the trigger fast and decide what to do with the bond.

Two ways to notice a trigger

A) Webhook (push, recommended)

Subscribe once, receive an HMAC-signed JSON POST when the trigger lands on-chain. End-to-end latency from on-chain settlement to your endpoint is 0–30s (the worker polls a queue every 30s).

const sub = await lumina.webhooks.create({
  url:    'https://my-bot.example.com/webhooks/lumina',
  events: ['policy_triggered', 'bond_minted', 'bond_redeemed'],
})
// store sub.secret in your secrets manager

The body of a policy_triggered event contains policyId, productId, bondId, faceValueUsdc, txHash, and the on-chain triggeredAt epoch. See Webhooks for the signature-verification snippet.

B) Polling (pull)

Cheap when you only hold a handful of active policies. Hit GET /api/v1/policies/:id on an interval — every 30s is plenty:

const p = await lumina.policies.get(productId, policyId)
if (p.status === 'triggered') {
  console.log('triggered — bond', p.bondId, 'minted')
}

p.status is one of active | triggered | expired. For the bond face value and maturity epoch, list your bonds and find the matching bondId (BondsAPI exposes only list() — there is no bonds.get()):

const bonds = await lumina.bonds.list(wallet)
const bond = bonds.find((b) => b.bondId === p.bondId)
//   { bondId, amount, faceValueUsdc, maturityEpoch, … }

Trigger events

Event	Fires when
`policy_triggered`	Oracle proof accepted by the shield, payout enqueued
`bond_minted`	`BondVault.mint` settled on-chain (usually same tx as `policy_triggered`)
`bond_redeemed`	A bond is redeemed for $LUMINA at maturity (730 days post-mint)
`listing_created` / `listing_purchased`	You listed / sold a bond on the marketplace

Read positions

const bonds = await lumina.bonds.list()
//   [{ bondId: '202805', amount: '50', faceValueUsdc: '50000000', maturityEpoch: 12345 }, …]

Filtered server-side to the calling wallet. Cross-wallet reads are forbidden (the on-chain data is public; the API just refuses to act as an unauthenticated indexer).

Bond redemption flow

Bonds are ERC-1155,

1 face value per unit, with a **730-day maturity** from mint. Once mature, redeem on-chain for `

LUMINAviaBondVault.redeem(or the SDK wrapper if exposed). The vault enforces a per-epoch throttle ofMAX_REDEMPTION_PER_EPOCH_BPS = 108` — 1.08% per week of the epoch’s outstanding face, FIFO queued post-throttle. This is the anti bond-run safeguard described in BondVault throttle. If you need cash sooner than 730 days, list the bond on the marketplace — typical discount is 2–5%, with 150 bps maker + 150 bps taker fees.

Decision rule

Condition	Action
Need cash today	List on marketplace at `face × discount` (typically 95-98%)
Maturity is < 24 h away	Hold and redeem on-chain at maturity
Want to compound	Hold; redeem; immediately rotate into a new policy

Listing logic

const listings = await lumina.marketplace.listings({ sortBy: 'price-asc', limit: 5 })
const cheapest = listings[0]

// Buy if discount > 5%
if (cheapest && BigInt(cheapest.totalPriceUsdc) < (BigInt(cheapest.amount) * 95n) / 100n) {
  // … snipe
}

Pinning maturity

bond.maturityEpoch (where exposed) is a wall-clock seconds value. To get seconds-until-maturity:

const secondsToMaturity = bond.maturityEpoch - Math.floor(Date.now() / 1000)

If the SDK doesn’t expose maturityEpoch on a particular response shape, query the on-chain BondVault.epochInfo(epochId) directly via your RPC.

Getting started

Core concepts

For AI agents

MCP

SDK

Contracts

Reference

Two ways to notice a trigger

A) Webhook (push, recommended)

B) Polling (pull)

Trigger events

Read positions

Bond redemption flow

Decision rule

Listing logic

Pinning maturity

​Two ways to notice a trigger

​A) Webhook (push, recommended)

​B) Polling (pull)

​Trigger events

​Read positions

​Bond redemption flow

​Decision rule

​Listing logic

​Pinning maturity

Two ways to notice a trigger

A) Webhook (push, recommended)

B) Polling (pull)

Trigger events

Read positions

Bond redemption flow

Decision rule

Listing logic

Pinning maturity