The Currency Layer API provides real-time and historical exchange rates for 168 world currencies. This guide covers comprehensive integration with the Currency Layer API in Java applications.

Core API Client Implementation

Step 1: Basic API Client Setup

package com.example.currencylayer; import com.fasterxml.jackson.annotation.JsonProperty; import com.fasterxml.jackson.databind.ObjectMapper; import okhttp3.*; import java.io.IOException; import java.math.BigDecimal; import java.time.LocalDate; import java.time.format.DateTimeFormatter; import java.util.*; import java.util.concurrent.CompletableFuture; import java.util.concurrent.TimeUnit; // Core API response models public class CurrencyLayerModels { public static class ApiResponse { private boolean success; private ErrorInfo error; private Map<String, String> terms; private Map<String, String> privacy; // Getters and setters public boolean isSuccess() { return success; } public void setSuccess(boolean success) { this.success = success; } public ErrorInfo getError() { return error; } public void setError(ErrorInfo error) { this.error = error; } public Map<String, String> getTerms() { return terms; } public void setTerms(Map<String, String> terms) { this.terms = terms; } public Map<String, String> getPrivacy() { return privacy; } public void setPrivacy(Map<String, String> privacy) { this.privacy = privacy; } } public static class ErrorInfo { private int code; private String info; private String type; // Getters and setters public int getCode() { return code; } public void setCode(int code) { this.code = code; } public String getInfo() { return info; } public void setInfo(String info) { this.info = info; } public String getType() { return type; } public void setType(String type) { this.type = type; } @Override public String toString() { return String.format("Error %d: %s (%s)", code, info, type); } } public static class LiveRatesResponse extends ApiResponse { private String source; private Map<String, BigDecimal> quotes; private Long timestamp; // Getters and setters public String getSource() { return source; } public void setSource(String source) { this.source = source; } public Map<String, BigDecimal> getQuotes() { return quotes; } public void setQuotes(Map<String, BigDecimal> quotes) { this.quotes = quotes; } public Long getTimestamp() { return timestamp; } public void setTimestamp(Long timestamp) { this.timestamp = timestamp; } } public static class HistoricalRatesResponse extends ApiResponse { private String source; private LocalDate date; private Map<String, BigDecimal> quotes; private Long timestamp; // Getters and setters public String getSource() { return source; } public void setSource(String source) { this.source = source; } public LocalDate getDate() { return date; } public void setDate(LocalDate date) { this.date = date; } public Map<String, BigDecimal> getQuotes() { return quotes; } public void setQuotes(Map<String, BigDecimal> quotes) { this.quotes = quotes; } public Long getTimestamp() { return timestamp; } public void setTimestamp(Long timestamp) { this.timestamp = timestamp; } } public static class CurrencyConversionResponse extends ApiResponse { private String source; private Map<String, BigDecimal> quotes; private BigDecimal result; // Getters and setters public String getSource() { return source; } public void setSource(String source) { this.source = source; } public Map<String, BigDecimal> getQuotes() { return quotes; } public void setQuotes(Map<String, BigDecimal> quotes) { this.quotes = quotes; } public BigDecimal getResult() { return result; } public void setResult(BigDecimal result) { this.result = result; } } public static class TimeFrameResponse extends ApiResponse { private String source; private LocalDate startDate; private LocalDate endDate; private Map<LocalDate, Map<String, BigDecimal>> quotes; // Getters and setters public String getSource() { return source; } public void setSource(String source) { this.source = source; } public LocalDate getStartDate() { return startDate; } public void setStartDate(LocalDate startDate) { this.startDate = startDate; } public LocalDate getEndDate() { return endDate; } public void setEndDate(LocalDate endDate) { this.endDate = endDate; } public Map<LocalDate, Map<String, BigDecimal>> getQuotes() { return quotes; } public void setQuotes(Map<LocalDate, Map<String, BigDecimal>> quotes) { this.quotes = quotes; } } public static class SupportedCurrenciesResponse extends ApiResponse { private Map<String, CurrencyInfo> currencies; // Getters and setters public Map<String, CurrencyInfo> getCurrencies() { return currencies; } public void setCurrencies(Map<String, CurrencyInfo> currencies) { this.currencies = currencies; } } public static class CurrencyInfo { private String symbol; private String name; private String symbolNative; private int decimalDigits; private int rounding; private String code; private String namePlural; // Getters and setters public String getSymbol() { return symbol; } public void setSymbol(String symbol) { this.symbol = symbol; } public String getName() { return name; } public void setName(String name) { this.name = name; } public String getSymbolNative() { return symbolNative; } public void setSymbolNative(String symbolNative) { this.symbolNative = symbolNative; } public int getDecimalDigits() { return decimalDigits; } public void setDecimalDigits(int decimalDigits) { this.decimalDigits = decimalDigits; } public int getRounding() { return rounding; } public void setRounding(int rounding) { this.rounding = rounding; } public String getCode() { return code; } public void setCode(String code) { this.code = code; } public String getNamePlural() { return namePlural; } public void setNamePlural(String namePlural) { this.namePlural = namePlural; } } } // Core API client public class CurrencyLayerClient { private final String apiKey; private final String baseUrl; private final OkHttpClient httpClient; private final ObjectMapper objectMapper; private final boolean useHttps; public CurrencyLayerClient(String apiKey) { this(apiKey, "api.currencylayer.com", true); } public CurrencyLayerClient(String apiKey, String baseUrl, boolean useHttps) { this.apiKey = apiKey; this.baseUrl = baseUrl; this.useHttps = useHttps; this.objectMapper = new ObjectMapper(); this.httpClient = createHttpClient(); } private OkHttpClient createHttpClient() { return new OkHttpClient.Builder() .connectTimeout(30, TimeUnit.SECONDS) .readTimeout(30, TimeUnit.SECONDS) .writeTimeout(30, TimeUnit.SECONDS) .retryOnConnectionFailure(true) .build(); } private String buildUrl(String endpoint, Map<String, String> params) { String protocol = useHttps ? "https" : "http"; StringBuilder urlBuilder = new StringBuilder() .append(protocol).append("://").append(baseUrl).append("/").append(endpoint); Map<String, String> allParams = new HashMap<>(); allParams.put("access_key", apiKey); if (params != null) { allParams.putAll(params); } if (!allParams.isEmpty()) { urlBuilder.append("?"); allParams.forEach((key, value) -> urlBuilder.append(key).append("=").append(value).append("&")); // Remove trailing & urlBuilder.setLength(urlBuilder.length() - 1); } return urlBuilder.toString(); } private <T> T executeRequest(String url, Class<T> responseType) throws CurrencyLayerException { Request request = new Request.Builder() .url(url) .addHeader("User-Agent", "Java-CurrencyLayer-Client/1.0") .build(); try (Response response = httpClient.newCall(request).execute()) { if (!response.isSuccessful()) { throw new CurrencyLayerException("HTTP error: " + response.code() + " - " + response.message()); } ResponseBody body = response.body(); if (body == null) { throw new CurrencyLayerException("Empty response body"); } String responseBody = body.string(); T result = objectMapper.readValue(responseBody, responseType); // Check for API-level errors if (result instanceof CurrencyLayerModels.ApiResponse) { CurrencyLayerModels.ApiResponse apiResponse = (CurrencyLayerModels.ApiResponse) result; if (!apiResponse.isSuccess() && apiResponse.getError() != null) { throw new CurrencyLayerException(apiResponse.getError().toString()); } } return result; } catch (IOException e) { throw new CurrencyLayerException("Request failed: " + e.getMessage(), e); } } private <T> CompletableFuture<T> executeRequestAsync(String url, Class<T> responseType) { return CompletableFuture.supplyAsync(() -> { try { return executeRequest(url, responseType); } catch (CurrencyLayerException e) { throw new RuntimeException(e); } }); } }

Step 2: Core API Operations

// Continue CurrencyLayerClient class with API methods public class CurrencyLayerClient { // ... previous code ... // 1. Get real-time exchange rates public CurrencyLayerModels.LiveRatesResponse getLiveRates() throws CurrencyLayerException { return getLiveRates(null, null); } public CurrencyLayerModels.LiveRatesResponse getLiveRates(String source, List<String> currencies) throws CurrencyLayerException { Map<String, String> params = new HashMap<>(); if (source != null && !source.trim().isEmpty()) { params.put("source", source); } if (currencies != null && !currencies.isEmpty()) { params.put("currencies", String.join(",", currencies)); } String url = buildUrl("live", params); return executeRequest(url, CurrencyLayerModels.LiveRatesResponse.class); } public CompletableFuture<CurrencyLayerModels.LiveRatesResponse> getLiveRatesAsync() { return getLiveRatesAsync(null, null); } public CompletableFuture<CurrencyLayerModels.LiveRatesResponse> getLiveRatesAsync( String source, List<String> currencies) { Map<String, String> params = new HashMap<>(); if (source != null && !source.trim().isEmpty()) { params.put("source", source); } if (currencies != null && !currencies.isEmpty()) { params.put("currencies", String.join(",", currencies)); } String url = buildUrl("live", params); return executeRequestAsync(url, CurrencyLayerModels.LiveRatesResponse.class); } // 2. Get historical exchange rates public CurrencyLayerModels.HistoricalRatesResponse getHistoricalRates(LocalDate date) throws CurrencyLayerException { return getHistoricalRates(date, null, null); } public CurrencyLayerModels.HistoricalRatesResponse getHistoricalRates( LocalDate date, String source, List<String> currencies) throws CurrencyLayerException { Map<String, String> params = new HashMap<>(); params.put("date", date.format(DateTimeFormatter.ISO_DATE)); if (source != null && !source.trim().isEmpty()) { params.put("source", source); } if (currencies != null && !currencies.isEmpty()) { params.put("currencies", String.join(",", currencies)); } String url = buildUrl("historical", params); return executeRequest(url, CurrencyLayerModels.HistoricalRatesResponse.class); } // 3. Currency conversion public CurrencyLayerModels.CurrencyConversionResponse convertCurrency( String from, String to, BigDecimal amount) throws CurrencyLayerException { return convertCurrency(from, to, amount, null); } public CurrencyLayerModels.CurrencyConversionResponse convertCurrency( String from, String to, BigDecimal amount, LocalDate date) throws CurrencyLayerException { Map<String, String> params = new HashMap<>(); params.put("from", from); params.put("to", to); params.put("amount", amount.toString()); if (date != null) { params.put("date", date.format(DateTimeFormatter.ISO_DATE)); } String url = buildUrl("convert", params); return executeRequest(url, CurrencyLayerModels.CurrencyConversionResponse.class); } // 4. Time-frame data public CurrencyLayerModels.TimeFrameResponse getTimeFrameData( LocalDate startDate, LocalDate endDate) throws CurrencyLayerException { return getTimeFrameData(startDate, endDate, null, null); } public CurrencyLayerModels.TimeFrameResponse getTimeFrameData( LocalDate startDate, LocalDate endDate, String source, List<String> currencies) throws CurrencyLayerException { Map<String, String> params = new HashMap<>(); params.put("start_date", startDate.format(DateTimeFormatter.ISO_DATE)); params.put("end_date", endDate.format(DateTimeFormatter.ISO_DATE)); if (source != null && !source.trim().isEmpty()) { params.put("source", source); } if (currencies != null && !currencies.isEmpty()) { params.put("currencies", String.join(",", currencies)); } String url = buildUrl("timeframe", params); return executeRequest(url, CurrencyLayerModels.TimeFrameResponse.class); } // 5. Get supported currencies public CurrencyLayerModels.SupportedCurrenciesResponse getSupportedCurrencies() throws CurrencyLayerException { String url = buildUrl("list", null); return executeRequest(url, CurrencyLayerModels.SupportedCurrenciesResponse.class); } // 6. Get currency information public Map<String, CurrencyLayerModels.CurrencyInfo> getCurrencyInfo() throws CurrencyLayerException { CurrencyLayerModels.SupportedCurrenciesResponse response = getSupportedCurrencies(); return response.getCurrencies(); } } // Custom exception class CurrencyLayerException extends Exception { public CurrencyLayerException(String message) { super(message); } public CurrencyLayerException(String message, Throwable cause) { super(message, cause); } }

Advanced Features and Caching

Step 3: Caching and Rate Limiting

package com.example.currencylayer.advanced; import com.example.currencylayer.CurrencyLayerClient; import com.example.currencylayer.CurrencyLayerException; import com.example.currencylayer.CurrencyLayerModels; import java.math.BigDecimal; import java.time.LocalDate; import java.time.LocalDateTime; import java.util.*; import java.util.concurrent.*; public class AdvancedCurrencyService { private final CurrencyLayerClient client; private final Map<String, CachedRates> ratesCache; private final ScheduledExecutorService scheduler; private final long cacheTTLMinutes; public AdvancedCurrencyService(CurrencyLayerClient client) { this(client, 10); // 10 minutes TTL by default } public AdvancedCurrencyService(CurrencyLayerClient client, long cacheTTLMinutes) { this.client = client; this.cacheTTLMinutes = cacheTTLMinutes; this.ratesCache = new ConcurrentHashMap<>(); this.scheduler = Executors.newScheduledThreadPool(1); // Schedule cache cleanup scheduler.scheduleAtFixedRate(this::cleanupCache, 1, 1, TimeUnit.MINUTES); } private static class CachedRates { private final Map<String, BigDecimal> rates; private final LocalDateTime timestamp; private final String source; public CachedRates(Map<String, BigDecimal> rates, String source) { this.rates = rates; this.source = source; this.timestamp = LocalDateTime.now(); } public boolean isExpired(long ttlMinutes) { return LocalDateTime.now().isAfter(timestamp.plusMinutes(ttlMinutes)); } public Map<String, BigDecimal> getRates() { return rates; } public String getSource() { return source; } public LocalDateTime getTimestamp() { return timestamp; } } // Enhanced live rates with caching public Map<String, BigDecimal> getCachedLiveRates(String source, List<String> currencies) throws CurrencyLayerException { String cacheKey = buildCacheKey("live", source, currencies); CachedRates cached = ratesCache.get(cacheKey); if (cached != null && !cached.isExpired(cacheTTLMinutes)) { return new HashMap<>(cached.getRates()); } // Fetch fresh data CurrencyLayerModels.LiveRatesResponse response = client.getLiveRates(source, currencies); Map<String, BigDecimal> rates = response.getQuotes(); // Update cache ratesCache.put(cacheKey, new CachedRates(rates, source)); return rates; } // Bulk conversion with caching public Map<String, BigDecimal> bulkConvert(String fromCurrency, List<String> toCurrencies, BigDecimal amount) throws CurrencyLayerException { Map<String, BigDecimal> results = new HashMap<>(); Map<String, BigDecimal> rates = getCachedLiveRates(fromCurrency, toCurrencies); for (String toCurrency : toCurrencies) { String rateKey = fromCurrency + toCurrency; BigDecimal rate = rates.get(rateKey); if (rate != null) { results.put(toCurrency, amount.multiply(rate)); } } return results; } // Historical analysis public Map<String, List<BigDecimal>> getHistoricalTrend(String currency, LocalDate startDate, LocalDate endDate, String baseCurrency) throws CurrencyLayerException { CurrencyLayerModels.TimeFrameResponse response = client.getTimeFrameData(startDate, endDate, baseCurrency, Arrays.asList(currency)); Map<String, List<BigDecimal>> trends = new HashMap<>(); List<BigDecimal> rates = new ArrayList<>(); response.getQuotes().entrySet().stream() .sorted(Map.Entry.comparingByKey()) .forEach(entry -> { String rateKey = baseCurrency + currency; BigDecimal rate = entry.getValue().get(rateKey); if (rate != null) { rates.add(rate); } }); trends.put(currency, rates); return trends; } // Rate change calculation public Map<String, RateChange> calculateRateChanges(LocalDate fromDate, LocalDate toDate, List<String> currencies, String baseCurrency) throws CurrencyLayerException { CurrencyLayerModels.HistoricalRatesResponse fromRates = client.getHistoricalRates(fromDate, baseCurrency, currencies); CurrencyLayerModels.HistoricalRatesResponse toRates = client.getHistoricalRates(toDate, baseCurrency, currencies); Map<String, RateChange> changes = new HashMap<>(); for (String currency : currencies) { String rateKey = baseCurrency + currency; BigDecimal fromRate = fromRates.getQuotes().get(rateKey); BigDecimal toRate = toRates.getQuotes().get(rateKey); if (fromRate != null && toRate != null) { BigDecimal change = toRate.subtract(fromRate); BigDecimal percentChange = change.divide(fromRate, 6, BigDecimal.ROUND_HALF_UP) .multiply(BigDecimal.valueOf(100)); changes.put(currency, new RateChange(fromRate, toRate, change, percentChange)); } } return changes; } // Currency strength analysis public Map<String, CurrencyStrength> analyzeCurrencyStrength(List<String> currencies, int daysBack) throws CurrencyLayerException { LocalDate endDate = LocalDate.now(); LocalDate startDate = endDate.minusDays(daysBack); Map<String, CurrencyStrength> strengths = new HashMap<>(); for (String currency : currencies) { Map<String, List<BigDecimal>> trends = getHistoricalTrend(currency, startDate, endDate, "USD"); List<BigDecimal> rates = trends.get(currency); if (rates != null && rates.size() >= 2) { BigDecimal startRate = rates.get(0); BigDecimal endRate = rates.get(rates.size() - 1); BigDecimal change = endRate.subtract(startRate); BigDecimal percentChange = change.divide(startRate, 6, BigDecimal.ROUND_HALF_UP) .multiply(BigDecimal.valueOf(100)); BigDecimal volatility = calculateVolatility(rates); strengths.put(currency, new CurrencyStrength(currency, percentChange, volatility)); } } return strengths; } private BigDecimal calculateVolatility(List<BigDecimal> rates) { if (rates.size() < 2) return BigDecimal.ZERO; // Calculate standard deviation as volatility measure BigDecimal mean = rates.stream() .reduce(BigDecimal.ZERO, BigDecimal::add) .divide(BigDecimal.valueOf(rates.size()), 6, BigDecimal.ROUND_HALF_UP); BigDecimal variance = rates.stream() .map(rate -> rate.subtract(mean).pow(2)) .reduce(BigDecimal.ZERO, BigDecimal::add) .divide(BigDecimal.valueOf(rates.size()), 6, BigDecimal.ROUND_HALF_UP); return new BigDecimal(Math.sqrt(variance.doubleValue())); } private String buildCacheKey(String endpoint, String source, List<String> currencies) { StringBuilder key = new StringBuilder(endpoint); if (source != null) key.append(":").append(source); if (currencies != null) key.append(":").append(String.join(",", currencies)); return key.toString(); } private void cleanupCache() { ratesCache.entrySet().removeIf(entry -> entry.getValue().isExpired(cacheTTLMinutes)); } public void shutdown() { scheduler.shutdown(); try { if (!scheduler.awaitTermination(5, TimeUnit.SECONDS)) { scheduler.shutdownNow(); } } catch (InterruptedException e) { scheduler.shutdownNow(); Thread.currentThread().interrupt(); } } // Supporting data classes public static class RateChange { private final BigDecimal fromRate; private final BigDecimal toRate; private final BigDecimal absoluteChange; private final BigDecimal percentChange; public RateChange(BigDecimal fromRate, BigDecimal toRate, BigDecimal absoluteChange, BigDecimal percentChange) { this.fromRate = fromRate; this.toRate = toRate; this.absoluteChange = absoluteChange; this.percentChange = percentChange; } // Getters public BigDecimal getFromRate() { return fromRate; } public BigDecimal getToRate() { return toRate; } public BigDecimal getAbsoluteChange() { return absoluteChange; } public BigDecimal getPercentChange() { return percentChange; } } public static class CurrencyStrength { private final String currency; private final BigDecimal performance; private final BigDecimal volatility; public CurrencyStrength(String currency, BigDecimal performance, BigDecimal volatility) { this.currency = currency; this.performance = performance; this.volatility = volatility; } // Getters public String getCurrency() { return currency; } public BigDecimal getPerformance() { return performance; } public BigDecimal getVolatility() { return volatility; } public BigDecimal getRiskAdjustedReturn() { if (volatility.compareTo(BigDecimal.ZERO) == 0) { return BigDecimal.ZERO; } return performance.divide(volatility, 6, BigDecimal.ROUND_HALF_UP); } } }

Spring Boot Integration

Step 4: Spring Boot Configuration and Service

package com.example.currencylayer.spring; import com.example.currencylayer.CurrencyLayerClient; import com.example.currencylayer.CurrencyLayerException; import com.example.currencylayer.CurrencyLayerModels; import com.example.currencylayer.advanced.AdvancedCurrencyService; import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.scheduling.annotation.Async; import org.springframework.scheduling.annotation.EnableAsync; import org.springframework.scheduling.annotation.Scheduled; import org.springframework.stereotype.Service; import java.math.BigDecimal; import java.time.LocalDate; import java.util.*; import java.util.concurrent.CompletableFuture; @Configuration @EnableAsync public class CurrencyLayerConfig { @Bean @ConfigurationProperties(prefix = "currencylayer") public CurrencyLayerProperties currencyLayerProperties() { return new CurrencyLayerProperties(); } @Bean public CurrencyLayerClient currencyLayerClient(CurrencyLayerProperties properties) { return new CurrencyLayerClient( properties.getApiKey(), properties.getBaseUrl(), properties.isUseHttps() ); } @Bean public AdvancedCurrencyService advancedCurrencyService(CurrencyLayerClient client) { return new AdvancedCurrencyService(client, 15); // 15 minutes cache TTL } } @ConfigurationProperties(prefix = "currencylayer") class CurrencyLayerProperties { private String apiKey; private String baseUrl = "api.currencylayer.com"; private boolean useHttps = true; private long cacheTtlMinutes = 15; // Getters and setters public String getApiKey() { return apiKey; } public void setApiKey(String apiKey) { this.apiKey = apiKey; } public String getBaseUrl() { return baseUrl; } public void setBaseUrl(String baseUrl) { this.baseUrl = baseUrl; } public boolean isUseHttps() { return useHttps; } public void setUseHttps(boolean useHttps) { this.useHttps = useHttps; } public long getCacheTtlMinutes() { return cacheTtlMinutes; } public void setCacheTtlMinutes(long cacheTtlMinutes) { this.cacheTtlMinutes = cacheTtlMinutes; } } @Service public class CurrencyLayerService { private final CurrencyLayerClient client; private final AdvancedCurrencyService advancedService; private final Map<String, CurrencyLayerModels.LiveRatesResponse> lastRates = new HashMap<>(); public CurrencyLayerService(CurrencyLayerClient client, AdvancedCurrencyService advancedService) { this.client = client; this.advancedService = advancedService; } // Scheduled task to refresh rates periodically @Scheduled(fixedRate = 600000) // Every 10 minutes public void refreshLiveRates() { try { CurrencyLayerModels.LiveRatesResponse rates = client.getLiveRates(); lastRates.put("USD", rates); // Cache USD-based rates System.out.println("Refreshed currency rates at: " + new Date()); } catch (CurrencyLayerException e) { System.err.println("Failed to refresh rates: " + e.getMessage()); } } public CurrencyLayerModels.LiveRatesResponse getCurrentRates() throws CurrencyLayerException { if (lastRates.containsKey("USD")) { return lastRates.get("USD"); } return client.getLiveRates(); } @Async public CompletableFuture<CurrencyLayerModels.LiveRatesResponse> getCurrentRatesAsync() { return CompletableFuture.supplyAsync(() -> { try { return getCurrentRates(); } catch (CurrencyLayerException e) { throw new RuntimeException(e); } }); } public BigDecimal convertCurrency(String from, String to, BigDecimal amount) throws CurrencyLayerException { CurrencyLayerModels.CurrencyConversionResponse response = client.convertCurrency(from, to, amount); return response.getResult(); } @Async public CompletableFuture<BigDecimal> convertCurrencyAsync(String from, String to, BigDecimal amount) { return CompletableFuture.supplyAsync(() -> { try { return convertCurrency(from, to, amount); } catch (CurrencyLayerException e) { throw new RuntimeException(e); } }); } public Map<String, BigDecimal> getRateHistory(String currency, LocalDate start, LocalDate end) throws CurrencyLayerException { CurrencyLayerModels.TimeFrameResponse response = client.getTimeFrameData(start, end, "USD", Arrays.asList(currency)); Map<String, BigDecimal> history = new TreeMap<>(); response.getQuotes().forEach((date, rates) -> { String rateKey = "USD" + currency; BigDecimal rate = rates.get(rateKey); if (rate != null) { history.put(date.toString(), rate); } }); return history; } public Map<String, CurrencyLayerModels.CurrencyInfo> getAvailableCurrencies() throws CurrencyLayerException { return client.getCurrencyInfo(); } // Business logic: Detect arbitrage opportunities public List<ArbitrageOpportunity> findArbitrageOpportunities(List<String> currencies) throws CurrencyLayerException { List<ArbitrageOpportunity> opportunities = new ArrayList<>(); Map<String, BigDecimal> rates = advancedService.getCachedLiveRates("USD", currencies); for (String fromCurrency : currencies) { for (String toCurrency : currencies) { if (!fromCurrency.equals(toCurrency)) { String directRateKey = fromCurrency + toCurrency; BigDecimal directRate = rates.get(directRateKey); if (directRate != null) { // Check triangular arbitrage for (String viaCurrency : currencies) { if (!viaCurrency.equals(fromCurrency) && !viaCurrency.equals(toCurrency)) { BigDecimal arbitrageProfit = calculateTriangularArbitrage( fromCurrency, toCurrency, viaCurrency, rates); if (arbitrageProfit.compareTo(BigDecimal.valueOf(0.01)) > 0) { opportunities.add(new ArbitrageOpportunity( fromCurrency, toCurrency, viaCurrency, arbitrageProfit)); } } } } } } } opportunities.sort(Comparator.comparing(ArbitrageOpportunity::getProfit).reversed()); return opportunities; } private BigDecimal calculateTriangularArbitrage(String from, String to, String via, Map<String, BigDecimal> rates) { try { BigDecimal rate1 = rates.get(from + via); // from -> via BigDecimal rate2 = rates.get(via + to); // via -> to BigDecimal rate3 = rates.get(from + to); // from -> to (direct) if (rate1 != null && rate2 != null && rate3 != null) { BigDecimal triangularRate = rate1.multiply(rate2); BigDecimal difference = triangularRate.subtract(rate3); return difference.divide(rate3, 6, BigDecimal.ROUND_HALF_UP) .multiply(BigDecimal.valueOf(100)); // as percentage } } catch (Exception e) { // Ignore calculation errors } return BigDecimal.ZERO; } public static class ArbitrageOpportunity { private final String fromCurrency; private final String toCurrency; private final String viaCurrency; private final BigDecimal profit; public ArbitrageOpportunity(String fromCurrency, String toCurrency, String viaCurrency, BigDecimal profit) { this.fromCurrency = fromCurrency; this.toCurrency = toCurrency; this.viaCurrency = viaCurrency; this.profit = profit; } // Getters public String getFromCurrency() { return fromCurrency; } public String getToCurrency() { return toCurrency; } public String getViaCurrency() { return viaCurrency; } public BigDecimal getProfit() { return profit; } @Override public String toString() { return String.format("Arbitrage: %s -> %s -> %s | Profit: %.2f%%", fromCurrency, viaCurrency, toCurrency, profit); } } }

REST API Controller

Step 5: Spring REST Controller

package com.example.currencylayer.controller; import com.example.currencylayer.CurrencyLayerException; import com.example.currencylayer.CurrencyLayerModels; import com.example.currencylayer.spring.CurrencyLayerService; import org.springframework.format.annotation.DateTimeFormat; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.*; import java.math.BigDecimal; import java.time.LocalDate; import java.util.List; import java.util.Map; import java.util.concurrent.CompletableFuture; @RestController @RequestMapping("/api/currency") @CrossOrigin(origins = "*") public class CurrencyLayerController { private final CurrencyLayerService currencyService; public CurrencyLayerController(CurrencyLayerService currencyService) { this.currencyService = currencyService; } @GetMapping("/rates/live") public ResponseEntity<?> getLiveRates( @RequestParam(required = false) String source, @RequestParam(required = false) List<String> currencies) { try { CurrencyLayerModels.LiveRatesResponse rates = currencyService.getCurrentRates(); return ResponseEntity.ok(rates); } catch (CurrencyLayerException e) { return ResponseEntity.badRequest().body( Map.of("error", e.getMessage())); } } @GetMapping("/rates/historical") public ResponseEntity<?> getHistoricalRates( @RequestParam @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate date, @RequestParam(required = false) String source, @RequestParam(required = false) List<String> currencies) { try { CurrencyLayerModels.HistoricalRatesResponse rates = currencyService.getHistoricalRates(date, source, currencies); return ResponseEntity.ok(rates); } catch (CurrencyLayerException e) { return ResponseEntity.badRequest().body( Map.of("error", e.getMessage())); } } @GetMapping("/convert") public ResponseEntity<?> convertCurrency( @RequestParam String from, @RequestParam String to, @RequestParam BigDecimal amount, @RequestParam(required = false) @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate date) { try { BigDecimal result; if (date != null) { result = currencyService.convertCurrency(from, to, amount, date); } else { result = currencyService.convertCurrency(from, to, amount); } return ResponseEntity.ok(Map.of( "from", from, "to", to, "amount", amount, "result", result )); } catch (CurrencyLayerException e) { return ResponseEntity.badRequest().body( Map.of("error", e.getMessage())); } } @GetMapping("/currencies") public ResponseEntity<?> getSupportedCurrencies() { try { Map<String, CurrencyLayerModels.CurrencyInfo> currencies = currencyService.getAvailableCurrencies(); return ResponseEntity.ok(currencies); } catch (CurrencyLayerException e) { return ResponseEntity.badRequest().body( Map.of("error", e.getMessage())); } } @GetMapping("/analysis/history") public ResponseEntity<?> getRateHistory( @RequestParam String currency, @RequestParam @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate start, @RequestParam @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate end) { try { Map<String, BigDecimal> history = currencyService.getRateHistory(currency, start, end); return ResponseEntity.ok(history); } catch (CurrencyLayerException e) { return ResponseEntity.badRequest().body( Map.of("error", e.getMessage())); } } @GetMapping("/analysis/arbitrage") public ResponseEntity<?> findArbitrageOpportunities( @RequestParam(required = false) List<String> currencies) { try { List<CurrencyLayerService.ArbitrageOpportunity> opportunities = currencyService.findArbitrageOpportunities(currencies); return ResponseEntity.ok(opportunities); } catch (CurrencyLayerException e) { return ResponseEntity.badRequest().body( Map.of("error", e.getMessage())); } } @GetMapping("/analysis/strength") public ResponseEntity<?> analyzeCurrencyStrength( @RequestParam List<String> currencies, @RequestParam(defaultValue = "30") int days) { try { Map<String, AdvancedCurrencyService.CurrencyStrength> strengths = currencyService.analyzeCurrencyStrength(currencies, days); return ResponseEntity.ok(strengths); } catch (CurrencyLayerException e) { return ResponseEntity.badRequest().body( Map.of("error", e.getMessage())); } } // Async endpoints @GetMapping("/rates/live/async") public CompletableFuture<ResponseEntity<?>> getLiveRatesAsync() { return currencyService.getCurrentRatesAsync() .thenApply(ResponseEntity::ok) .exceptionally(e -> ResponseEntity.badRequest() .body(Map.of("error", e.getMessage()))); } @GetMapping("/convert/async") public CompletableFuture<ResponseEntity<?>> convertCurrencyAsync( @RequestParam String from, @RequestParam String to, @RequestParam BigDecimal amount) { return currencyService.convertCurrencyAsync(from, to, amount) .thenApply(result -> ResponseEntity.ok(Map.of( "from", from, "to", to, "amount", amount, "result", result ))) .exceptionally(e -> ResponseEntity.badRequest() .body(Map.of("error", e.getMessage()))); } }

Testing and Error Handling

Step 6: Comprehensive Testing

package com.example.currencylayer.test; import com.example.currencylayer.CurrencyLayerClient; import com.example.currencylayer.CurrencyLayerException; import com.example.currencylayer.CurrencyLayerModels; import com.example.currencylayer.advanced.AdvancedCurrencyService; import okhttp3.mockwebserver.MockResponse; import okhttp3.mockwebserver.MockWebServer; import okhttp3.mockwebserver.RecordedRequest; import org.junit.jupiter.api.AfterEach; import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.Test; import java.io.IOException; import java.math.BigDecimal; import java.time.LocalDate; import java.util.Arrays; import java.util.List; import java.util.Map; import static org.junit.jupiter.api.Assertions.*; class CurrencyLayerClientTest { private MockWebServer mockWebServer; private CurrencyLayerClient client; @BeforeEach void setUp() throws IOException { mockWebServer = new MockWebServer(); mockWebServer.start(); client = new CurrencyLayerClient( "test-api-key", mockWebServer.getHostName() + ":" + mockWebServer.getPort(), false ); } @AfterEach void tearDown() throws IOException { mockWebServer.shutdown(); } @Test void testLiveRatesSuccess() throws Exception { String jsonResponse = """ { "success": true, "terms": "https://currencylayer.com/terms", "privacy": "https://currencylayer.com/privacy", "timestamp": 1634577963, "source": "USD", "quotes": { "USDEUR": 0.86115, "USDGBP": 0.73016, "USDJPY": 113.25 } } """; mockWebServer.enqueue(new MockResponse() .setBody(jsonResponse) .addHeader("Content-Type", "application/json")); CurrencyLayerModels.LiveRatesResponse response = client.getLiveRates(); assertTrue(response.isSuccess()); assertEquals("USD", response.getSource()); assertEquals(3, response.getQuotes().size()); assertEquals(new BigDecimal("0.86115"), response.getQuotes().get("USDEUR")); // Verify request RecordedRequest request = mockWebServer.takeRequest(); assertEquals("/live?access_key=test-api-key", request.getPath()); } @Test void testLiveRatesWithParameters() throws Exception { String jsonResponse = """ { "success": true, "source": "EUR", "quotes": { "EURGBP": 0.84802, "EURUSD": 1.16115 } } """; mockWebServer.enqueue(new MockResponse().setBody(jsonResponse)); List<String> currencies = Arrays.asList("GBP", "USD"); CurrencyLayerModels.LiveRatesResponse response = client.getLiveRates("EUR", currencies); assertEquals("EUR", response.getSource()); assertEquals(2, response.getQuotes().size()); RecordedRequest request = mockWebServer.takeRequest(); assertTrue(request.getPath().contains("source=EUR")); assertTrue(request.getPath().contains("currencies=GBP,USD")); } @Test void testApiError() { String jsonResponse = """ { "success": false, "error": { "code": 101, "type": "invalid_access_key", "info": "You have not supplied a valid API Access Key." } } """; mockWebServer.enqueue(new MockResponse().setBody(jsonResponse)); CurrencyLayerException exception = assertThrows(CurrencyLayerException.class, () -> client.getLiveRates()); assertTrue(exception.getMessage().contains("invalid_access_key")); } @Test void testHistoricalRates() throws Exception { String jsonResponse = """ { "success": true, "historical": true, "date": "2023-10-01", "source": "USD", "quotes": { "USDEUR": 0.85115, "USDGBP": 0.72016 } } """; mockWebServer.enqueue(new MockResponse().setBody(jsonResponse)); LocalDate date = LocalDate.of(2023, 10, 1); CurrencyLayerModels.HistoricalRatesResponse response = client.getHistoricalRates(date); assertTrue(response.isSuccess()); assertEquals(date, response.getDate()); assertEquals(2, response.getQuotes().size()); RecordedRequest request = mockWebServer.takeRequest(); assertTrue(request.getPath().contains("date=2023-10-01")); } @Test void testCurrencyConversion() throws Exception { String jsonResponse = """ { "success": true, "query": { "from": "USD", "to": "EUR", "amount": 100 }, "info": { "timestamp": 1634577963, "quote": 0.86115 }, "result": 86.115 } """; mockWebServer.enqueue(new MockResponse().setBody(jsonResponse)); CurrencyLayerModels.CurrencyConversionResponse response = client.convertCurrency("USD", "EUR", new BigDecimal("100")); assertTrue(response.isSuccess()); assertEquals(new BigDecimal("86.115"), response.getResult()); RecordedRequest request = mockWebServer.takeRequest(); assertTrue(request.getPath().contains("from=USD")); assertTrue(request.getPath().contains("to=EUR")); assertTrue(request.getPath().contains("amount=100")); } @Test void testSupportedCurrencies() throws Exception { String jsonResponse = """ { "success": true, "currencies": { "USD": "United States Dollar", "EUR": "Euro", "GBP": "British Pound Sterling" } } """; mockWebServer.enqueue(new MockResponse().setBody(jsonResponse)); CurrencyLayerModels.SupportedCurrenciesResponse response = client.getSupportedCurrencies(); assertTrue(response.isSuccess()); assertEquals(3, response.getCurrencies().size()); assertEquals("United States Dollar", response.getCurrencies().get("USD").getName()); } } // Integration test with caching class AdvancedCurrencyServiceTest { private MockWebServer mockWebServer; private CurrencyLayerClient client; private AdvancedCurrencyService advancedService; @BeforeEach void setUp() throws IOException { mockWebServer = new MockWebServer(); mockWebServer.start(); client = new CurrencyLayerClient( "test-key", mockWebServer.getHostName() + ":" + mockWebServer.getPort(), false ); advancedService = new AdvancedCurrencyService(client, 1); // 1 minute TTL for testing } @Test void testCachedRates() throws Exception { String jsonResponse = """ { "success": true, "source": "USD", "quotes": { "USDEUR": 0.86115, "USDGBP": 0.73016 } } """; // First request - should call API mockWebServer.enqueue(new MockResponse().setBody(jsonResponse)); List<String> currencies = Arrays.asList("EUR", "GBP"); Map<String, BigDecimal> rates1 = advancedService.getCachedLiveRates("USD", currencies); assertEquals(2, rates1.size()); assertEquals(1, mockWebServer.getRequestCount()); // Second request - should use cache Map<String, BigDecimal> rates2 = advancedService.getCachedLiveRates("USD", currencies); assertEquals(rates1, rates2); assertEquals(1, mockWebServer.getRequestCount()); // Still 1, cache was used } @Test void testBulkConversion() throws Exception { String jsonResponse = """ { "success": true, "source": "USD", "quotes": { "USDEUR": 0.86115, "USDGBP": 0.73016, "USDJPY": 113.25 } } """; mockWebServer.enqueue(new MockResponse().setBody(jsonResponse)); List<String> toCurrencies = Arrays.asList("EUR", "GBP", "JPY"); Map<String, BigDecimal> results = advancedService.bulkConvert("USD", toCurrencies, new BigDecimal("100")); assertEquals(3, results.size()); assertEquals(new BigDecimal("86.115"), results.get("EUR")); // 100 * 0.86115 assertEquals(new BigDecimal("73.016"), results.get("GBP")); // 100 * 0.73016 } }

Configuration and Deployment

Step 7: Application Configuration

application.yml:

currencylayer: api-key: ${CURRENCY_LAYER_API_KEY:your_api_key_here} base-url: api.currencylayer.com use-https: true cache-ttl-minutes: 15 server: port: 8080 spring: application: name: currency-service logging: level: com.example.currencylayer: DEBUG management: endpoints: web: exposure: include: health,metrics,info endpoint: health: show-details: always

Maven Dependencies (pom.xml):

<?xml version="1.0" encoding="UTF-8"?> <project> <dependencies> <!-- Spring Boot --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-actuator</artifactId> </dependency> <!-- HTTP Client --> <dependency> <groupId>com.squareup.okhttp3</groupId> <artifactId>okhttp</artifactId> <version>4.11.0</version> </dependency> <!-- JSON Processing --> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> </dependency> <dependency> <groupId>com.fasterxml.jackson.datatype</groupId> <artifactId>jackson-datatype-jsr310</artifactId> </dependency> <!-- Testing --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> <dependency> <groupId>com.squareup.okhttp3</groupId> <artifactId>mockwebserver</artifactId> <version>4.11.0</version> <scope>test</scope> </dependency> </dependencies> </project>

Key Features and Benefits

Core Features:

1. Real-time Exchange Rates: Get current rates for 168 currencies
2. Historical Data: Access historical exchange rates
3. Currency Conversion: Convert between any supported currencies
4. Time-frame Analysis: Analyze rates over custom time periods
5. Supported Currencies: Get detailed information about all available currencies

Advanced Features:

1. Intelligent Caching: Reduce API calls with configurable TTL
2. Rate Limiting: Built-in respect for API rate limits
3. Bulk Operations: Efficient processing of multiple currencies
4. Arbitrage Detection: Identify potential arbitrage opportunities
5. Currency Strength Analysis: Analyze currency performance and volatility

Integration Benefits:

1. Spring Boot Ready: Seamless Spring integration with auto-configuration
2. REST API: Full-featured REST controller for easy consumption
3. Async Support: Non-blocking operations for better performance
4. Comprehensive Testing: Unit and integration test coverage
5. Production Ready: Error handling, logging, and monitoring

This comprehensive Currency Layer API integration provides a robust foundation for building financial applications, trading systems, currency converters, and analytical tools with real-time and historical exchange rate data.