@varve/boc-valet

An isomorphic, Zod-validated TypeScript client for the Bank of Canada Valet API.

The Valet API provides Bank of Canada financial data and metadata, including exchange rates, interest rates, economic statistics, series catalogues, and grouped time series.

Installation

npm install @varve/boc-valet zod

zod is a required peer dependency.

Quick start

import { BocValetClient } from '@varve/boc-valet';

const client = new BocValetClient();

const data = await client.getObservations(['FXUSDCAD', 'FXEURCAD'], {
  startDate: '2024-01-01',
  endDate: '2024-01-31',
});

console.log(data.observations);

Discovery

const series = await client.listSeries();
const groups = await client.listGroups();

const usdCad = await client.getSeries('FXUSDCAD');
const dailyFx = await client.getGroup('FX_RATES_DAILY');

Valet exposes catalogue responses as maps keyed by series or group identifier.

Observations

const latest = await client.getObservations('FXUSDCAD', {
  recent: 5,
  orderDir: 'desc',
});

const group = await client.getGroupObservations('FX_RATES_DAILY', {
  recent: 1,
});

Observation rows keep the native Valet shape:

{
  d: '2024-01-02',
  FXUSDCAD: { v: '1.3312' }
}

The client prevents incompatible date filters, matching Valet's documented rule: recent, recent_weeks, recent_months, and recent_years cannot be combined with start_date or end_date.

Graph metadata

For graph imports or charting, use the normalized helper:

const graph = await client.getObservationGraphMetadata(['FXUSDCAD', 'FXEURCAD'], {
  recent: 10,
});

console.log(graph.series);
console.log(graph.periods);
console.log(graph.observations);

The normalized observation values remain strings because Valet returns numeric values as strings and some series may use non-numeric values.

FX RSS

Valet also exposes a foreign exchange RSS/RDF XML feed. This package returns it as raw XML text:

const xml = await client.getFxRss('FXUSDCAD');

Configuration

const client = new BocValetClient({
  baseUrl: 'https://www.bankofcanada.ca/valet',
  maxRetries: 2, // accepted for compatibility; retries are handled by callers
  timeoutMs: 30_000,
});

The client performs one timeout-bound HTTP request per method call. Non-2xx responses expose status, and Retry-After is parsed as retryAfterMs when present.

API reference

• listSeries()
• listGroups()
• getSeries(seriesName)
• getGroup(groupName)
• getObservations(seriesNames, params)
• getGroupObservations(groupName, params)
• getObservationGraphMetadata(seriesNames, params)
• getGroupObservationGraphMetadata(groupName, params)
• getFxRss(seriesNames?)

Official references

• Bank of Canada Valet API documentation
• Valet API how-to guide
• Bank of Canada terms of use