Integrating the Rates Engine

The Rates Engine is a single, authenticated source of market data for Kaleidico client sites, sourced from the Federal Reserve (FRED). Instead of each site sourcing or hand-typing figures, every site reads from one endpoint and stays in sync.

It serves two kinds of series, distinguished by a category field:

• rates — mortgage products (Freddie Mac PMMS), for rate widgets and calculators. Weekly.
• research — economic indicators (Treasury yields, the Fed Funds rate, home prices, unemployment) for market-context content. Daily to quarterly.

Both are reached through the same endpoints below; you choose what to request by series id. Base URL: https://rates.kaleidicoagents.com

1. 1Get an API key for the site from the admin dashboard.
2. 2Add the key to the site's environment and install the client package (or call the HTTP API directly).
3. 3Render the rate in a Server Component. Done — it caches and refreshes on its own.

Every request must include a bearer token — the API key issued per client site. Keep it server-side; it should never reach the browser.

Authorization: Bearer krp_your_key_here

Requests without a valid key return 401 Unauthorized. Keys are issued and revoked from the admin dashboard.

@kaleidico/rates-client is a tiny, headless, server-side wrapper. It reads the key from the environment and sets Next.js caching automatically — no UI, so each site styles the data to its own brand.

It's published privately to GitHub Packages under the Kaleidico org. A consuming repo needs an .npmrc that points the @kaleidico scope at GitHub Packages and supplies a token with read:packages — npm expands ${GITHUB_TOKEN} from the environment at install time.

@kaleidico:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

Generate the token at GitHub → Settings → Developer settings → Personal access tokens with the read:packages scope, then expose it to the build. Locally, export it in your shell; in CI or Vercel, add GITHUB_TOKEN as an environment variable.

export GITHUB_TOKEN=ghp_your_read_packages_token
npm install @kaleidico/rates-client

Then add the Rates Engine API key (issued from the admin dashboard) to the site's server-side environment:

KALEIDICO_RATES_API_KEY=krp_your_key_here

Three functions are exported:

import {
  getCurrentRates,
  getRateHistory,
  listSeries,
} from '@kaleidico/rates-client'

// Latest rate per series (cached 1h)
const { data } = await getCurrentRates(['MORTGAGE30US', 'MORTGAGE15US'])

// Weekly time series for a chart (cached 24h)
const history = await getRateHistory('MORTGAGE30US', 52)

// The catalog of available series
const series = await listSeries()

Each example below is rendered with the live data the API is serving right now, paired with the code that produces it. Styling is yours — these use Kaleidico's, but the data is identical to what any site receives.

1. Inline rate strip

A compact row of current rates, e.g. in a site header or hero.

import { getCurrentRates } from '@kaleidico/rates-client'

export async function RateStrip() {
  const { data } = await getCurrentRates([
    'MORTGAGE30US', 'MORTGAGE15US',
  ])
  return (
    <div className="rate-strip">
      {data.map((r) => (
        <span key={r.series}>
          {r.label} <strong>{r.rate.toFixed(2)}%</strong>
        </span>
      ))}
    </div>
  )
}

2. Featured rate card

The headline rate as a hero figure, with source attribution.

import { getCurrentRates } from '@kaleidico/rates-client'

export async function RateCard() {
  const { data, meta } = await getCurrentRates(['MORTGAGE30US'])
  const r = data[0]
  return (
    <div className="rate-card">
      <p className="label">{r.label}</p>
      <p className="figure">{r.rate.toFixed(2)}%</p>
      <p className="source">
        Freddie Mac, as of {r.observed_on}
      </p>
    </div>
  )
}

3. Rate with week-over-week trend

Pair the latest rate with the prior week to show direction — useful on a rates page or market-update block.

import { getRateHistory } from '@kaleidico/rates-client'

const { data } = await getRateHistory('MORTGAGE30US', 2)
const [prior, latest] = data            // oldest first
const delta = latest.rate - prior.rate  // e.g. +0.02

4. Feeding a calculator

Use the latest rate as the default in a mortgage calculator. Below, a $400,000 loan over 30 years at today's 30-year fixed rate:

const { data } = await getCurrentRates(['MORTGAGE30US'])
const apr = data[0].rate / 100      // e.g. 0.0653
const r = apr / 12                  // monthly rate
const n = 30 * 12                   // payments
const P = 400000                    // principal

const monthly = P * r * (1 + r) ** n / ((1 + r) ** n - 1)

5. Market indicators (research)

Research series come through the same endpoints — just request them by id. They arrive in different units, so format by the unit field (percent, index, or usd).

import { getCurrentRates } from '@kaleidico/rates-client'

export async function MarketIndicators() {
  const { data } = await getCurrentRates([
    'DGS10', 'FEDFUNDS', 'MSPUS', 'CSUSHPINSA',
  ])
  const format = (rate: number, unit: string) =>
    unit === 'usd'   ? `$${Math.round(rate).toLocaleString()}`
  : unit === 'index' ? rate.toLocaleString(undefined, { maximumFractionDigits: 1 })
  :                    `${rate.toFixed(2)}%`

  return (
    <ul>
      {data.map((d) => (
        <li key={d.series}>{d.label}: {format(d.rate, d.unit)}</li>
      ))}
    </ul>
  )
}

Any stack can call the API directly. All endpoints are GET, require the bearer key, and return a { data, meta } envelope.

GET /v1/rates/current

Latest observation per series. ?series= takes a comma-separated list.

curl -H "Authorization: Bearer krp_your_key" \
  "https://rates.kaleidicoagents.com/v1/rates/current?series=MORTGAGE30US,MORTGAGE15US"

{
  "data": [
    { "series": "MORTGAGE30US", "label": "30-Year Fixed",
      "rate": 6.66, "unit": "percent", "observed_on": "2026-07-30" }
  ],
  "meta": { "source": "FRED", "fetched_at": "2026-06-03T20:00:00.000Z" }
}

GET /v1/rates/history

Weekly series for charts. ?series= (single) and ?weeks= (default 52).

{
  "data": [
    { "observed_on": "2026-05-21", "rate": 6.51 },
    { "observed_on": "2026-05-28", "rate": 6.66 }
  ],
  "meta": { "source": "FRED", "series": "MORTGAGE30US", "weeks": 52 }
}

GET /v1/series

The catalog of tracked series. Add ?category=rates or ?category=research to filter.

Research series & units

Research indicators come through the same endpoints — request them by id. For these, the /v1/data/* aliases read more honestly than /v1/rates/*(they're identical — use whichever fits). Values arrive in different units, given by the unit field (percent, index, usd), so format accordingly.

curl -H "Authorization: Bearer krp_your_key" \
  "https://rates.kaleidicoagents.com/v1/data/current?series=DGS10,MSPUS"

{
  "data": [
    { "series": "DGS10", "label": "10-Year Treasury",
      "rate": 4.61, "unit": "percent", "observed_on": "2026-07-28" },
    { "series": "MSPUS", "label": "Median Home Sale Price",
      "rate": 410700, "unit": "usd", "observed_on": "2026-04-01" }
  ],
  "meta": { "source": "FRED", "fetched_at": "2026-06-04T13:00:00.000Z" }
}

Series fall into two categories. Rates are mortgage products for widgets and calculators; research are economic indicators for market-context content. Filter the catalog with /v1/series?category=research.

New series can be added without code changes — a row in the catalog, not a deploy. We only publish series with a live feed, so the figures are always current rather than historical.

• Caching. The client package sets revalidate automatically — 1 hour for current values, 24 hours for history. Series update daily to weekly, so this stays comfortably fresh.
• If the API is down. Next.js keeps serving the last good cached response, so widgets never flash blank. Design the component to render nothing past the cache TTL rather than show a broken state.
• Rate limits. 60 requests per minute per key. Server-side caching means a busy site makes only a handful of real calls per hour.