BCV Today logo BCV Today
Español

API reference

A free read-only JSON BCV API for the official exchange rates published by Banco Central de Venezuela. Data is served as static files from GitHub Pages, with no authentication, no API keys, and no project-level rate limits beyond GitHub Pages itself.

Base URL: https://bcv.today

API v1 root: https://bcv.today/api/v1

Agent discovery

Resource URL Use
OpenAPI /openapi.json Machine-readable endpoint description.
API catalog /.well-known/api-catalog RFC-style catalog with docs, status and OpenAPI.
Agent card /.well-known/agent-card.json Data-access capabilities for agents.
LLM index /llms.txt Short summary for agents and LLMs.
LLM full context /llms-full.txt Full Markdown/text context.

Endpoints

Latest rate

GET /api/v1/rate.json

Returns today’s current rate entry. The file is rebuilt every time the scraper runs and commits only when the generated files in api/v1/ change.

Example:

curl -s https://bcv.today/api/v1/rate.json

{
  "USD": 500.4606,
  "EUR": 589.27233807,
  "CNY": 73.59606476,
  "TRY": 11.03277068,
  "RUB": 6.71398712,
  "updated_at": "2026-05-11T13:28:27.091112+00:00",
  "effective_date": "2026-05-11",
  "date": "2026-05-11"
}

History index

GET /api/v1/history.json

Returns up to the latest 1830 daily entries, ordered from oldest to newest. This file powers the history chart and table on the website.

Example:

curl -s https://bcv.today/api/v1/history.json

API status

GET /api/v1/status.json

Returns the status of the published dataset, the effective date, generation time, and available currencies.

Example:

curl -s https://bcv.today/api/v1/status.json

{
  "status": "ok",
  "updated_at": "2026-05-11T15:39:01.127606+00:00",
  "generated_at": "2026-05-11T15:39:01.127606+00:00",
  "date": "2026-05-11",
  "effective_date": "2026-05-11",
  "timezone": "America/Caracas",
  "api_version": "v1",
  "supported_currencies": ["USD", "EUR", "CNY", "TRY", "RUB"]
}

History by date

GET /api/v1/history/{YYYY-MM-DD}.json

Returns the snapshot stored for a specific America/Caracas calendar date. Historical snapshots use the same base format as rate.json, but older entries may omit currencies that were unavailable in the original source data.

Parameter Type Description
YYYY-MM-DD path ISO 8601 date, for example 2026-05-11.

Example:

curl -s https://bcv.today/api/v1/history/2026-05-11.json

Returns 404 if the requested date does not exist in the repository.

Response schema

Field Type Description
USD number Bolívares per 1 US dollar.
EUR number Bolívares per 1 euro. Always present in rate.json; may be omitted from older history entries if unavailable in the source.
CNY number Bolívares per 1 Chinese yuan. Always present in rate.json; may be omitted from older history entries if unavailable in the source.
TRY number Bolívares per 1 Turkish lira. Always present in rate.json; may be omitted from older history entries if unavailable in the source.
RUB number Bolívares per 1 Russian ruble. Always present in rate.json; may be omitted from older history entries if unavailable in the source.
updated_at string (ISO 8601) UTC timestamp when the scraper captured the rate.
date string (YYYY-MM-DD) Calendar date represented by the file. For per-day history files, this matches the filename.
effective_date string (YYYY-MM-DD) Official BCV validity date (Fecha Valor). On weekends and holidays this can point to the previous business day whose rate is still officially in effect.
source string Optional field present on some imported historical entries.

BCV usually publishes rates on business days around 16:30 Caracas time, effective for the next business day. Friday’s publication normally applies to Monday; if Monday is a holiday, it applies to the next business day.

Saturdays, Sundays, and holidays do not usually have a new BCV publication. The scraper fills missing calendar days with the latest rate whose effective_date is less than or equal to that day.

Usage examples

Badges

You can show API availability or the latest USD rate in a README, internal dashboard, or public docs.

Markdown:

![BCV Today](https://img.shields.io/badge/BCV%20Today-API%20online-187a3b)
![USD BCV](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fbcv.today%2Fapi%2Fv1%2Frate.json&query=$.USD&label=USD%20BCV&suffix=%20Bs)

HTML:

<img
  alt="BCV Today API online"
  src="https://img.shields.io/badge/BCV%20Today-API%20online-187a3b"
/>
<img
  alt="USD BCV"
  src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fbcv.today%2Fapi%2Fv1%2Frate.json&query=$.USD&label=USD%20BCV&suffix=%20Bs"
/>

JavaScript

const res = await fetch("https://bcv.today/api/v1/rate.json", {
  cache: "no-cache",
});
const { USD, EUR, date } = await res.json();
console.log(`Rate for ${date}: USD ${USD} - EUR ${EUR}`);

Node.js

const res = await fetch("https://bcv.today/api/v1/rate.json");
if (!res.ok) throw new Error(`BCV API ${res.status}`);

const rate = await res.json();
const ves = 100 * rate.USD;

console.log(`100 USD = ${ves.toFixed(2)} Bs. (${rate.date})`);

Python

import requests

data = requests.get(
    "https://bcv.today/api/v1/rate.json",
    timeout=10,
).json()

print(f"USD: {data['USD']}  EUR: {data['EUR']}  ({data['date']})")

PHP

<?php
$json = file_get_contents("https://bcv.today/api/v1/rate.json");
$rate = json_decode($json, true, flags: JSON_THROW_ON_ERROR);

$ves = 100 * $rate["USD"];
echo "100 USD = " . number_format($ves, 2) . " Bs. ({$rate['date']})";

cURL + jq

curl -s https://bcv.today/api/v1/rate.json | jq '.USD'

Quick conversion

function convert(amount, from, to, rate) {
  const toBs = from === "VES" ? amount : amount * rate[from];
  return to === "VES" ? toBs : toBs / rate[to];
}

const rate = await fetch("https://bcv.today/api/v1/rate.json").then((r) => r.json());

console.log(convert(100, "USD", "VES", rate));
console.log(convert(1000, "VES", "USD", rate));

Availability and caching

Changes and support

Source code and change history are available at github.com/grupoclip/bcv-api.

Open an issue for bugs or requests.