---
title: "Bond Ladder Builder"
method: POST
path: "/v1/tools/build_bond_ladder"
tags: ["bond_ladder", "fixed-income", "duration", "dv01", "convexity", "reinvestment-assumption", "portfolio-risk", "tvm-primitive", "mcp:build_bond_ladder"]
---

# Bond Ladder Builder

`POST /v1/tools/build_bond_ladder`

## Request

- Base URL: `https://ainumbers.co`
- URL: `https://ainumbers.co/v1/tools/build_bond_ladder`
- Auth: none declared

Builds a target-weight bond ladder from a total notional split across maturity rungs and reports rung-by-rung and portfolio risk analytics: each rung's price, Macaulay and modified duration, DV01 and convexity, plus the target_weight-weighted portfolio aggregates. Every reinvestment assumption is named in plain sentences in the output, and rung target weights must sum to 1 within 1e-9 or the tool refuses, naming the sum.

**Tool URL:** https://ainumbers.co/chaingraph/art-705-bond-ladder-builder.html
**AP2/Policy Mandate export:** yes

## Request body

- object
  - `notional` number, required: Total ladder notional, split across rungs pro rata to target_weight.
  - `rungs` object[], required: One object per rung: { maturity_years, coupon_rate_pct, yield_pct, target_weight }. Target weights must sum to 1 within 1e-9.
    - `maturity_years` number
    - `coupon_rate_pct` number
    - `yield_pct` number
    - `target_weight` number
  - `periods_per_year` number: Coupon periods per year for every rung (default 2).
  - `reinvestment_assumption` 'hold_to_maturity' | 'roll_to_longest_rung': Named in the output assumptions[]: hold coupons and maturing principal as cash at 0%, or reinvest them at the longest rung's yield.

## Response `200`

Successful tool execution result

- object
  - `assumptions` string[], required
  - `detail` string
  - `domain_errors` object[]
    - `code` 'REINVESTMENT_ASSUMPTION_INVALID' | 'WEIGHTS_SUM_NOT_ONE', required
    - `text` string, required
  - `error` 'reinvestment_assumption_invalid' | 'weights_sum_not_one'
  - `ladder` unknown, required
  - `note` string
  - `notional` number
  - `num_rungs` number
  - `periods_per_year` number
  - `portfolio` object, nullable, required
  - `regulatory_basis` string
  - `reinvestment_assumption` 'hold_to_maturity' | 'roll_to_longest_rung'

---

[API](https://skmtc.dev/ainumbers/apis/ainumbers-co-fintech-intelligence-suite.md) · [All operations](https://skmtc.dev/ainumbers/apis/ainumbers-co-fintech-intelligence-suite/llms.txt) · [OpenAPI document](https://skmtc.dev/ainumbers/apis/ainumbers-co-fintech-intelligence-suite/revisions/b462e4f5bb28?raw)