Install and authenticate
Use Node 22 or later. Set your API key in the NARWHAL_API_KEY environment variable. Keep the SDK server-side and never put the key in browser code. Follow the quickstart for setup.
// npm install narwhalapi
import { Narwhal } from "narwhalapi";
// Reads NARWHAL_API_KEY from the server environment.
const nw = new Narwhal();Fetch the latest yield curve
Request USA yields for the 2-year and 10-year maturities. The response contains date, curve_type and yields, with maturity and yield_percent for each entry. Decimal values arrive as exact strings, such as "4.25". See the yield curve reference.
const curve = await nw.economics.yieldCurve("USA", { maturity: ["2y", "10y"] });
console.log(curve.date, curve.curve_type);
for (const point of curve.yields) {
console.log(point.maturity, point.yield_percent);
}Read daily history
Set start and end to your requested date range. The iterator pages through daily history lazily, with up to 1,000 dates per page. This example requests Germany's 10-year yield.
for await (const day of nw.economics.yieldCurveHistoryIter("DEU", {
maturity: ["10y"],
start: "2026-01-01",
end: "2026-03-31",
})) {
console.log(day.date, day.yields[0]?.yield_percent);
}Check for an inverted curve
Subtract the 2-year yield from the 10-year yield on the same curve. A negative spread means inversion. Calculate only when both maturities exist. This example converts the decimal strings to numbers for calculation.
const yieldOf = (maturity: string) =>
curve.yields.find((point) => point.maturity === maturity)?.yield_percent;
const two = yieldOf("2y");
const ten = yieldOf("10y");
if (two && ten) {
const spread = Number(ten) - Number(two);
console.log(spread.toFixed(2), spread < 0 ? "inverted" : "not inverted");
}Go to the exact reference
Common questions
Which country codes can I use?
Use USA, GBR, DEU, JPN or CAN. Each country keeps its own source curve type, so available maturities and measures differ.
Are decimal values strings or numbers?
Decimal values arrive as exact strings, such as "4.25". Decimal inputs must also be strings; numbers are not accepted as inputs.
Can I compare matching maturities across countries?
Check each country's source curve type and measure first. The same maturity label does not make curves interchangeable.
Sources and references
Published . Last reviewed .