Documentation

API Documentation

Everything you need to integrate Costa Rica's exchange rate into your applications.

Introduction

The ExchangeCR API exposes the official USD/CRC exchange rate (BCCR) through a versioned REST API. Every route lives under /api/v1 and returns JSON in a consistent format.

Base URLhttps://exchangecr.com/api/v1

Authentication

Every endpoint —except /health, /openapi.json and /postman.json— requires your API key in the x-api-key header.

curl -H "x-api-key: YOUR_API_KEY" \
  https://exchangecr.com/api/v1/exchange-rate/latest

Request API key

Response format

Every response uses a consistent envelope: success with the data, or an error with a message and a readable code.

// Success
{ "success": true, "data": { } }

// Error
{ "success": false, "message": "...", "error": "CODE" }

Error catalog

Status	error	When
400	BAD_REQUEST	Invalid or missing parameters (date, days, range).
401	UNAUTHORIZED	Missing or invalid API key.
404	NOT_FOUND	No data exists for the request.
429	RATE_LIMITED	Too many requests (see Retry-After).
500	INTERNAL_ERROR	Internal server error.
503	—	Health check: database unreachable.

Rate limits

60 requests per minute per client (per API key, or per IP without a key), with X-RateLimit-Limit and X-RateLimit-Remaining. Each API key also has a monthly quota of 5,000 requests: responses include X-Quota-Limit and X-Quota-Remaining, and exceeding it returns 429 with the QUOTA_EXCEEDED code. Need more? Contact us for a custom plan.

Endpoints

Exchange rate

GET/exchange-rate/latestRequires API key

Latest rate

Get the most recent buy and sell rate for the USD/CRC pair.

GET/exchange-rate?date=YYYY-MM-DDRequires API key

By specific date

Look up the exchange rate for a single day.

• date — required (YYYY-MM-DD)

GET/exchange-rate/history?days=30Requires API key

History

The latest N days of rates (up to 365), perfect for charts.

• days — 1–365, default 30

GET/exchange-rate/range?from=&to=Requires API key

Date range

Every rate between two dates for period analysis.

• from, to — required (max 366 days)

Converter

GET/convert?amount=1000&from=USD&to=CRCRequires API key

Amount converter

Convert amounts between USD and CRC with the official rate.

• amount — required (> 0)
• from, to — USD | CRC
• rate — buy | sell (default sell)
• date — optional

Analytics

GET/exchange-rate/analytics?days=30Requires API key

Analytics

Average, min, max, change, volatility and trend, already computed.

• days — default 30, or from & to

GET/exchange-rate/stats?period=monthly&from=&to=Requires API key

Period statistics

Monthly or yearly aggregates for a date range.

• period — monthly | yearly
• from, to — required

GET/exchange-rate/chart?days=90&points=60Requires API key

Chart data

Optimized series downsampled to N points, with a trend line.

• days — default 30
• points — 2–500, default 90

Banking (ventanilla)

GET/banking/ratesRequires API key

Rates by institution

Per-bank and exchange-house USD buy/sell rates (ventanilla).

• date — optional
• type — optional (entity type)

GET/banking/best?operation=sellRequires API key

Best rate

Which institution buys or sells USD at the best price, with ranking.

• operation — buy | sell (required)

Artificial intelligence

GET/insights?days=30&locale=esRequires API key

AI Market Insights

AI summary of the likely causes of market movements plus a verdict.

• days — default 30
• locale — es | en

System

GET/healthPublic

Service status

Check the API availability and the latest available date.

GET/openapi.jsonPublic

OpenAPI 3.1 spec

Machine-readable spec of every endpoint.

GET/postman.jsonPublic

Postman collection

Import into Postman to try everything.

How to consume

SDK oficial (JavaScript / TypeScript)

import { ExchangeCR } from "@exchangecr/sdk";

const client = new ExchangeCR({ apiKey: process.env.EXCHANGE_API_KEY });
const latest = await client.getLatest();
const { result } = await client.convert({ amount: 1000, from: "USD", to: "CRC" });

Next.js / JavaScript (fetch)

const res = await fetch(
  "https://exchangecr.com/api/v1/exchange-rate/latest",
  { headers: { "x-api-key": process.env.EXCHANGE_API_KEY } }
);
const { data } = await res.json();
console.log(data.sell);

Swift (URLSession)

var req = URLRequest(url: URL(string: "https://exchangecr.com/api/v1/exchange-rate/latest")!)
req.setValue("YOUR_API_KEY", forHTTPHeaderField: "x-api-key")
let (data, _) = try await URLSession.shared.data(for: req)

cURL

curl -H "x-api-key: YOUR_API_KEY" \
  "https://exchangecr.com/api/v1/exchange-rate/history?days=30"

Google Sheets

Use custom functions to pull the exchange rate straight into a sheet. Paste the script into Extensions → Apps Script, store your key once with setExchangeApiKey('...'), and start using =EXCHANGE…

Function	Returns
=EXCHANGERATE([date],[type])	The rate (CRC per 1 USD), latest or by date
=EXCHANGECONVERT(amount,from,to)	Amount converted between USD and CRC
=EXCHANGEHISTORY([days])	Table Date · Buy · Sell
=EXCHANGEBEST(operation)	Best institution · buy · sell
=EXCHANGEANALYTICS([days])	Average, min, max, change, volatility

Download ExchangeCR.gs

Embeddable widgets

Show the exchange rate on your site with an iframe. No API key, auto-updates.

<iframe src="https://exchangecr.com/es/widget?theme=auto"
        width="360" height="150" style="border:0"></iframe>

Tools

Swagger

Interactive reference to try each endpoint.

Postman

Ready-to-import collection.

Status

Live service availability.