Integrating the Rates Engine

The Rates Engine is a single, authenticated source of mortgage rate data for Kaleidico client sites. Rates come from Freddie Mac's Primary Mortgage Market Survey via the Federal Reserve (FRED) and refresh every Thursday. Instead of each site sourcing or hand-typing rates, every site reads from one endpoint and stays in sync.

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', 'MORTGAGE5US',
  ])
  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)

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.53, "unit": "percent", "observed_on": "2026-05-28" }
  ],
  "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.53 }
  ],
  "meta": { "source": "FRED", "series": "MORTGAGE30US", "weeks": 52 }
}

GET /v1/series

The catalog of tracked series.

Note: MORTGAGE5US (5/1 ARM) was discontinued by Freddie Mac in late 2022, so its latest value is historical. New series can be added without code changes.

• Caching. The client package sets revalidate automatically — 1 hour for current rates, 24 hours for history. Rates only change weekly, so this is generous.
• 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.