Superintendencia Financiera de Colombia Exchange Rates API — colombia-trm-exchange-rate

Official Superintendencia Financiera de Colombia (Colombia) 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 Superintendencia Financiera de Colombia itself prints, every business day.

🚀 Why this client?

• 🏛️ Official published rates — Superintendencia Financiera de Colombia's own table, with the publisher's own rate_date on every response
• 📅 History back to 1991 — 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 Superintendencia Financiera de Colombia itself published, fixed once printed and carrying the central bank's own rate_date — what filings and audits require. Need the live mid-market rate 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.

📈 Latest published table

The image is rendered live from the keyless endpoint, so it follows the central bank's publications on npm and on GitHub alike without a new release. The same table as text is folded below for search and copy-paste: on GitHub a daily Action refreshes it whenever the central bank publishes a new table; on npm it is as of the package's publish date.

Base	Quote	Type	Rate
USD	COP	reference	3182.99

Source: Official rates published by SFC, served by AllRatesToday. Rates are as printed by the central bank; AllRatesToday is not affiliated with it.

📦 Installation

npm install colombia-trm-exchange-rate

yarn add colombia-trm-exchange-rate

pnpm add colombia-trm-exchange-rate

Requires Node 18+ (global fetch); also runs on Bun, Deno and edge runtimes. Also published under the org scope as @allratestoday/colombia-trm-exchange-rate — same code, same versions.

🏁 Quick start

import { getRate } from 'colombia-trm-exchange-rate';

const pair = await getRate('USD', 'COP', { apiKey: 'art_live_...' });
console.log(pair.rate, pair.rate_date); // the official Superintendencia Financiera de Colombia 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', 'COP', { apiKey: 'art_live_...' });

Response:

{
  bank: 'sfc',
  name: 'Superintendencia Financiera de Colombia',
  rate_date: '2026-10-10',   // Superintendencia Financiera de Colombia's own publication date
  source: 'USD',
  target: 'COP',
  rate: 3194.44,
  rate_type: 'reference',
  derived: false,
  method: 'published',
  disclaimer: 'Official rates as published by the named central bank. On weekends/holidays the most recent published rate_date is returned.'
}

Full published table

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

import { getLatestRates } from 'colombia-trm-exchange-rate';

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

Response:

{
  bank: 'sfc',
  name: 'Superintendencia Financiera de Colombia',
  rate_date: '2026-10-10',
  rates: [
    { "base": "USD", "quote": "COP", "type": "reference", "value": 3194.44 },
    // … the rest of the published table (1 currency vs COP)
  ],
  disclaimer: '…'
}

Table for a date

Paid plans. The official table for any date since 1991 — 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 'colombia-trm-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: 'COP' });

Response:

{
  bank: 'sfc',
  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 'colombia-trm-exchange-rate';

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

Response:

{
  bank: 'sfc',
  source: 'USD',
  target: 'COP',
  from: '2026-01-01',
  to: '2026-10-10',
  count: 152,
  rates: [
    // one entry per publication date
    { date: '2026-10-10', rate: 3194.44, 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

Superintendencia Financiera de Colombia currently publishes rates covering 1 currency against the COP (as of the latest table):

🇺🇸 USD

🏛️ Source

The Superintendencia Financiera de Colombia certifies the TRM (Tasa Representativa del Mercado), the official USD/COP exchange rate calculated from interbank trading. The TRM is the legally binding rate for Colombian tax, customs and accounting purposes, certified each business day for the following day.

• Publisher's own page: TRM — Tasa Representativa del Mercado · www.superfinanciera.gov.co
• Publication: every business day; the exact schedule, freshness status and any current delay are on the Superintendencia Financiera de Colombia rates page
• In the API: usually by 00:15 UTC (measured over the last 11 publications). Schedule a sync at or after that time and retry hourly until rate_date moves; every response carries the same figure as available_by_utc — see when to poll
• Values are stored unmodified, with the publisher's own rate_date on every row — see the methodology

🧭 Reading the numbers

• value is always quote currency per 1 unit of base currency (base: "EUR", quote: "USD", value: 1.15 means 1 EUR = 1.15 USD).
• Superintendencia Financiera de Colombia quotes COP per 1 unit of foreign currency (e.g. base: "USD", quote: "COP" means COP per one US dollar).
• Need the other way round? Ask getRate(target, source) and the API inverts or crosses for you, flagged derived: true — never divide a published rate yourself in a compliance workflow.
• rate_type tells you which of the central bank's series a row belongs to (reference here); some publishers print buy/sell or several fixings for the same pair.

🧩 ERP & accounting systems

Loading the official Superintendencia Financiera de Colombia rate into an accounting system is a supported workflow, not a hack. Step-by-step guides with the direction each system expects:

• Dynamics 365 Business Central — built-in Currency Exchange Rate Service, no code
• Xero · QuickBooks Online · SAP S/4HANA and ECC · Odoo

The same keyed endpoints return ?format=csv, ?format=xml and ?format=xlsx, and accept the key as ?api_key= on the URL for importers that cannot send headers:

curl "https://allratestoday.com/api/v1/central-bank/sfc/latest?format=xml&api_key=art_live_..."

🤖 AI agents

• MCP server: npx -y @allratestoday/central-bank-mcp (stdio) or the hosted endpoint https://allratestoday.com/api/mcp — tools for official rates, history, cross-bank comparison and publication calendars
• Already using the general SDK or MCP server? Since 2026-10-01 @allratestoday/sdk 1.4+ has officialRates('sfc') and @allratestoday/mcp-server 0.6+ has a get_official_rates tool — both return this source's latest table with no key, so you can add it without a second dependency
• Claude Code plugin (no key): /plugin marketplace add AllRates-Today/claude-code-plugin then /plugin install allratestoday@allratestoday — bundles both MCP servers plus an /official-rate sfc ... command
• Evaluating? Agents can self-issue a trial key with no signup: POST https://allratestoday.com/api/agent/keys (send Content-Type: application/json) returns a 100-call key valid 7 days that covers the free-plan methods (latest table, pairs); dated tables and history need a paid plan. The MCP servers expose it as request_trial_key
• Machine-readable site guide: llms.txt · for-ai-agents

⚖️ Published vs derived rates

If Superintendencia Financiera de Colombia 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 COP 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 Superintendencia Financiera de Colombia
429	Monthly quota exceeded

🔷 TypeScript

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

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

📦 CommonJS

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

getRate('USD', 'COP', { 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 1991

📥 Bulk data (no key)

Need the whole archive rather than an API call? The same published tables are mirrored daily as open data:

• Hugging Face: AllRatesToday/central-bank-exchange-rates — one CSV per institution (rates/sfc.csv)
• Kaggle: allratestoday/central-bank-exchange-rates
• Raw JSON on GitHub: https://raw.githubusercontent.com/AllRates-Today/central-bank-exchange-rates/main/data/sfc/latest.json

🔗 Links

• Website: allratestoday.com
• Superintendencia Financiera de Colombia rates page — live table, publication cadence, FAQ
• All central bank sources
• Download central bank rates — every bank's latest table and history as Excel, CSV or JSON
• Package docs on the site · ERP integration guides
• API documentation · Interactive reference · Methodology
• Register (Free) · Dashboard · Pricing
• Status
• Postman collection
• ChatGPT app — ask ChatGPT for live and official central bank rates
• GitHub

📜 License

MIT