Carry and Roll-Down

Calculates the carry and roll-down of zero-coupon government bonds on every date: the return in excess of financing that a bond of each maturity earns over the horizon if the yield curve stays as it is. The bond earns its own yield over the financing rate (the carry) and, as it ages, is priced at the yield of a shorter maturity, which on an upward sloping curve is lower, so its price rises (the roll-down). Together they are the return an unchanged curve gives, the bond carry of Koijen, Moskowitz, Pedersen and Vrugt (2018): the yield spread over the short rate plus the roll-down. It shows where on the curve a position is paid most for holding it, and where an inverted curve makes holding a bond cost money.

The formula is as follows:

\[\text{Carry} = (1 + z(T))^{h} - (1 + r)^{h}\] \[\text{Roll-Down} = \frac{(1 + z(T))^{T}}{(1 + z(T - h))^{T - h}} - (1 + z(T))^{h}\] \[\text{Total} = \text{Carry} + \text{Roll-Down} = \frac{P(T - h)}{P(T)} - (1 + r)^{h}\]

where:

\[z(m) = \text{The zero-coupon rate of maturity}\; m,\;\; \text{annually compounded}\] \[P(m) = (1 + z(m))^{- m},\;\; \text{the price of a zero-coupon bond paying 1 at } m\] \[T = \text{The maturity of the bond},\;\; \text{in years}\] \[h = \text{The horizon},\;\; \text{in years}\] \[r = \text{The financing rate over the}\; \text{horizon:} \;\text{the zero-coupon rate of the horizon},\;\; z \text{(} h \text{)}\]

The curve is the zero-coupon curve of get_zero_coupon_curve, bootstrapped from the government bond par yields of the day (or published as zero-coupon rates for the Euro Area and Germany) and annually compounded, with the zero rate of every coupon date the bootstrap solves for. z(T - h) and z(h) are interpolated linearly on it, as for get_forward_rate, and held flat below the shortest maturity, so where the curve starts beyond the horizon (Germany at one year) the financing rate is the shortest rate. Beyond the longest maturity L the curve is held flat as well, so a bond with T - h at or beyond L has a roll-down of 0 and only the carry (1 + z(L))^h - (1 + z(h))^h. Each bond is repriced exactly on the unchanged curve: the carry is what it earns over the financing if its own yield stays z(T), the roll-down the price change from its yield moving to z(T - h), valued at the horizon. Every value is a return over the horizon, not annualized. Germany and Japan quote maturities from one year, so a horizon of a year avoids the flat extrapolation there. For a curve or a financing rate of your own, use yieldcurve_model.get_carry_and_roll_down.

To first order, with \(D = (T - h) / (1 + z (T))\) the modified duration (annual compounding) of the bond at the horizon, as Koijen et al. (2018) approximate it:

  • Carry ≈ \((z (T) - r) \times h\)
  • Roll-Down ≈ \(- D \times (z (T - h) - z (T))\)

For more information, see the following sources:

  • Koijen, R.S.J., Moskowitz, T.J., Pedersen, L.H. and Vrugt, E.B. (2018). “Carry.” Journal of Financial Economics, 127(2), 197-225.
  • Ilmanen, A. (2011). “Expected Returns: An Investor’s Guide to Harvesting Market Rewards.” Wiley, chapter 9.

Also known as: bond carry, rolldown, roll yield, horizon return on an unchanged curve.

Carry and Roll-Down in Python or via the MCP

Install the Finance Toolkit with:

pip install financetoolkit -U

Then call get_carry_and_roll_down as shown below.

from financetoolkit import FixedIncome

fixedincome = FixedIncome(start_date='2026-10-19', end_date='2026-10-23')

carry_and_roll_down = fixedincome.get_carry_and_roll_down(maturities='2Y,5Y,10Y,30Y')

carry_and_roll_down['United States']['Total']

Or, after setting up the Finance Toolkit MCP, ask:

What was the total carry and roll-down of 2-, 5-, 10- and 30-year US Treasuries each day from 19 to 23 October 2026?

Which returns:

Item 2Y 5Y 10Y 30Y
2026-10-19 0.0024 0.0022 0.0033 0.002
2026-10-20 0.0025 0.0022 0.0031 0.0019
2026-10-21 0.0026 0.0021 0.0032 0.0019
2026-10-22 0.0021 0.0017 0.0028 0.002
2026-10-23 0.0022 0.0019 0.003 0.002

Parameters

get_carry_and_roll_down accepts the following parameters.

ParameterTypeDescriptionExample
countrieslist[str] | strThe countries, see get_zero_coupon_curve. Defaults to “United States”.["United States", "Germany"]
periodstrWhether to use the daily, weekly or monthly curves. Defaults to “daily”."weekly"
horizonfloat | strThe holding period, in years or as a label such as “3M” or “1Y”. Defaults to 0.25 (three months).5
maturitieslist[float | str] | str | NoneThe maturities of the bonds, in years or as labels such as “2Y” (a list or a comma-separated string). A maturity shorter than the horizon is NaN. Defaults to None, every maturity of the curve longer than the horizon.["3M", "6M"]
roundingint | NoneThe number of decimals to round the results to. Defaults to None.2
show_columnsstr | list[str] | NoneThe columns to keep, a name or a list of names, matched on every column level, or the rows when no column has those names (such as the line items of a financial statement). Names that do not exist are logged, and when none exist the result is returned in full. Defaults to None, which keeps every column.None, which keeps every column
Share