bcv: Python client for the BCV Today API
Unofficial: not affiliated with Banco Central de Venezuela. This package is the official client of BCV Today, an independent project that republishes the exchange rates posted by Banco Central de Venezuela (BCV). Despite the short package name
bcv, it is not made, endorsed or operated by the bank. For legal or accounting use, check the figures against bcv.org.ve.
Official BCV exchange rates (bolivars per unit of USD, EUR, CNY, TRY and RUB) from the free, read-only BCV Today API, with conversions, history and a command-line tool.
- Zero runtime dependencies (standard library
urllib), Python 3.9+, fully typed (py.typed). Decimaleverywhere money is involved.- In-memory TTL cache, clear exceptions, CLI with
--jsonoutput. - Optional extras:
bcv[pandas]for DataFrames,bcv[async]for an async client (httpx).
Install
pip install bcv
pip install "bcv[pandas]" # History.to_pandas()
pip install "bcv[async]" # AsyncBCV
Quickstart
from bcv import BCV
client = BCV()
rates = client.latest()
print(rates["USD"], rates.effective_date) # Decimal('916.6477') 2026-11-18
day = client.on("2026-01-04", currency="USD") # a Sunday
print(day.rate, day.effective_date, day.carried_forward)
# 304.6796 2026-01-03 True
conv = client.convert(100, "USD", "VES")
print(conv.result, conv.rate, conv.effective_date)
print(client.convert(50_000, "VES", "EUR", date="2026-01-06"))
hist = client.history("USD", days=30) # or start="2026-01-01", end="2026-03-31"
print(hist.first.rate, hist.last.rate, hist.change_pct, hist.min.date, hist.max.date)
df = hist.to_pandas() # needs bcv[pandas]
print(client.status().stale)
Async
import asyncio
from bcv import AsyncBCV
async def main() -> None:
async with AsyncBCV() as client:
print(await client.convert(100, "USD", "VES"))
asyncio.run(main())
API
| Method | Returns | Endpoint |
|---|---|---|
BCV(base_url="https://bcv.today", timeout=10, cache_ttl=300, user_agent=None) |
client | |
.latest() |
Rates (rates, date, effective_date, updated_at, source) |
/api/v1/rate.json |
.on(date, currency=None) |
DayRate (date, effective_date, carried_forward, note, rates, .rate) |
/api/v1/history/{date}.json |
.history(currency, days=30, *, start=None, end=None) |
History (points, first, last, min, max, change, change_pct, note, .to_list(), .to_pandas()) |
/api/v1/history.json |
.convert(amount, from_, to, date=None, *, decimals=2) |
Conversion (result, result_exact, rate, rates_used, effective_date, carried_forward) |
rate.json or the day snapshot |
.status() |
Status (status, updated_at, age_hours, stale, supported_currencies) |
/api/v1/status.json |
Dates accept datetime.date, datetime.datetime or "YYYY-MM-DD". Currency
codes are case-insensitive. Rates/DayRate support rates["USD"],
rates.get("EUR") and rates.usd (try_ for the Turkish lira). Every result
has to_dict() (JSON-ready) and a readable str().
Exceptions
BCVError
├── InvalidArgument (ValueError)
│ ├── InvalidDate malformed date, or start after end
│ ├── InvalidCurrency unknown code, or from == to
│ └── InvalidAmount negative, non-finite, > 1e15
├── DateOutOfRange before 2021-08-02, after tomorrow (Caracas), not published yet
├── CurrencyNotAvailable no rate for that currency on that day
├── NotFound HTTP 404
├── UpstreamError network error, HTTP error, invalid JSON (.status)
└── MissingDependency extra not installed (ImportError)
Command line
$ bcv latest
Official BCV rates, effective 2026-11-18 (Bs. per unit)
Currency Rate (VES)
-------- ----------
USD 916.6477
EUR 1,007.3867
CNY 137.5233
TRY 18.2102
RUB 11.1719
$ bcv on 2026-01-04 --currency USD
$ bcv convert 100 USD VES [--date 2026-01-04] [--decimals 2]
$ bcv history USD --days 7 # or --start 2026-01-01 --end 2026-01-31
$ bcv status
$ bcv latest --json # machine output on any command
python -m bcv works too. Exit codes: 0 success, 1 no data for the request
(date out of range, currency not available that day), 2 invalid arguments, 3
network or API error. With --json, errors are also printed to stdout as
{"error": {"type": ..., "message": ...}}.
How the data works
- Value date and carry-forward.
effective_dateis BCV's official validity date ("fecha valor");updated_atis the UTC capture time. BCV does not publish on weekends and holidays, so the last published rate stays in effect:on("2026-01-04")(Sunday) returns the rate witheffective_date2026-01-03 andcarried_forward=True, plus a humannote. BCV publishes the next business day's rate in the afternoon, soeffective_dateoflatest()can be tomorrow. - Range. Daily snapshots start on 2021-08-02. Dates after tomorrow
(Caracas time, UTC-4) raise
DateOutOfRange.history()readshistory.json, which keeps the latest 1830 daily entries; older single days are available throughon(). Older entries may lack some currencies (EUR, CNY, TRY and RUB appear later than USD); those days raiseCurrencyNotAvailableor are skipped in a history series. - Money math. Rates are parsed from JSON directly into
Decimal. Conversions go through the bolivar (amount * VES_per_from / VES_per_to) with 28 significant digits;resultis rounded todecimalsplaces (default 2) with ROUND_HALF_UP, andresult_exactkeeps the unrounded value.rateis the unrounded cross rate. Float amounts are converted withstr(); passDecimalor a string for exact input. - Caching. Each client keeps responses in memory for
cache_ttlseconds (default 300;0disables). Callclient.clear_cache()to force a refresh. The data changes a few times per business day at most, and the API is served from a CDN, so there is no need to poll more often than every few minutes. - User-Agent. Requests send
bcv-python/<version> (+https://bcv.today).
Attribution and license
Code: Apache-2.0 (see LICENSE). Data: CC BY 4.0, see
bcv.today/licencia. When you display the rates,
credit the source, for example:
Rates: Banco Central de Venezuela, via BCV Today.
En español
bcv es el cliente Python oficial de la API de BCV Today:
tasas oficiales del Banco Central de Venezuela (bolívares por USD, EUR, CNY, TRY y
RUB), sin dependencias y con línea de comandos. Proyecto no oficial: no está
afiliado al Banco Central de Venezuela.
pip install bcv
bcv latest
bcv convert 100 USD VES
bcv on 2026-01-04 --currency USD # domingo: usa la tasa vigente con fecha valor 2026-01-03
effective_date es la fecha valor del BCV. Los fines de semana y feriados se
mantiene la última tasa publicada (carried_forward=True). Datos desde el
2021-08-02. Licencia de los datos: CC BY 4.0, cita la fuente "BCV Today".
Links
- Website: https://bcv.today
- API documentation: https://bcv.today/api/
- Source and issues: https://github.com/grupoclip/bcv-api
Metadata
Release files for bcv 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| bcv-1.0.0.tar.gz | 36.5 kB | With provenance | Details for bcv-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| bcv-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for bcv-1.0.0-py3-none-any.whl |
Total release size: 67.5 kB
Release files / bcv-1.0.0.tar.gz
| Download URL | bcv-1.0.0.tar.gz |
|---|---|
| Size | 36.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b51050864f7eef0808b233e156b2a7aef26f2f61f4f04a6c9ec26c24f2c7affd
|
|
BLAKE2b-256 checksum How to use checksums |
6944fe0d44811d608e765a1191e2d696e04eac38802581307d2dfb30c5b14dc3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logRelease files / bcv-1.0.0-py3-none-any.whl
| Download URL | bcv-1.0.0-py3-none-any.whl |
|---|---|
| Size | 31.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b13007f351f65dffaeb21e9d3e51c98c995569d804187d36b615ece4e64ad77c
|
|
BLAKE2b-256 checksum How to use checksums |
fbcd54615583255d22160ef7ec4cddfd40d7eb8deec778290bde9cbd25292ade
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logSecurity for bcv 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for bcv-1.0.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.