Skip to main content

OpenExchangeAPI Overview

A comprehensive guide to integrating currency exchange data into your applications

What is OpenExchangeAPI?

OpenExchangeAPI is a global-first SaaS platform offering fast, reliable foreign exchange data through a simple and scalable API. Our product powers financial applications, global pricing engines, dashboards, and cross-border platforms with real-time and historical currency data.

Unlike outdated or over-complicated FX services, we focus on performance, usability, and developer experience. Integration is effortless. Data is accurate. Pricing is clear. Documentation is simple. You get the exchange data you needβ€”fast.

Fast & Reliable

Our API delivers exchange rate data with minimal latency. Live rates are updated every 60 seconds, ensuring your applications always have the most current information.

Developer-Friendly

Clean JSON responses, comprehensive documentation, and intuitive endpoints make integration straightforward for developers of all experience levels.

Key Features

Live Exchange Rates

Updated every 60 seconds for all major and minor currency pairs

Historical Rates

Access past exchange data for analysis and reporting

Currency Conversion

Convert amounts between currencies with precision

Modern Dashboard

Manage keys, view stats, and access docs in one place

Who It's For

Developers

Building applications that need currency data

SaaS Companies

Integrating FX data into their platforms

Fintech Products

Powering financial applications

E-commerce Systems

Displaying prices in multiple currencies

Authentication

Unlock higher limits and track usage with API key authentication. Follow the steps below to get started.

API Key Authentication

Our API supports public and authenticated access.

API keys are optional but recommended for production use. They help you track usage and manage rate limits effectively.

Without an API key, you're limited to 100 requests per day per IP address.

To unlock higher limits and track usage, include your API key as a query parameter or a Bearer token in the request header.

Example Request with API Key

https://api.openexchangeapi.com/v1/latest?apiKey=YOUR_API_KEY&base=USD

Important

Keep your API key secure and never expose it in client-side code. If you believe your key has been compromised, you can regenerate it from your dashboard.

How to Get Your API Key

  1. Sign up for an OpenExchangeAPI account
  2. Navigate to the API Keys section in your dashboard
  3. Generate a new API key for your project
  4. Copy the key and include it in your API requests

HTTPS Required

All API requests must be made over HTTPS. Requests over plain HTTP will fail. This ensures your API key and data remain secure during transmission.

API Key Management

You can create multiple API keys for different projects, monitor usage for each key, and revoke keys that are no longer needed through your dashboard.

Authentication Errors

Error Code Description Solution
401 Invalid API key Check that you're using a valid API key
403 Access denied Verify your subscription allows access to this endpoint
429 Rate limit exceeded Reduce request frequency or upgrade your plan

API Endpoints

Explore our endpoints for accessing currency exchange data

Live Rates

GET /v1/latest

Get the latest exchange rates for all supported currencies. The response includes the base currency and a list of rates for each currency.

Parameters

Parameter Required Where Description
apiKey No Query Your API key
base No Query Base currency (default: USD)

Live Rates (High Precision)

GET /v1/latest-precise

Get the latest exchange rates for all supported currencies. The response includes the base currency and a list of rates for each currency.

Parameters

Parameter Required Where Description
apiKey No Query Your API key
base No Query Base currency (default: USD)

Note

Rates are updated every 60 seconds. The latest rates are available for all supported currencies. You can specify the base currency and the target currencies in the request.

Historical Data

GET /v1/rates?date=2023-01-01

Get historical exchange rates for a specific date. The response includes the base currency and a list of rates for each currency. You can specify the date parameter in the request to get rates for that date.

Parameters

Parameter Required Where Description
apiKey No Query Your API key
date Yes Query Date in YYYY-MM-DD format
base No Query Base currency (default: USD)

Historical Data (High Precision)

GET /v1/rates-precise

High precision historical data for a specific date. The response includes the base currency and a list of rates for each currency. You can specify the date parameter in the request to get rates for that date.

Parameters

Parameter Required Where Description
apiKey No Query Your API key
date Yes Query Date in YYYY-MM-DD format
base No Query Base currency (default: USD)

Note

Rates are updated every 60 seconds. The latest rates are available for all supported currencies. You can specify the base currency and the target currencies in the request.

Currency Conversion

GET /v1/convert?from=USD&to=EUR&amount=100

Convert currency from one denomination to another.
The response includes the base currency, target currency, and the converted amount.

The response will include the converted amount and the exchange rate used for the conversion.

Parameters

Parameter Required Where Description
apiKey No Query Your API key
from Yes Query Currency code you want to convert from (e.g., USD)
to Yes Query Currency code you want to convert to (e.g., EUR)
amount Yes Query Amount to convert

Currency Conversion (High Precision)

GET /v1/convert-precise?from=USD&to=EUR&amount=100

High precision currency conversion for a specific amount. The response includes the base currency, target currency, and the converted amount.

Parameters

Parameter Required Where Description
apiKey No Query Your API key
from Yes Query Currency code you want to convert from (e.g., USD)
to Yes Query Currency code you want to convert to (e.g., EUR)
amount Yes Query Amount to convert

Note

Rates are updated every 60 seconds. The latest rates are available for all supported currencies. You can specify the base currency and the target currencies in the request.

Code Examples

Integrate OpenExchangeAPI into your applications with these ready-to-use code snippets

Rates (Javascript)


const ExchangeRates = (() => {
  let cache = null;
  let lastFetch = 0;
  const TTL = 5 * 60 * 1000// 5 minutes

  async function getRates() {
    const now = Date.now();
    if (cache && now - lastFetch < TTL) return cache;

    const res = await fetch('https://api.openexchangeapi.com/v1/latest'{
      headers: { Authorization: 'Bearer YOUR_API_KEY' }
    });

    const data = await res.json();
    cache = data.rates;
    lastFetch = now;
    return cache;
  }

  return { getRates };
})();


const userCurrency = new Intl.NumberFormat(navigator.language, {   style: 'currency',   currency: 'USD' }).resolvedOptions().currency;

async function getConvertedAmount(priceUsd) {   const rates = await ExchangeRates.getRates();   if (!rates || !rates[userCurrency]) return null;   const converted = priceUsd * rates[userCurrency];   return new Intl.NumberFormat(navigator.language, {     style: 'currency',     currency: userCurrency   }).format(converted); }

Note

This example demonstrates how to fetch the latest exchange rates using the Open Exchange API.

Error Codes

Understanding and handling API errors effectively

Error Response Format

The API relies on HTTP status codes to indicate the success or failure of a request. Each response will include a status code, and in case of an error, a detailed error message.

When an error occurs, the API returns a JSON response with details about what went wrong. All error responses include an error code, a message, and sometimes additional information to help you troubleshoot.

{
  "error": {
    "code": 404,
    "message": "Not found",
    "details": "The requested resource does not exist."
  }
}

Best Practice

Always check for error responses in your code and handle them gracefully. This improves user experience and makes debugging easier.

HTTP Status Codes

Status Code Description Common Causes
200 OK The request was successful N/A - This is a success response
400 Bad Request The request was invalid
  • Missing required parameters
  • Invalid parameter format
  • Invalid currency code
401 Unauthorized Authentication failed
  • Missing API key
  • Invalid API key
  • Expired API key
403 Forbidden Access denied
  • Subscription doesn't allow access to this endpoint
  • Account suspended
404 Not Found Resource not found
  • Invalid endpoint
  • Historical data not available for requested date
429 Too Many Requests Rate limit exceeded
  • Too many requests in a given time period
  • Monthly quota exceeded
500 Internal Server Error Server error
  • Unexpected server error
  • Please contact support if this persists
503 Service Unavailable Service temporarily unavailable
  • Server maintenance
  • Temporary overload
  • Check status page for updates

Common Error Codes

400

Bad Request - The request was invalid or malformed.

401

Unauthorized - No API key was provided in the request.

403

Forbidden - The API key is invalid or does not have access to the requested resource.

404

Not Found - The requested resource does not exist.

429

Too Many Requests - You have exceeded the rate limit.

Error Handling Best Practices

Implement Retry Logic

For 429 and 5xx errors, implement exponential backoff retry logic to handle temporary issues.

Validate Input

Validate currency codes and other parameters before making API calls to avoid 400 errors.

Monitor Rate Limits

Track your API usage and implement rate limiting on your side to avoid 429 errors.

Log Errors

Log all API errors with timestamps and request details for troubleshooting.

Graceful Degradation

Design your application to handle API unavailability gracefully, possibly using cached data.

Need Help?

If you're experiencing persistent errors or need help troubleshooting an issue, our support team is here to help. Contact us at [email protected] or check our status page for any ongoing service disruptions.

Rate Limits

Understanding and managing your API usage effectively

Overview

To ensure fair usage and maintain service quality for all users, OpenExchangeAPI implements rate limiting on API requests. Rate limits vary by subscription plan and are applied on a per-API key basis.

Rate Limit Headers

All API responses include headers that provide information about your current rate limit status. Use these headers to monitor your usage and implement appropriate throttling in your application.

Header Description Example
X-RateLimit-Category The rate limit category the request falls under (e.g. rates) rates
X-RateLimit-Day Number of requests used in the current day 4815
X-RateLimit-Hour Number of requests used in the current hour 999
X-RateLimit-Minute Number of requests used in the current minute 59

Rate Limiting

Global Request Limits

All API requests are rate-limited based on your API key or IP address. Limits are enforced per minute, hour, and day. These limits prevent abuse and ensure fair use across all clients.

Example: 100 requests per minute, 1,000 per hour, 5,000 per day

Free Access Limits

If no API key is provided, your access is considered anonymous and limited to 100 requests per day, per IP address. To raise limits and access more features, use an API key.

Example: 100 requests/day without an API key

Rate Limit Headers

Every response includes headers that indicate your current request usage for the day, hour, and minute. These values help you monitor and adapt your application's usage.

  • X-RateLimit-Category: The group of rate limits applied to the request
  • X-RateLimit-Day: Requests used today
  • X-RateLimit-Hour: Requests used this hour
  • X-RateLimit-Minute: Requests used this minute

Best Practices

  • Implement caching to reduce the number of API calls
  • Monitor your usage with the rate limit headers
  • Implement exponential backoff for retry logic
  • Request only the data you need (use the symbols parameter)
  • Upgrade your plan if you consistently hit rate limits

Need Higher Limits?

If your application requires higher rate limits than our standard plans offer, please contact our sales team to discuss custom Enterprise solutions. We can tailor a plan to meet your specific needs.

Supported Currencies

A comprehensive list of all supported currencies and their codes

Supported Currencies

OpenExchangeAPI supports 170+ currencies worldwide. Here are some of the most commonly used currencies:

USD
US Dollar
EUR
Euro
GBP
British Pound
JPY
Japanese Yen
CAD
Canadian Dollar
AUD
Australian Dollar
CHF
Swiss Franc
CNY
Chinese Yuan

SDKs

Explore our official SDKs for easy integration with the OpenExchangeAPI

Changelog

Stay up to date with the latest improvements and updates to the OpenExchangeAPI

API Version History

Current: v1.0.1

We're constantly improving our API to provide you with the best possible experience. Below is a history of our API versions and the changes introduced in each update.

All API versions are backward compatible. We recommend using the latest version to access all features.

Version 1.0.1

Released on November 10, 2023

Current

Bug Fixes

  • Fixed minor issue with currency rounding in convert endpoint
  • Corrected fallback mechanism for unsupported currency codes

Performance

  • Reduced cold start latency on serverless environments
  • Minor backend caching improvements

Version 1.0.0

Released on October 10, 2023

Launch

Highlights

  • Public release of OpenExchangeAPI
  • Core endpoints: /latest, /historical, /convert
  • API key auth with public/free tier
  • Support for 170+ currencies

Version 0.9.2

Released on September 20, 2023

Changes

  • Improved response schema for /convert endpoint
  • Rate limit headers added to all responses

Version 0.8.7

Released on August 25, 2023

Beta

Beta Release

  • Initial prototype released to selected early testers
  • Endpoints: /latest, /historical
  • Initial exchange rate data backend and cron updates

Upcoming Features

Webhooks for Rate Alerts

Set up notifications when exchange rates cross specified thresholds.

Batch Conversion Endpoint

Convert multiple currency pairs in a single API request.

GraphQL API

A flexible GraphQL interface for more efficient data fetching.

Official Client Libraries

Official SDK packages for popular programming languages.

Have a feature request? We'd love to hear your ideas! Contact our team with your suggestions.

API Deprecation Policy

At OpenExchangeAPI, we strive to maintain backward compatibility and provide a stable API. Our deprecation policy ensures that you have ample time to update your integrations when changes are necessary.

Minimum 6-Month Notice

We will provide at least 6 months' notice before deprecating any API feature or version.

Deprecation Warnings

Deprecated features will return a deprecation warning in the response headers.

Migration Guides

We will provide comprehensive migration guides for any breaking changes.

There are currently no deprecated features in the API. We will update this section when deprecations are announced.