Official Java client for the UniRate API — free, real-time and historical currency exchange rates plus VAT rates.
- Real-time exchange rates between 170+ currencies (fiat + crypto)
- Historical rates back to 1999
- Time-series ranges up to 5 years
- Currency conversion (current and historical)
- VAT rates for countries worldwide
- Free tier, no credit card required
- Pure Java —
java.net.http.HttpClient+ Jackson, nothing else - Typed exception hierarchy rooted at
UniRateException
- Java 11+
- Maven (or Gradle)
<dependency>
<groupId>com.unirateapi</groupId>
<artifactId>unirate-api</artifactId>
<version>0.1.0</version>
</dependency>implementation "com.unirateapi:unirate-api:0.1.0"importcom.unirateapi.client.UniRateClient;
UniRateClientclient = newUniRateClient("your-api-key");
// Current ratedoublerate = client.getRate("USD", "EUR");
System.out.println("USD -> EUR: " + rate);
// Convertdoubleeuros = client.convert(100, "USD", "EUR");
System.out.println("100 USD = " + euros + " EUR");
// All supported currenciesjava.util.List<String> currencies = client.getSupportedCurrencies();
System.out.println(currencies.size() + " currencies supported");Get a free API key at https://unirateapi.com.
// Single pairdoublerate = client.getRate("USD", "EUR");
// All rates for a baseMap<String, Double> rates = client.getAllRates("USD");
// Convert an amountdoubleresult = client.convert(100, "USD", "EUR");
// Supported currency listList<String> codes = client.getSupportedCurrencies();// Rate on a specific datedoublerate = client.getHistoricalRate("2024-01-01", "USD", "EUR");
// All rates on a dateMap<String, Double> rates = client.getHistoricalRates("2024-01-01", "USD");
// Convert using historical ratedoubleamount = client.convertHistorical(100, "USD", "EUR", "2024-01-01");
// Time seriesMap<String, Map<String, Double>> series = client.getTimeSeries(
"2024-01-01", "2024-01-07",
"USD", List.of("EUR", "GBP"),
1);
// Available historical coverage per currencyHistoricalLimitsResponselimits = client.getHistoricalLimits();// All countriesVatRatesResponsevatRates = client.getVatRates();
// Single country (ISO-3166 alpha-2 code)VatCountryResponsegermany = client.getVatRate("DE");
System.out.println("Germany VAT: " + germany.getVatData().getVatRate() + "%");All methods throw unchecked exceptions extending UniRateException:
try {
doublerate = client.getRate("USD", "ZZZ");
} catch (AuthenticationExceptione) {
// invalid API key
} catch (InvalidCurrencyExceptione) {
// unknown currency code
} catch (RateLimitExceptione) {
// back off and retry
} catch (InvalidDateExceptione) {
// bad date format / parameters
} catch (ApiExceptione) {
// other HTTP error (e.g. 403 Pro-gated, 503)System.err.println("status " + e.getStatusCode() + ": " + e.getBody());
} catch (UniRateExceptione) {
// transport / decoding failure
}| HTTP status | Exception type |
|---|---|
| 400 | InvalidDateException |
| 401 | AuthenticationException |
| 403 | ApiException (Pro-gated endpoint on free tier) |
| 404 | InvalidCurrencyException |
| 429 | RateLimitException |
| 503 | ApiException |
| other | ApiException |
| network / decode | UniRateException |
The client accepts anything implementing HttpTransport (one method, takes an HttpRequest, returns an HttpResponse<String>), which makes mocking trivial in tests:
HttpTransportstub = request -> newStubResponse(200, "{\"rate\": 0.9}", request);
UniRateClientclient = newUniRateClient(
"test-key",
"https://api.unirateapi.com",
Duration.ofSeconds(5),
stub);See src/test/java/com/unirateapi/client/UniRateClientTest.java for the full pattern.
UNIRATE_API_KEY=your-key mvn -q compile exec:java \
-Dexec.mainClass=com.unirateapi.examples.Example# Mock tests (~18, no network)
mvn -q test# Mock + live free-tier tests
UNIRATE_API_KEY=your-key mvn -q test- Currency endpoints: standard rate limits apply
- Historical endpoints: 50 requests/hour on the free tier
- VAT endpoints: 1800 requests/hour on the free tier
- unirate-api-python (PyPI:
unirate-api) - unirate-api-nodejs (npm:
unirate-api) - unirate-api-swift (Swift Package Manager)
UniRate ships official integrations for 40+ ecosystems, all maintained under the UniRate-API org.
Core clients (9 languages)Python · Node.js / TypeScript · Go · Rust · Java · Ruby · PHP · .NET · Swift
JavaScript / TypeScriptReact · Next.js · Remix · SvelteKit · Vue · Angular · Nuxt · NestJS · tRPC
Static-site generatorsAstro · Eleventy · Hugo · Jekyll
CMS & e-commerceWagtail · WordPress · WooCommerce · Drupal · Strapi · Medusa · Symfony · Laravel · Directus
Data, AI & backendLangChain (Python) · LangChain.js · FastAPI · Flask · Django REST Framework · Apache Airflow · dbt
Platform & toolsMCP server · CLI · Cloudflare Workers · Home Assistant · n8n · Google Sheets · VS Code · Obsidian
Money library bridgesmoney gem (Ruby) · NodaMoney (.NET)
Get a free API key at unirateapi.com.
MIT — see LICENSE.