@varve/boc-valet

TypeScript client for the Bank of Canada Valet API, including series, groups, observations, graph metadata, and FX RSS.

The Bank of Canada Valet API provides financial data and metadata including exchange rates, interest rates, economic statistics, series catalogues, and grouped time series. @varve/boc-valet wraps Valet in an isomorphic, Zod-validated TypeScript client.

npm install @varve/boc-valet zod

import { BocValetClient, BocValetApiError } from '@varve/boc-valet';
 
const client = new BocValetClient();

When to use this package

Use @varve/boc-valet when you need Bank of Canada series or groups, especially:

daily foreign exchange rates
interest rate series
recent observations for dashboards
group-level pulls such as daily FX rates
graph metadata for series-period observations
raw FX RSS/RDF XML

Data model

Series is a named Valet time series, such as FXUSDCAD.

Group is a provider-defined collection of series, such as FX_RATES_DAILY.

Observation is a dated row. Valet keeps values under series IDs and returns numeric values as strings.

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

Quick start

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

Common workflows

Discover series

List series and groups, then inspect metadata for a known Valet identifier.

Fetch observations

Pull series or group observations, build graph metadata, and fetch FX RSS XML.

Configuration

const client = new BocValetClient({
  baseUrl: 'https://www.bankofcanada.ca/valet',
  maxRetries: 2,
  timeoutMs: 30_000,
});

The client retries 429 and 5xx responses and respects Retry-After when present.