Skip to content
Java guide

Exchange rate API in Java and Spring Boot

Call the fxapi exchange rate API with the JDK’s built-in HttpClient, map responses to Java records with Jackson, convert with BigDecimal and cache in Spring with @Cacheable.

Last updated: · fxapi team

This guide shows how to integrate an exchange rate API in Java without extra HTTP libraries. You’ll use java.net.http.HttpClient for requests, Jackson to map JSON to records, BigDecimal for conversion, and Spring’s @Cacheable with Caffeine to keep API calls to a minimum. Every example handles fxapi’s error codes explicitly.

Setup

Get a key from the free sign-up and expose it as FXAPI_KEY (or fxapi.key in Spring configuration). The only dependency is Jackson 3 for JSON:

tools.jackson.core:jackson-databind:3.2.4

Spring Boot 4’s web starters already include it. Jackson 3 lives in the tools.jackson packages and reads java.time types without an extra module; only the annotations keep their com.fasterxml.jackson.annotation package. On a Jackson 2 stack (Spring Boot 3), use the com.fasterxml.jackson.databind imports instead and add jackson-datatype-jsr310.

Records for the JSON response

/v1/latest, /v1/historical and /v1/convert return the same shape. One file per record, as Java requires for public types:

// Rate.java
import java.math.BigDecimal;

public record Rate(String code, BigDecimal value) {}

// Meta.java
import com.fasterxml.jackson.annotation.JsonProperty;
import java.time.Instant;

public record Meta(
        @JsonProperty("last_updated_at") Instant lastUpdatedAt,
        @JsonProperty("base_currency") String baseCurrency) {}

// RatesResponse.java
import java.util.Map;

public record RatesResponse(Meta meta, Map<String, Rate> data) {}

Mapping value to BigDecimal keeps the exact digits from the JSON instead of a binary double approximation.

An exchange rate API client in Java with HttpClient

import java.io.IOException;
import java.io.UncheckedIOException;
import java.math.BigDecimal;
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.time.LocalDate;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;
import tools.jackson.core.JacksonException;
import tools.jackson.databind.DeserializationFeature;
import tools.jackson.databind.json.JsonMapper;

public final class FxApiClient {
    private static final String BASE = "https://api.fxapi.com/v1/";

    private final HttpClient http = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(5))
            .build();
    private final JsonMapper mapper = JsonMapper.builder() // java.time support is built in
            .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
            .build();
    private final String apiKey;

    public FxApiClient(String apiKey) {
        this.apiKey = apiKey;
    }

    public RatesResponse latest(String base, String currencies) {
        return get("latest", params("base_currency", base, "currencies", currencies));
    }

    public RatesResponse historical(LocalDate date, String base, String currencies) {
        return get("historical", params("date", date.toString(), "base_currency", base, "currencies", currencies));
    }

    /** Requires the Basic plan or higher (HTTP 403 otherwise). */
    public RatesResponse convert(BigDecimal value, String base, String currencies) {
        return get("convert", params("value", value.toPlainString(), "base_currency", base, "currencies", currencies));
    }

    private static Map<String, String> params(String... kv) {
        Map<String, String> map = new LinkedHashMap<>();
        for (int i = 0; i < kv.length; i += 2) {
            if (kv[i + 1] != null) map.put(kv[i], kv[i + 1]);
        }
        return map;
    }

    private RatesResponse get(String endpoint, Map<String, String> params) {
        String query = params.entrySet().stream()
                .map(e -> e.getKey() + "=" + URLEncoder.encode(e.getValue(), StandardCharsets.UTF_8))
                .collect(Collectors.joining("&"));
        HttpRequest request = HttpRequest.newBuilder(URI.create(BASE + endpoint + "?" + query))
                .header("apikey", apiKey)
                .header("Accept", "application/json")
                .timeout(Duration.ofSeconds(10))
                .GET()
                .build();
        try {
            HttpResponse<String> res = http.send(request, HttpResponse.BodyHandlers.ofString());
            if (res.statusCode() == 200) {
                return mapper.readValue(res.body(), RatesResponse.class);
            }
            throw toException(res);
        } catch (IOException e) {
            throw new UncheckedIOException(e);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw new IllegalStateException("Interrupted while calling fxapi", e);
        }
    }

    record ErrorInfo(String code) {}
    record ErrorBody(String message, ErrorInfo error, Map<String, List<String>> errors) {}

    private FxApiException toException(HttpResponse<String> res) {
        ErrorBody body;
        try {
            body = mapper.readValue(res.body(), ErrorBody.class);
        } catch (JacksonException e) {
            body = new ErrorBody(null, null, null); // keep the status even if the body isn't JSON
        }
        String code = body.error() == null ? null : body.error().code();
        String message = switch (res.statusCode()) {
            case 401 -> "Missing or invalid API key";
            case 403 -> "Endpoint or option not included in your plan";
            case 404 -> "No data for this date or range";
            case 422 -> "Validation error: " + body.errors();
            case 429 -> "rate_limit_exceeded".equals(code)
                    ? "Per-minute limit reached, retry in "
                            + res.headers().firstValue("Retry-After").orElse("60") + " s"
                    : "Monthly quota used up";
            default -> body.message() != null ? body.message() : "Unexpected status";
        };
        return new FxApiException(res.statusCode(), code, message);
    }
}
public class FxApiException extends RuntimeException {
    private final int status;
    private final String code; // error.code, e.g. "quota_exceeded"; null on 422

    public FxApiException(int status, String code, String message) {
        super(status + ": " + message);
        this.status = status;
        this.code = code;
    }

    public int status() { return status; }

    public String code() { return code; }
}

A 422 body contains an errors object keyed by parameter (for example a date in the future), and it doesn’t count against your quota. 401, 403, 404 and 429 bodies carry a machine-readable error.code; a 429 with rate_limit_exceeded is the Free plan’s 10 requests per minute (wait the Retry-After seconds), one with quota_exceeded means the monthly quota is used up. In Jackson 3, parse errors are unchecked JacksonExceptions, so a malformed body surfaces as a runtime exception as well.

Latest and historical exchange rates in Java

var fx = new FxApiClient(System.getenv("FXAPI_KEY"));

RatesResponse latest = fx.latest("EUR", "USD,GBP,CHF");
System.out.println(latest.meta().lastUpdatedAt() + " EUR/USD " + latest.data().get("USD").value());

RatesResponse hist = fx.historical(LocalDate.of(2024, 12, 31), "USD", "EUR,JPY");
System.out.println(hist.data().get("JPY").value());

Historical values are end-of-day rates in UTC, available from 1999-01-01 up to yesterday. Pass null for currencies to get all 190+ in one response. More on the historical exchange rates API.

Currency conversion with BigDecimal

On Basic and higher plans, the /v1/convert endpoint of the currency converter API does it for you: fx.convert(new BigDecimal("250"), "USD", "EUR") returns the converted amount. On the Free plan, or when you already have cached rates, compute it locally:

import java.math.RoundingMode;

BigDecimal rate = fx.latest("USD", "EUR").data().get("EUR").value();
BigDecimal eur = new BigDecimal("250.00").multiply(rate).setScale(2, RoundingMode.HALF_EVEN);

Use the currency’s decimal_digits from /v1/currencies instead of a hard-coded 2 – JPY has 0 and KWD 3. The rounding guide covers half-even versus half-up and cross rates.

Spring Boot: caching with @Cacheable

Add spring-boot-starter-cache and com.github.ben-manes.caffeine:caffeine, then set the TTL to your plan’s update interval – daily on Free, hourly on Basic, 60 seconds on Professional and Enterprise (pricing):

# application.properties
fxapi.key=${FXAPI_KEY}
spring.cache.cache-names=fx-latest,fx-historical
spring.cache.caffeine.spec=maximumSize=1000,expireAfterWrite=1h
@Configuration
@EnableCaching
class FxApiConfig {
    @Bean
    FxApiClient fxApiClient(@Value("${fxapi.key}") String key) {
        return new FxApiClient(key);
    }
}

@Service
class ExchangeRateService {
    private final FxApiClient fx;

    ExchangeRateService(FxApiClient fx) { this.fx = fx; }

    @Cacheable("fx-latest")
    public RatesResponse latest(String base) {
        return fx.latest(base, null); // all currencies, one request per base and TTL
    }

    @Cacheable("fx-historical")
    public RatesResponse historical(LocalDate date, String base) {
        return fx.historical(date, base, null);
    }
}

@Service
class CurrencyConverter {
    private final ExchangeRateService rates;

    CurrencyConverter(ExchangeRateService rates) { this.rates = rates; }

    public BigDecimal convert(BigDecimal amount, String from, String to, int digits) {
        BigDecimal rate = rates.latest(from).data().get(to).value(); // goes through the cache proxy
        return amount.multiply(rate).setScale(digits, RoundingMode.HALF_EVEN);
    }
}

Two details matter here. First, the converter lives in a separate bean: a @Cacheable method called from inside its own class skips the proxy and hits the API every time. Second, @Cacheable evicts on expiry and has no “serve stale on error” mode – if you need that, keep a last-known-good copy as shown in caching exchange rates, and store lastUpdatedAt with each booked transaction.

Official SDK

fxapi’s official SDKs cover JavaScript, Python, PHP, Ruby, C# and Rust – there is no Java package. If you prefer generated code, run OpenAPI Generator against the OpenAPI spec; otherwise the roughly 100 lines above are all you need.

Next steps

The examples in this guide use fxapi, a FX rates API with a free plan of 300 requests a month – no credit card required.

Frequently asked questions

Which Java version do I need?
Java 17 or newer. The examples use java.net.http.HttpClient, records, switch expressions and Jackson 3, which itself needs Java 17 and is the Jackson version Spring Boot 4 ships.
Why does @Cacheable not cache my exchange rates?
Spring caching works through a proxy, so calling a @Cacheable method from another method in the same class bypasses the cache. Call it from a different bean, as the converter on this page does.
How do I set a TTL for @Cacheable?
@Cacheable itself has no expiry. Configure it in the cache provider, for example Caffeine with spring.cache.caffeine.spec=expireAfterWrite=1h, matching your plan’s update interval.
Should exchange rates be double or BigDecimal in Java?
BigDecimal. Jackson reads JSON numbers directly into BigDecimal fields, and setScale(digits, RoundingMode.HALF_EVEN) rounds the result to the currency’s minor units.
Is there an official Java SDK?
The official SDKs cover JavaScript, Python, PHP, Ruby, C# and Rust, not Java. The OpenAPI spec works with OpenAPI Generator if you prefer a generated client, or use the plain HttpClient code on this page.
Free plan · no credit card

Get your free exchange rate API key

300 requests a month, latest and historical rates, fluctuation and averages – free forever. Upgrade when you need faster updates or more requests.