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

# Bond Marketplace

> Trade ClaimBonds before maturity. P2P, USDC settlement, 3% fee (1.5% seller + 1.5% buyer) burned.

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

The Lumina Bond Marketplace is the on-chain secondary market for
`ClaimBond` ERC-1155 tokens. Holders who can't (or don't want to) wait
until 730-day maturity sell their bonds for **USDC** today; buyers who
want redemption upside pick them up at a discount and redeem in
**LUMINA** at maturity.

## TL;DR

* **P2P trading.** Listings are on-chain; sellers escrow bonds in the
  marketplace contract until filled or cancelled.
* **USDC settlement.** Both sides settle in USDC — sellers receive USDC,
  buyers pay USDC.
* **ERC-1155 transfers.** Bond ownership moves via `safeTransferFrom`
  on `ClaimBond` (the maturity stays tied to the token, not the wallet).
* **3% fee — burned.** A **3% total** fee (**1.5% seller + 1.5% buyer**,
  `SELLER_FEE_BPS=150` / `BUYER_FEE_BPS=150`) is taken on each fill and
  routed through `AdaptiveFeeDistributor`: the 85% slice is
  TWAP-burned (LUMINA bought back and burned); the 8/2/5 slices fund
  buyback / ops / maintenance.
* **Anti-spam floor.** `minPricePerUnit = $1` (1\_000\_000 raw, 6-dec USDC).
  Audit fix M-3.

## What is the marketplace?

Bonds are minted to a wallet when a policy's parametric trigger fires.
They're an obligation to pay the holder **LUMINA** at maturity (730 days).
For agents that need liquidity sooner — to rotate into a new position, to
cover op-ex, or simply because they don't want 2-year duration risk —
waiting isn't an option.

The marketplace solves that. It's a fully on-chain order-book where any
holder can list a bond at a chosen `pricePerUnit` (in USDC), and any
buyer can match. Sellers exit in USDC immediately; buyers acquire bonds
they'll later redeem for LUMINA at maturity. The protocol takes a 3%
total fee (**1.5% from the seller + 1.5% from the buyer**) that is
**burned** (split via the AdaptiveFeeDistributor 85/8/2/5 schedule that
applies to every protocol fee stream).

Listings are owned by the seller until filled or cancelled. Bond
ownership is escrowed in the marketplace contract on `list()` and
atomically transferred to the buyer on `buy()`.

## How it works

1. **Policy bought.** Agent pays USDC premium and receives an active policy.
2. **Trigger fires.** The shield mints a `ClaimBond` (ERC-1155, $800 per
   $1k cover) to the buyer's wallet.
3. **Seller lists.** One-time `marketplace.approveBonds()` (ERC-1155
   approval), then `marketplace.list({ bondId, amount, pricePerUnit, expiresAt })`.
   The bond tokens are escrowed in the marketplace contract.
4. **Buyer browses & fills.** Reads `marketplace.listings()` /
   `marketplace.listing(id)` / `marketplace.estimateBuyPrice(...)`,
   approves USDC via `marketplace.approve(usdcAmount)`, then calls
   `marketplace.buy({ listingId, amount })`.
5. **Atomic settlement.** Seller receives
   `pricePerUnit * amount * (1 - 150 bps)` in USDC (1.5% seller fee), and
   the buyer pays an additional 1.5% on top. The combined 3% fee is sent
   to `AdaptiveFeeDistributor` for the standard 85/8/2/5 burn-split.
6. **Buyer holds → redeems.** At maturity (730d epoch), buyer calls
   `BondVault.redeem(epochId)` and receives **LUMINA**.

## Fee — 3% burned (1.5% seller + 1.5% buyer)

| Item        | Value                                                                    |
| ----------- | ------------------------------------------------------------------------ |
| Total fee   | **300 bps (3%)**                                                         |
| Seller fee  | **150 bps (1.5%)** — `SELLER_FEE_BPS=150`, deducted from seller proceeds |
| Buyer fee   | **150 bps (1.5%)** — `BUYER_FEE_BPS=150`, added on top of the fill price |
| Destination | `AdaptiveFeeDistributor`                                                 |
| Burn split  | 85% TWAP-burned LUMINA / 8% buyback / 2% ops / 5% maintenance            |

V5.4 charges a maker/taker-style split: the seller (maker) pays 1.5% and
the buyer (taker) pays 1.5%, for a 3% total per fill, burned via the same
path that handles policy premium fees.

## Anti-spam floor

`minPricePerUnit` is enforced on-chain at `1_000_000` raw (`$1` in 6-dec
USDC). Any `list()` call with `pricePerUnit` below this floor reverts.
This prevents an attacker from spamming the order book with sub-cent
listings to grief frontends and indexers. (Audit fix M-3.)

## For AI agents

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

const lumina = new LuminaClient({ apiKey: process.env.LUMINA_API_KEY! })

// One-time approval for the marketplace to move bond tokens on your behalf.
await lumina.marketplace.approveBonds()

// Sell 50 tokens of bond #202805 at $0.97/token, expires in 7 days.
await lumina.marketplace.list({
  bondId: '202805',
  amount: '50',
  pricePerUnit: '970000',                          // 0.97 in 6-dec USDC
  expiresAt: Math.floor(Date.now() / 1000) + 7 * 86400,
})
```

To buy, browse listings and fill atomically:

```ts theme={null}
const listings = await lumina.marketplace.listings({ sortBy: 'price-asc' })
const target = listings[0]

const quote = await lumina.marketplace.estimateBuyPrice({
  listingId: target.id, amount: '10',
})

await lumina.marketplace.approve(quote.totalUsdc)
await lumina.marketplace.buy({ listingId: target.id, amount: '10' })
```

Available SDK methods (`@lumina-org/sdk` ≥ `0.5.0`):
`marketplace.listings`, `marketplace.listing`, `marketplace.stats`,
`marketplace.history`, `marketplace.myListings`, `marketplace.list`,
`marketplace.buy`, `marketplace.cancel`, `marketplace.approve`,
`marketplace.approveBonds`.

## For humans

Prefer the UI? The hosted marketplace lives at
[lumina-org.com/app/human/marketplace](https://www.lumina-org.com/app/human/marketplace).

## API endpoints

| Method | Path                               | Status   |
| ------ | ---------------------------------- | -------- |
| GET    | `/api/v1/marketplace/listings`     | Existing |
| POST   | `/api/v1/marketplace/list`         | Existing |
| POST   | `/api/v1/marketplace/buy`          | Existing |
| GET    | `/api/v1/marketplace/stats`        | Existing |
| GET    | `/api/v1/marketplace/history`      | Existing |
| GET    | `/api/v1/marketplace/listings/:id` | Existing |

## Smart contract

The marketplace is deployed on Base mainnet at
[`0xfB3ec1B507DE8a7dB50691a26f872360F0EF71AB`](https://basescan.org/address/0xfB3ec1B507DE8a7dB50691a26f872360F0EF71AB).
The live address is also exposed via the
[`/health`](https://lumina-api-production-ac85.up.railway.app/health)
endpoint — agents should always read it from there rather than hard-coding.

> **Note** — Premium for **policies** is paid in USDC. Bonds in the
> **marketplace** are also bought/sold in USDC. **Redeem at maturity** is
> in **LUMINA** — not USDC.