API pública

REST JSON, sin autenticación para consultas públicas, con tasa limitada por IP. Diseñada para consumidores automáticos (clientes, extensiones, agentes IA).

Para agentes IA: también publicamos /llms.txt, /llms-full.txt, /openapi.yaml, /.well-known/ai-plugin.json y /.well-known/mcp.json.

Convenciones

  • Base URL: https://tipodecambio.cr/api/v1
  • Encoding: UTF-8. Respuestas: application/json.
  • Formato de fechas: YYYY-MM-DD.
  • Envoltura estándar: { "ok": bool, "data": ..., "source": "<origen>", "retrievedAt": "<ISO-8601>" }.
  • En errores: { "ok": false, "error": "<mensaje>" }.
  • Rate limit: 120 req/min por IP. Headers X-RateLimit-Remaining y Retry-After.
  • Cache HTTP: respuestas marcadas con Cache-Control: public, max-age=<n>.

Códigos de error

HTTPCuerpoCuándo
200{ "data": ... }Respuesta normal.
400{ "error": "<msg>" }Parámetros inválidos (fecha mal formada, monedas no soportadas, etc).
404{ "error": "not_found" }Slug de indicador inexistente.
429{ "error": "rate_limited", "retryAfter": <s> }Excedió 120 req/min. Respete Retry-After.
502{ "error": "upstream_unavailable" }El BCCR no respondió y no hay fallback en BD.
503{ "error": "maintenance" }Mantenimiento programado.

Endpoints

GET /api/v1/tipo-cambio/hoy

Tipo de cambio oficial de referencia del dólar (USD→CRC) del día.

curl https://tipodecambio.cr/api/v1/tipo-cambio/hoy
Respuesta de ejemplo 
{
  "ok": true,
  "data": {
    "fecha": "2026-05-12",
    "compra": 524.83,
    "venta": 532.15,
    "moneda": "USD",
    "referencia": "CRC"
  },
  "source": "BCCR SDDE cuadro 1",
  "retrievedAt": "2026-05-12T09:14:31-06:00"
}

GET /api/v1/tipo-cambio/historico

Serie histórica del tipo de cambio. Query params: desde=YYYY-MM-DD, hasta=YYYY-MM-DD.

curl 'https://tipodecambio.cr/api/v1/tipo-cambio/historico?desde=2025-01-01&hasta=2025-12-31'
Respuesta de ejemplo 
{
  "ok": true,
  "data": [
    { "date": "2025-01-02", "compra": 510.22, "venta": 517.05 },
    { "date": "2025-01-03", "compra": 511.07, "venta": 518.30 }
  ],
  "meta": { "desde": "2025-01-02", "hasta": "2025-12-31", "puntos": 257, "moneda": "USD", "referencia": "CRC" },
  "source": "BCCR SDDE cuadro 1"
}

GET /api/v1/convertir

Conversor USD ↔ CRC al tipo de cambio actual. Query params: monto, desde (USD|CRC), hacia (USD|CRC).

curl 'https://tipodecambio.cr/api/v1/convertir?monto=100&desde=USD&hacia=CRC'
Respuesta de ejemplo 
{
  "ok": true,
  "data": {
    "monto": 100, "desde": "USD", "hacia": "CRC",
    "resultado": 53215.00,
    "tasaCompra": 524.83, "tasaVenta": 532.15,
    "fecha": "2026-05-12"
  }
}

GET /api/v1/indicadores

Lista de indicadores económicos disponibles (SOFR, MONEX, IPC, expectativas, balanza de pagos, etc.).

curl https://tipodecambio.cr/api/v1/indicadores

GET /api/v1/indicadores/{slug}

Series temporales de un indicador específico. Query params opcionales: desde, hasta.

curl 'https://tipodecambio.cr/api/v1/indicadores/sofr-overnight?desde=2026-01-01'

GET /api/v1/noticias

Agregado de noticias relacionadas desde Google News. Query params: q, limit (1–30).

curl 'https://tipodecambio.cr/api/v1/noticias?q=dólar+Costa+Rica&limit=10'

GET /api/v1/health

Ping del servicio. Devuelve { "ok": true, "time": ... } en respuestas saludables.

curl https://tipodecambio.cr/api/v1/health

Uso responsable

Se aplica rate-limiting de 120 req/min por IP. Si necesita más, escriba a [email protected]. Para integraciones de alta frecuencia ofrecemos webhooks (en preview).

Fuente

Todos los datos económicos provienen de Banco Central de Costa Rica (BCCR) vía su API pública SDDE.