Central Bank of Tunisia Exchange Rate API — bct-exchange-rate

Official Central Bank of Tunisia (Tunisia) daily exchange rates for Node.js and TypeScript. The published central bank rates behind tax filings, customs valuations, audits, and compliant invoicing — not market estimates, but the numbers Central Bank of Tunisia itself prints, every business day.

🚀 Why this client?

• 🏛️ Official published rates — Central Bank of Tunisia's own table, with the publisher's own rate_date on every response
• 📅 History back to 2004 — point-in-time tables and daily series for any past date
• 🔀 Published vs derived, always flagged — computed inverse/cross pairs carry derived: true, never mixed with official prints
• ⚡ Zero dependencies — pure ESM + CJS over global fetch; Node 18+, Bun, Deno, and edge runtimes
• 🔷 Type-safe — full TypeScript definitions shipped with the package
• 🧾 Compliance-grade metadata — rate_type, publication date, and source disclaimer on every response

Official rate, not mid-market: every value here is a number Central Bank of Tunisia itself published, fixed once printed and carrying the central bank's own rate_date — what filings and audits require. Need the live interbank midpoint for pricing or display instead? Use the mid-market API or @allratestoday/sdk. The two can diverge by several percent.

🔑 Get your API key

Get a free API key at allratestoday.com/register — no credit card required. Latest rates are on every plan, including free.

📦 Installation

npm install bct-exchange-rate

yarn add bct-exchange-rate

pnpm add bct-exchange-rate

Also published under the org scope as @allratestoday/bct-exchange-rate — same code, same versions.

🏁 Quick start

import { getRate } from 'bct-exchange-rate';

const pair = await getRate('USD', 'TND', { apiKey: 'art_live_...' });
console.log(pair.rate, pair.rate_date); // the official Central Bank of Tunisia rate, on the central bank's own date

📚 API reference

• Latest pair rate — one pair from the latest published table
• Full published table — everything the central bank printed, in one call
• Table for a date — the official table for an invoice or filing date
• Daily time series — one pair across a date range

---

Latest pair rate

Free plan and up. Pairs the central bank does not print directly are resolved from its table and flagged (see Published vs derived rates below).

const pair = await getRate('USD', 'TND', { apiKey: 'art_live_...' });

Response:

{
  bank: 'bct',
  name: 'Central Bank of Tunisia',
  rate_date: '2026-08-20',   // Central Bank of Tunisia's own publication date
  source: 'USD',
  target: 'TND',
  rate: 2.9036,
  rate_type: 'reference',
  derived: false,
  method: 'published',
  disclaimer: '…'
}

Full published table

Free plan and up. The complete table for the latest publication date.

import { getLatestRates } from 'bct-exchange-rate';

const table = await getLatestRates({ apiKey: 'art_live_...' });
console.log(table.rate_date, table.rates.length);

Response:

{
  bank: 'bct',
  name: 'Central Bank of Tunisia',
  rate_date: '2026-08-20',
  rates: [
    { "base": "USD", "quote": "TND", "type": "reference", "value": 2.9036 },
    // … the rest of the published table (20 currencies vs TND)
  ],
  disclaimer: '…'
}

Table for a date

Paid plans. The official table for any date since 2004 — weekends and holidays return the most recent published date, flagged via published_on_requested_date, which is exactly the in-force rate a filing needs.

import { getRatesForDate } from 'bct-exchange-rate';

const day = await getRatesForDate('2026-06-30', { apiKey: 'art_live_...' });
// Optionally narrow to one pair:
const one = await getRatesForDate('2026-06-30', { apiKey: 'art_live_...', source: 'USD', target: 'TND' });

Response:

{
  bank: 'bct',
  requested_date: '2026-06-30',
  rate_date: '2026-06-30',                // the date actually published
  published_on_requested_date: true,      // false when a weekend/holiday fell back
  rates: [ /* the full table for that date */ ],
  disclaimer: '…'
}

Daily time series

Paid plans. One resolved rate per publication date — ready for charting, revaluation runs, or audit workpapers.

import { getHistory } from 'bct-exchange-rate';

const series = await getHistory(
  { source: 'USD', target: 'TND', from: '2026-01-01', to: '2026-08-20' },
  { apiKey: 'art_live_...' }
);

Response:

{
  bank: 'bct',
  source: 'USD',
  target: 'TND',
  from: '2026-01-01',
  to: '2026-08-20',
  count: 152,
  rates: [
    // one entry per publication date
    { date: '2026-08-20', rate: 2.9036, rate_type: 'reference', derived: false, method: 'published' },
    // …
  ],
  disclaimer: '…'
}

Pass { symbol: 'USD' } instead of source/target to get the raw published rows for one currency (all rate types, no pair resolution).

---

🗺️ Currencies covered

Central Bank of Tunisia currently publishes rates covering 20 currencies against the TND (as of the latest table):

🇦🇪 AED · 🇧🇭 BHD · 🇨🇦 CAD · 🇨🇭 CHF · 🇨🇳 CNY · 🇩🇰 DKK · 🇩🇿 DZD · 🇪🇺 EUR · 🇬🇧 GBP · 🇯🇵 JPY · 🇰🇼 KWD · 🇱🇾 LYD · 🇲🇦 MAD · 🇲🇷 MRU · 🇳🇴 NOK · 🇴🇲 OMR · 🇶🇦 QAR · 🇸🇦 SAR · 🇸🇪 SEK · 🇺🇸 USD

⚖️ Published vs derived rates

If Central Bank of Tunisia does not print a pair directly, the API resolves it from the central bank's own table and says so — official and computed values are never confused:

method	derived	Meaning
published	false	The central bank printed this pair directly
inverse	true	Computed as 1 ÷ the published opposite direction
cross	true	Computed via TND from two published rates

🛡️ Error handling

Errors are thrown as Error with status (HTTP code) and body (the API's JSON error) attached:

try {
  const pair = await getRate('USD', 'XXX', { apiKey: 'art_live_...' });
} catch (err) {
  console.log(err.message); // human-readable reason
  console.log(err.status);  // e.g. 404
}

Status	Meaning
—	Missing apiKey (thrown before any request)
400	Malformed date or parameters
401	Invalid API key
403	Endpoint needs a paid plan (historical dates & series)
404	Pair or date range not covered by Central Bank of Tunisia
429	Monthly quota exceeded

🔷 TypeScript

Full definitions ship with the package — no @types install:

import type { LatestRates, PairRate, DatedRates, RateEntry, HistoryQuery, RequestOptions } from 'bct-exchange-rate';

📦 CommonJS

const { getRate } = require('bct-exchange-rate');

getRate('USD', 'TND', { apiKey: 'art_live_...' }).then((pair) => console.log(pair.rate));

💡 Quota tips

• Rates change once per business day — cache the published table locally and a small monthly quota goes a long way.
• Every request counts toward your AllRatesToday quota, shared across all AllRatesToday endpoints on your key.

📖 Methods reference

Method	Plan	Description
getRate(source, target, { apiKey })	Free	Latest rate for one pair, resolved from the published table
getLatestRates({ apiKey })	Free	The central bank's full latest published table
getRatesForDate(date, { apiKey, source?, target? })	Paid	The official table (or one pair) for a YYYY-MM-DD date
getHistory({ symbol | source+target, from?, to? }, { apiKey })	Paid	Daily series since 2004

🔗 Links

• Central Bank of Tunisia rates page — live table, publication cadence, FAQ
• All central bank sources
• API documentation · Interactive reference
• Register (free) · Pricing
• GitHub

📜 License

MIT