BACEN Service
Some free exchange-rate APIs block requests that come from cloud providers: the service answers on your laptop and fails once it runs on AWS. The PTAX of the Central Bank of Brazil (BCB, Banco Central do Brasil) is a public API, with no key and no sign-up, that quotes every major currency in Brazilian reals (BRL). This page gives the whole exchange microservice, in Python with FastAPI, backed by PTAX: your job is the container and wiring it into the platform.
Learning objectives
After this page you should be able to:
- Containerize a Python service managed by uv, with a reproducible lock file.
- Integrate a new microservice into the Compose stack and behind the gateway.
- Explain how a cross rate (USD → EUR) comes out of quotes that are all in BRL.
Optional
Using this service is an option of the Exchange API exercise: you may still write your own service on any third-party API. If you take this one, say so in your repository's README.
How it works
The gateway resolves who is calling and forwards the request with the id-account header. The service asks PTAX for the latest quote of each currency in BRL (the last 7 days, since weekends and holidays have no quote), keeps it in memory for 5 minutes and divides one by the other. Only one request per currency refreshes the cache at a time: the others wait for it instead of all calling the BCB together. When PTAX fails and an old rate is in memory, the service answers with it.
sequenceDiagram
participant G as gateway
participant E as exchange
participant P as PTAX (BCB)
G->>E: GET /exchange/USD/EUR + id-account
E->>P: CotacaoMoedaPeriodo USD, last 7 days
P-->>E: buy/sell in BRL, every bulletin
E->>P: CotacaoMoedaPeriodo EUR, last 7 days
P-->>E: buy/sell in BRL, every bulletin
E->>E: cross rate through BRL, cache 5 min
E-->>G: {"sell", "buy", "date", "id-account"} PTAX only quotes against the real, so USD → EUR goes through BRL. With \(c\) (buy) and \(v\) (sell) the PTAX quotes in BRL:
buy is what the market pays for 1 USD, in euros (it buys your dollars and sells you euros); sell is what it charges. BRL itself counts as 1, so GET /exchange/USD/BRL is the PTAX quote of the dollar.
The project
exchange/
├── pyproject.toml
├── uv.lock # created by uv lock: commit it
└── main.py
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 | |
| Endpoint | Returns |
|---|---|
GET /exchange/{from}/{to} | the rate from one currency to another (also answers on /exchanges/..., as the exercise statement spells it) |
GET /exchange/currencies | the currencies PTAX quotes, besides BRL |
GET /health | {"status": "ok"}, for the container health check |
Every rate response carries the header X-Cache: miss (PTAX was called), hit (rate from memory) or stale (PTAX failed and an expired rate was served). The settings come from environment variables, so the container changes them without a new image:
| Variable | Default | What it sets |
|---|---|---|
PTAX_URL | the BCB address | base URL of the PTAX API |
PTAX_TIMEOUT | 3 | seconds to wait for PTAX |
CACHE_SECONDS | 300 | how long a rate is reused before asking PTAX again |
RETRY_SECONDS | 30 | after a failed call, how long the old rate is served before trying again |
Run it locally
In the exchange/ folder:
In another terminal:
You should see something like:
{"sell":0.906885,"buy":0.9066,"date":"2026-11-13 13:03:27","id-account":"0195ae95-5be7-7dd3-b35d-7a7d87c404fb"}
The date is the PTAX bulletin used: on a weekend or before 10 a.m. (BrasÃlia) it is the last business day. Without the header the service answers 422; an unknown currency (/exchange/XYZ/BRL) answers 404.
Your task: the container
- Write the
Dockerfileof the service:- base image
python:3.12-slim, with theuvbinary copied fromghcr.io/astral-sh/uv1; - copy
pyproject.tomlanduv.lockbeforemain.pyand runuv sync --frozen, so a code change does not reinstall the dependencies; - start
uvicorn main:appon0.0.0.0:8000.
- base image
- Add the service
exchangeto the platform'scompose.yaml(no port published: only the gateway reaches it). - Add the gateway route
Path=/exchange/**→http://exchange:8000, behind authentication like the other business routes. - Check it through the gateway: log in, then
GET /exchange/USD/EURwith the token returns the rate and yourid-account. - In the cloud: from a pod of the cluster,
curlthe PTAX URL once to confirm the provider answers from AWS.
Limits of PTAX
- Quotes only exist on business days, between about 10 a.m. and 1 p.m. (BrasÃlia); outside that window the service returns the last bulletin.
- The cache lives in the process memory: a restarted container asks PTAX again, and if BCB does not answer and there is no cached rate the service answers
502. - PTAX is a public service of the BCB: do not load test it. Keep the cache on; a load test against your gateway should cause only a handful of calls to PTAX (count the
X-Cache: miss).