{
  "tool_id": "bond_yield_calculator",
  "slug": "bond-yield-calculator",
  "path": "/personal-finance/bond-yield-calculator/",
  "mode": "url_api",
  "api_usage": "GET https://aifinhub.io/api/bond-yield-calculator/?<params>",
  "sample_input": {
    "tool": "bond_yield_calculator",
    "face_value": 1000,
    "coupon_rate": 5,
    "years_to_maturity": 10,
    "current_price": 950,
    "coupon_frequency": 2
  },
  "input_schema": {
    "type": "object",
    "properties": {
      "tool": {
        "type": "string"
      },
      "face_value": {
        "type": "number"
      },
      "coupon_rate": {
        "type": "number"
      },
      "years_to_maturity": {
        "type": "number"
      },
      "current_price": {
        "type": "number"
      },
      "coupon_frequency": {
        "type": "number",
        "enum": [
          1,
          2,
          4
        ]
      },
      "call_price_percent": {
        "type": "number"
      },
      "years_to_call": {
        "type": "number"
      }
    },
    "required": [
      "tool",
      "face_value",
      "coupon_rate",
      "years_to_maturity",
      "current_price"
    ]
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "currentYield": {
        "type": "number",
        "description": "Annual coupon / current price (decimal)"
      },
      "yieldToMaturity": {
        "type": "number",
        "description": "YTM annualized (decimal)"
      },
      "yieldToCall": {
        "type": [
          "number",
          "null"
        ],
        "description": "YTC annualized (decimal), null if no call params provided"
      },
      "macaulayDuration": {
        "type": "number",
        "description": "Macaulay duration in years"
      },
      "modifiedDuration": {
        "type": "number",
        "description": "Price sensitivity per 1% yield change"
      },
      "dv01": {
        "type": "number",
        "description": "Dollar value of 1 basis point move"
      },
      "totalCouponIncome": {
        "type": "number",
        "description": "Sum of all coupon payments"
      },
      "gainLossAtMaturity": {
        "type": "number",
        "description": "Face value minus current price"
      },
      "totalReturn": {
        "type": "number",
        "description": "Total coupon income + gain/loss at maturity"
      },
      "schedule": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "period": {
              "type": "number"
            },
            "payment": {
              "type": "number"
            },
            "presentValue": {
              "type": "number"
            },
            "cumulativePV": {
              "type": "number"
            }
          }
        }
      },
      "warnings": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    }
  }
}