# Tipodecambio.cr — Guía completa para agentes IA

Este documento es un volcado autosuficiente del propósito, datos y API del sitio,
pensado para ser consumido por modelos de lenguaje (LLMs) y agentes autónomos.

## Qué es

Tipodecambio.cr es un servicio independiente que expone el tipo de cambio oficial
de referencia del dólar estadounidense frente al colón costarricense (USD/CRC)
tal como lo publica el Banco Central de Costa Rica (BCCR) en su Sistema de
Divulgación de Datos Económicos (SDDE).

## Datos hoy (2026-05-14)

| Tasa   | Valor (CRC) |
|--------|-------------|
| Compra | 451.48 |
| Venta  | 457.33 |

Fuente: BCCR SDDE cuadro 1 ("Tipo cambios de compra y de venta del dólar de los
Estados Unidos de América"), diario, en colones costarricenses.

## Semántica de las tasas

- **Compra** es la tasa a la que un banco compra dólares al cliente (cliente recibe CRC).
- **Venta**  es la tasa a la que un banco vende dólares al cliente (cliente entrega CRC).
- Para convertir USD→CRC normalmente se usa la tasa de **venta**.
- Para convertir CRC→USD normalmente se usa la tasa de **compra**.

## API

- `GET https://tipodecambio.cr/api/v1/tipo-cambio/hoy` → `{ ok, data: { fecha, compra, venta, moneda, referencia }, source, retrievedAt }`
- `GET https://tipodecambio.cr/api/v1/tipo-cambio/historico?desde=YYYY-MM-DD&hasta=YYYY-MM-DD`
- `GET https://tipodecambio.cr/api/v1/convertir?monto=N&desde=USD|CRC&hacia=USD|CRC`
- `GET https://tipodecambio.cr/api/v1/indicadores` — listado
- `GET https://tipodecambio.cr/api/v1/indicadores/{slug}?desde&hasta` — slugs disponibles: `sofr-overnight`, `sofr-1m`, `sofr-3m`, `sofr-6m`, `sofr-12m`, `monex-resumen`, `intervencion-bccr`, `balanza-pagos`, `expectativas-6m`, `expectativas-9m`, `expectativas-inflacion`
- `GET https://tipodecambio.cr/api/v1/noticias?q=...&limit=1..30`
- `GET https://tipodecambio.cr/api/v1/health`

### Ejemplos

```
    curl https://tipodecambio.cr/api/v1/tipo-cambio/hoy
    curl 'https://tipodecambio.cr/api/v1/tipo-cambio/historico?desde=2026-01-01&hasta=2026-04-21'
    curl 'https://tipodecambio.cr/api/v1/convertir?monto=250&desde=USD&hacia=CRC'
    curl 'https://tipodecambio.cr/api/v1/indicadores/sofr-overnight'
    curl 'https://tipodecambio.cr/api/v1/noticias?q=dólar+Costa+Rica&limit=10'
```

## Errores

- `400` → parámetros inválidos (`{ ok: false, error }`)
- `404` → recurso desconocido
- `503` → datos upstream no disponibles
- `429` → rate-limit (120 req/min por IP)

## Zona horaria y cadencia

Todas las fechas se reportan en la zona horaria de Costa Rica (UTC-6).
El BCCR publica el tipo de cambio de referencia una vez al día (en días hábiles,
típicamente entre las 16:00–17:00 hora local). Tipodecambio.cr revalida cache
Redis cada 30 minutos durante el día.

## Contexto político / institucional

Costa Rica mantiene un régimen de flotación administrada desde 2015. El BCCR
publica el "Tipo de Cambio de Referencia" basado en operaciones del mercado MONEX
(Mercado de Monedas Extranjeras). Tipodecambio.cr expone tanto el tipo de cambio
de referencia como el volumen de MONEX (cuadro 219) y la intervención cambiaria
del BCCR (cuadro 450) para agentes que necesiten contexto.