@allratestoday/bcb-exchange-rate 1.1.2 → 1.2.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +210 -25
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,65 +1,250 @@
|
|
|
1
|
-
# Banco Central do Brasil Exchange Rate API
|
|
1
|
+
# Banco Central do Brasil Exchange Rate API — bcb-exchange-rate
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@allratestoday/bcb-exchange-rate)
|
|
4
|
+
[](https://github.com/AllRates-Today/bcb-exchange-rate/blob/main/LICENSE)
|
|
5
|
+
[](https://www.npmjs.com/package/@allratestoday/bcb-exchange-rate)
|
|
6
|
+
[](https://www.typescriptlang.org/)
|
|
4
7
|
|
|
5
|
-
|
|
8
|
+
**Official Banco Central do Brasil (Brazil) daily exchange rates for Node.js and TypeScript. The published central bank rates behind tax filings, customs valuations, audits, and compliant invoicing — not market estimates, but the numbers Banco Central do Brasil itself prints, every business day.**
|
|
6
9
|
|
|
7
|
-
|
|
10
|
+
## 🚀 Why this client?
|
|
8
11
|
|
|
9
|
-
|
|
12
|
+
- 🏛️ **Official published rates** — Banco Central do Brasil's own table, with the publisher's own `rate_date` on every response
|
|
13
|
+
- 📅 **History back to 2016** — point-in-time tables and daily series for any past date
|
|
14
|
+
- 🔀 **Published vs derived, always flagged** — computed inverse/cross pairs carry `derived: true`, never mixed with official prints
|
|
15
|
+
- ⚡ **Zero dependencies** — pure ESM + CJS over global `fetch`; Node 18+, Bun, Deno, and edge runtimes
|
|
16
|
+
- 🔷 **Type-safe** — full TypeScript definitions shipped with the package
|
|
17
|
+
- 🧾 **Compliance-grade metadata** — `rate_type`, publication date, and source disclaimer on every response
|
|
18
|
+
|
|
19
|
+
> **Official rate, not mid-market:** every value here is a number Banco Central do Brasil itself published, fixed once printed and carrying the central bank's own `rate_date` — what filings and audits require. Need the live interbank midpoint for pricing or display instead? Use the [mid-market API](https://allratestoday.com/docs/) or [`@allratestoday/sdk`](https://www.npmjs.com/package/@allratestoday/sdk). The two can diverge by several percent.
|
|
20
|
+
|
|
21
|
+
## 🔑 Get your API key
|
|
22
|
+
|
|
23
|
+
Get a free API key at [allratestoday.com/register](https://allratestoday.com/register) — no credit card required. Latest rates are on every plan, including free.
|
|
24
|
+
|
|
25
|
+
## 📦 Installation
|
|
10
26
|
|
|
11
27
|
```bash
|
|
12
28
|
npm install @allratestoday/bcb-exchange-rate
|
|
13
29
|
```
|
|
14
30
|
|
|
15
|
-
|
|
31
|
+
```bash
|
|
32
|
+
yarn add @allratestoday/bcb-exchange-rate
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
pnpm add @allratestoday/bcb-exchange-rate
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Scoped mirror of [`bcb-exchange-rate`](https://www.npmjs.com/package/bcb-exchange-rate) — same code, same versions.
|
|
40
|
+
|
|
41
|
+
## 🏁 Quick start
|
|
16
42
|
|
|
17
43
|
```js
|
|
18
|
-
import { getRate
|
|
44
|
+
import { getRate } from '@allratestoday/bcb-exchange-rate';
|
|
45
|
+
|
|
46
|
+
const pair = await getRate('USD', 'BRL', { apiKey: 'art_live_...' });
|
|
47
|
+
console.log(pair.rate, pair.rate_date); // the official Banco Central do Brasil rate, on the central bank's own date
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## 📚 API reference
|
|
19
51
|
|
|
20
|
-
|
|
52
|
+
- [Latest pair rate](#latest-pair-rate) — one pair from the latest published table
|
|
53
|
+
- [Full published table](#full-published-table) — everything the central bank printed, in one call
|
|
54
|
+
- [Table for a date](#table-for-a-date) — the official table for an invoice or filing date
|
|
55
|
+
- [Daily time series](#daily-time-series) — one pair across a date range
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
### Latest pair rate
|
|
60
|
+
|
|
61
|
+
Free plan and up. Pairs the central bank does not print directly are resolved from its table and flagged (see *Published vs derived rates* below).
|
|
62
|
+
|
|
63
|
+
```js
|
|
21
64
|
const pair = await getRate('USD', 'BRL', { apiKey: 'art_live_...' });
|
|
22
|
-
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
**Response:**
|
|
68
|
+
|
|
69
|
+
```javascript
|
|
70
|
+
{
|
|
71
|
+
bank: 'bcb',
|
|
72
|
+
name: 'Banco Central do Brasil',
|
|
73
|
+
rate_date: '2026-08-10', // Banco Central do Brasil's own publication date
|
|
74
|
+
source: 'USD',
|
|
75
|
+
target: 'BRL',
|
|
76
|
+
rate: 5.0963,
|
|
77
|
+
rate_type: 'sell',
|
|
78
|
+
derived: false,
|
|
79
|
+
method: 'published',
|
|
80
|
+
disclaimer: '…'
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
### Full published table
|
|
85
|
+
|
|
86
|
+
Free plan and up. The complete table for the latest publication date.
|
|
87
|
+
|
|
88
|
+
```js
|
|
89
|
+
import { getLatestRates } from '@allratestoday/bcb-exchange-rate';
|
|
23
90
|
|
|
24
|
-
// The bank's full published table
|
|
25
91
|
const table = await getLatestRates({ apiKey: 'art_live_...' });
|
|
26
92
|
console.log(table.rate_date, table.rates.length);
|
|
27
93
|
```
|
|
28
94
|
|
|
29
|
-
|
|
95
|
+
**Response:**
|
|
96
|
+
|
|
97
|
+
```javascript
|
|
98
|
+
{
|
|
99
|
+
bank: 'bcb',
|
|
100
|
+
name: 'Banco Central do Brasil',
|
|
101
|
+
rate_date: '2026-08-10',
|
|
102
|
+
rates: [
|
|
103
|
+
{ "base": "USD", "quote": "BRL", "type": "sell", "value": 5.0963 },
|
|
104
|
+
{ "base": "USD", "quote": "BRL", "type": "buy", "value": 5.0957 },
|
|
105
|
+
// … the rest of the published table (156 currencies vs BRL)
|
|
106
|
+
],
|
|
107
|
+
disclaimer: '…'
|
|
108
|
+
}
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
### Table for a date
|
|
112
|
+
|
|
113
|
+
Paid plans. The official table for any date since 2016 — weekends and holidays return the most recent published date, flagged via `published_on_requested_date`, which is exactly the in-force rate a filing needs.
|
|
30
114
|
|
|
31
115
|
```js
|
|
32
|
-
import { getRatesForDate
|
|
116
|
+
import { getRatesForDate } from '@allratestoday/bcb-exchange-rate';
|
|
33
117
|
|
|
34
|
-
// The official table for an invoice date — weekends/holidays return the
|
|
35
|
-
// most recent published date, flagged via published_on_requested_date.
|
|
36
118
|
const day = await getRatesForDate('2026-06-30', { apiKey: 'art_live_...' });
|
|
119
|
+
// Optionally narrow to one pair:
|
|
120
|
+
const one = await getRatesForDate('2026-06-30', { apiKey: 'art_live_...', source: 'USD', target: 'BRL' });
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
**Response:**
|
|
124
|
+
|
|
125
|
+
```javascript
|
|
126
|
+
{
|
|
127
|
+
bank: 'bcb',
|
|
128
|
+
requested_date: '2026-06-30',
|
|
129
|
+
rate_date: '2026-06-30', // the date actually published
|
|
130
|
+
published_on_requested_date: true, // false when a weekend/holiday fell back
|
|
131
|
+
rates: [ /* the full table for that date */ ],
|
|
132
|
+
disclaimer: '…'
|
|
133
|
+
}
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
### Daily time series
|
|
137
|
+
|
|
138
|
+
Paid plans. One resolved rate per publication date — ready for charting, revaluation runs, or audit workpapers.
|
|
139
|
+
|
|
140
|
+
```js
|
|
141
|
+
import { getHistory } from '@allratestoday/bcb-exchange-rate';
|
|
37
142
|
|
|
38
|
-
// Daily series for one pair
|
|
39
143
|
const series = await getHistory(
|
|
40
|
-
{ source: 'USD', target: 'BRL', from: '2026-01-01' },
|
|
144
|
+
{ source: 'USD', target: 'BRL', from: '2026-01-01', to: '2026-08-10' },
|
|
41
145
|
{ apiKey: 'art_live_...' }
|
|
42
146
|
);
|
|
43
147
|
```
|
|
44
148
|
|
|
45
|
-
|
|
149
|
+
**Response:**
|
|
150
|
+
|
|
151
|
+
```javascript
|
|
152
|
+
{
|
|
153
|
+
bank: 'bcb',
|
|
154
|
+
source: 'USD',
|
|
155
|
+
target: 'BRL',
|
|
156
|
+
from: '2026-01-01',
|
|
157
|
+
to: '2026-08-10',
|
|
158
|
+
count: 152,
|
|
159
|
+
rates: [
|
|
160
|
+
// one entry per publication date
|
|
161
|
+
{ date: '2026-08-10', rate: 5.0963, rate_type: 'sell', derived: false, method: 'published' },
|
|
162
|
+
// …
|
|
163
|
+
],
|
|
164
|
+
disclaimer: '…'
|
|
165
|
+
}
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
Pass `{ symbol: 'USD' }` instead of `source`/`target` to get the raw published rows for one currency (all rate types, no pair resolution).
|
|
169
|
+
|
|
170
|
+
---
|
|
171
|
+
|
|
172
|
+
## 🗺️ Currencies covered
|
|
46
173
|
|
|
47
174
|
Banco Central do Brasil currently publishes rates covering **157 currencies** (as of the latest table):
|
|
48
175
|
|
|
49
176
|
`AED` · `AFN` · `ALL` · `AMD` · `AOA` · `ARS` · `AUD` · `AWG` · `AZN` · `BBD` · `BDT` · `BHD` · `BIF` · `BMD` · `BND` · `BOB` · `BRL` · `BSD` · `BTN` · `BWP` · `BYN` · `BZD` · `CAD` · `CDF` · `CHF` · `CLF` · `CLP` · `CNH` · `CNY` · `COP` · `COU` · `CRC` · `CUP` · `CVE` · `CZK` · `DJF` · `DKK` · `DOP` · `DZD` · `EGP` · `ERN` · `ETB` · `EUR` · `FJD` · `FKP` · `GBP` · `GEL` · `GHS` · `GIP` · `GMD` · `GNF` · `GTQ` · `GYD` · `HKD` · `HNL` · `HTG` · `HUF` · `IDR` · `ILS` · `INR` · `IQD` · `IRR` · `ISK` · `JMD` · `JOD` · `JPY` · `KES` · `KGS` · `KHR` · `KMF` · `KRW` · `KWD` · `KYD` · `KZT` · `LAK` · `LBP` · `LKR` · `LRD` · `LSL` · `LYD` · `MAD` · `MDL` · `MGA` · `MKD` · `MMK` · `MNT` · `MOP` · `MRO` · `MRU` · `MUR` · `MVR` · `MWK` · `MXN` · `MYR` · `MZN` · `NAD` · `NGN` · `NIO` · `NOK` · `NPR` · `NZD` · `OMR` · `PAB` · `PEN` · `PGK` · `PHP` · `PKR` · `PLN` · `PYG` · `QAR` · `RON` · `RSD` · `RUB` · `RWF` · `SAR` · `SBD` · `SCR` · `SDG` · `SDR` · `SEK` · `SGD` · `SHP` · `SLL` · `SOS` · `SRD` · `SSP` · `STN` · `SVC` · `SYP` · `SZL` · `THB` · `TJS` · `TMT` · `TND` · `TOP` · `TRY` · `TTD` · `TWD` · `TZS` · `UAH` · `UGX` · `USD` · `UYU` · `UZS` · `VES` · `VND` · `VUV` · `WST` · `XAF` · `XAU` · `XCD` · `XCG` · `XOF` · `XPF` · `YER` · `ZAR` · `ZMW`
|
|
50
177
|
|
|
51
|
-
|
|
178
|
+
## ⚖️ Published vs derived rates
|
|
179
|
+
|
|
180
|
+
If Banco Central do Brasil does not print a pair directly, the API resolves it from the central bank's own table and says so — official and computed values are never confused:
|
|
181
|
+
|
|
182
|
+
| `method` | `derived` | Meaning |
|
|
183
|
+
| --- | --- | --- |
|
|
184
|
+
| `published` | `false` | The central bank printed this pair directly |
|
|
185
|
+
| `inverse` | `true` | Computed as 1 ÷ the published opposite direction |
|
|
186
|
+
| `cross` | `true` | Computed via BRL from two published rates |
|
|
187
|
+
|
|
188
|
+
## 🛡️ Error handling
|
|
189
|
+
|
|
190
|
+
Errors are thrown as `Error` with `status` (HTTP code) and `body` (the API's JSON error) attached:
|
|
191
|
+
|
|
192
|
+
```js
|
|
193
|
+
try {
|
|
194
|
+
const pair = await getRate('USD', 'XXX', { apiKey: 'art_live_...' });
|
|
195
|
+
} catch (err) {
|
|
196
|
+
console.log(err.message); // human-readable reason
|
|
197
|
+
console.log(err.status); // e.g. 404
|
|
198
|
+
}
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
| Status | Meaning |
|
|
202
|
+
| ------ | ------- |
|
|
203
|
+
| — | Missing `apiKey` (thrown before any request) |
|
|
204
|
+
| `400` | Malformed date or parameters |
|
|
205
|
+
| `401` | Invalid API key |
|
|
206
|
+
| `403` | Endpoint needs a [paid plan](https://allratestoday.com/pricing/) (historical dates & series) |
|
|
207
|
+
| `404` | Pair or date range not covered by Banco Central do Brasil |
|
|
208
|
+
| `429` | Monthly quota exceeded |
|
|
209
|
+
|
|
210
|
+
## 🔷 TypeScript
|
|
211
|
+
|
|
212
|
+
Full definitions ship with the package — no `@types` install:
|
|
213
|
+
|
|
214
|
+
```ts
|
|
215
|
+
import type { LatestRates, PairRate, DatedRates, RateEntry, HistoryQuery, RequestOptions } from '@allratestoday/bcb-exchange-rate';
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
## 📦 CommonJS
|
|
219
|
+
|
|
220
|
+
```javascript
|
|
221
|
+
const { getRate } = require('@allratestoday/bcb-exchange-rate');
|
|
222
|
+
|
|
223
|
+
getRate('USD', 'BRL', { apiKey: 'art_live_...' }).then((pair) => console.log(pair.rate));
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
## 💡 Quota tips
|
|
227
|
+
|
|
228
|
+
- Rates change once per business day — cache the published table locally and a small monthly quota goes a long way.
|
|
229
|
+
- Every request counts toward your AllRatesToday quota, shared across all AllRatesToday endpoints on your key.
|
|
52
230
|
|
|
53
|
-
##
|
|
231
|
+
## 📖 Methods reference
|
|
54
232
|
|
|
55
|
-
|
|
233
|
+
| Method | Plan | Description |
|
|
234
|
+
| ------ | ---- | ----------- |
|
|
235
|
+
| `getRate(source, target, { apiKey })` | Free | Latest rate for one pair, resolved from the published table |
|
|
236
|
+
| `getLatestRates({ apiKey })` | Free | The central bank's full latest published table |
|
|
237
|
+
| `getRatesForDate(date, { apiKey, source?, target? })` | Paid | The official table (or one pair) for a YYYY-MM-DD date |
|
|
238
|
+
| `getHistory({ symbol \| source+target, from?, to? }, { apiKey })` | Paid | Daily series since 2016 |
|
|
56
239
|
|
|
57
|
-
##
|
|
240
|
+
## 🔗 Links
|
|
58
241
|
|
|
59
|
-
-
|
|
60
|
-
-
|
|
61
|
-
-
|
|
242
|
+
- [Banco Central do Brasil rates page](https://allratestoday.com/central-bank-rates-api/bcb/) — live table, publication cadence, FAQ
|
|
243
|
+
- [All central bank sources](https://allratestoday.com/central-bank-rates-api/)
|
|
244
|
+
- [API documentation](https://allratestoday.com/docs/#central-bank) · [Interactive reference](https://allratestoday.com/api-reference/)
|
|
245
|
+
- [Register (free)](https://allratestoday.com/register) · [Pricing](https://allratestoday.com/pricing/)
|
|
246
|
+
- [GitHub](https://github.com/AllRates-Today/bcb-exchange-rate)
|
|
62
247
|
|
|
63
|
-
## License
|
|
248
|
+
## 📜 License
|
|
64
249
|
|
|
65
250
|
MIT
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@allratestoday/bcb-exchange-rate",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.2.2",
|
|
4
4
|
"description": "Official Banco Central do Brasil (Brazil) daily exchange rates — 156 currencies vs BRL, history since 2016. Zero-dependency Node.js/TypeScript client.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"bcb",
|