# Bond coupon

Source: https://docs.settlemint.com/docs/developers/corporate-actions/bond-coupon
Pay periodic bond coupons through the fixed-treasury-yield feature, from funding the treasury to holder claims and maturity.



A bond coupon pays holders a fixed rate on their position at a fixed interval. You run the whole coupon lifecycle on the fixed-treasury-yield feature: it defines the schedule, accrues entitlement per period from on-chain balance history, and pays each holder from your treasury when they claim. Principal repayment at maturity runs on the separate maturity-redemption feature.

<Mermaid
  chart="flowchart TD
  Issue[&#x22;Issue the bond<br/>POST /tokens (template includes<br/>fixed-treasury-yield)&#x22;] --> Fund[&#x22;Fund the treasury<br/>POST .../fixed-treasury-yield/top-ups&#x22;]
  Fund --> Approve[&#x22;Treasury approves the schedule<br/>POST .../treasury-allowance&#x22;]
  Approve --> Period[&#x22;Coupon period completes<br/>(interval elapsed)&#x22;]
  Period --> Claim[&#x22;Holders claim accrued coupons<br/>POST .../fixed-treasury-yield/claims&#x22;]
  Claim --> Coverage[&#x22;Monitor coverage<br/>GET .../stats/yield-coverage&#x22;]
  Coverage -->|Next period| Fund
  Coverage -->|Maturity date reached| Mature[&#x22;Mature the bond<br/>POST .../maturity-redemption/maturations&#x22;]
  Mature --> Redeem[&#x22;Holders redeem principal<br/>POST .../maturity-redemption/redemptions&#x22;]"
/>

## Prerequisites [#prerequisites]

* API key for a wallet with the governance role on the bond (see [Getting started](/docs/api-reference/reference/getting-started)).
* The bond carries the fixed-treasury-yield feature. Most bond templates include it at creation; attach it to a configurable bond that lacks it through `POST /api/v2/tokens/{tokenAddress}/features` with `"name": "fixed-treasury-yield"`.
* A treasury wallet funded in the bond's denomination asset before each period completes.

## Paying coupons [#paying-coupons]

<Steps>
  <Step>
    ### Configure the schedule at issuance [#configure-the-schedule-at-issuance]

    The coupon terms are the feature's configuration: `rate` in basis points per period, `interval` (`MONTHLY`, `QUARTERLY`, `SEMI_ANNUAL`, `YEARLY`, and shorter steps), `startDate`, `endDate`, the `denominationAsset` the coupon pays in, and the `treasury` wallet it pays from. A 500 basis point rate on a quarterly interval pays 5 percent of the per-unit basis each quarter. Bond templates collect these fields during asset creation; see the [token lifecycle reference](/docs/api-reference/tokens/token-lifecycle) for the create call.
  </Step>

  <Step>
    ### Fund the treasury before each period completes [#fund-the-treasury-before-each-period-completes]

    Coupons pull from the treasury wallet at claim time, so your treasury needs balance and the schedule needs an allowance.

    ```bash
    curl -X POST "https://your-platform.example.com/api/v2/tokens/0x2f1De1B3d69cdCcbE743563b1EC1cA43663dbdb9/features/fixed-treasury-yield/top-ups" \
      -H "X-Api-Key: sm_dalp_test_xxxxxxxxxxxxxxxx" \
      -H "Idempotency-Key: coupon-fund-nwb-2026-q3" \
      -H "Content-Type: application/json" \
      -d '{ "amount": "50000000000" }'
    ```

    Then the treasury wallet signs `POST .../fixed-treasury-yield/treasury-allowance` to authorize the schedule to pay claims. Approve at least the expected coupon pool for the period; an insufficient allowance fails holder claims even when the balance is there.
  </Step>

  <Step>
    ### Holders claim after the period completes [#holders-claim-after-the-period-completes]

    Once a period ends, each holder claims all completed, unclaimed periods in one call.

    ```bash
    curl -X POST "https://your-platform.example.com/api/v2/tokens/0x2f1De1B3d69cdCcbE743563b1EC1cA43663dbdb9/features/fixed-treasury-yield/claims" \
      -H "X-Api-Key: sm_dalp_test_xxxxxxxxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{}'
    ```

    Entitlement per period comes from the holder's on-chain balance history in that period, so secondary-market buyers accrue from the period they bought into. A claim that spans many completed periods settles a bounded number per call and reports whether it is complete, so repeat the call until nothing remains. Pending claims appear to each holder in the [actions feed](/docs/api-reference/reference/actions).
  </Step>

  <Step>
    ### Monitor coverage between periods [#monitor-coverage-between-periods]

    `GET .../stats/yield-coverage` reports what share of accrued, unclaimed coupons your treasury balance and allowance cover. `GET .../treasury/health` rolls the same checks into a single status. Fund a shortfall before the next period completes, not after your holders start claiming.
  </Step>

  <Step>
    ### Redeem principal at maturity [#redeem-principal-at-maturity]

    At the maturity date, close the bond with `POST .../maturity-redemption/maturations`, then holders call `POST .../maturity-redemption/redemptions` to swap tokens for principal at face value, paid from its own treasury. The [maturity redemption reference](/docs/api-reference/token-features/maturity-redemption) documents funding and allowance for the principal leg, which mirror the coupon leg.
  </Step>
</Steps>

## Operational notes [#operational-notes]

* The claim model is pull-based. An unclaimed coupon stays in the treasury and stays claimable; it does not expire at the next period.
* Coupon amounts are integer strings in the denomination asset's base units; see [asset decimals](/docs/api-reference/reference/asset-decimals).
* Bonds issued before the feature-based model use a standalone yield schedule with the same lifecycle under different paths; see the [fixed yield schedule reference](/docs/api-reference/token-features/fixed-yield-schedule).

## Related guides [#related-guides]

* [Cash dividend](/docs/developers/corporate-actions/cash-dividend) runs the same feature on equities.
* [Fixed treasury yield API reference](/docs/api-reference/token-features/fixed-treasury-yield) documents every endpoint, parameter, and error of the feature.
* [Fixed treasury yield how-to](/docs/operators/token-features/fixed-treasury-yield) covers the same flow through the Console.