Currencies API
Powered by 14+ third party exchange rate data sources, the Currencies.dev API is capable of delivering currency conversions of all 135+ Stripe currencies. The API comes with multiple endpoints, each serving a different use case. Endpoint functionalities include converting to and from smallest units - used for the "amount" value on Stripe price objects, converting amounts from one currency to another.
Throughout this documentation you will learn about API structure, methods, potential errors and code examples. In case there any question is left unanswered, please make sure to contact us and our team will be happy to help out.
Getting Started
Definitions
API Key
Your API Key is the unique key that is passed into the API base URL's api_key parameter in order to authenticate with the Currencies API.
Base URL:
Append your API Key: Here is how to authenticate with the Currencies API:
Response
All data is returned in standard JSON format and can be parsed easily using any programming language.
Example Response: Below you will find an example API response carrying the latest 135+ native currencies supported by Stripe. This particular API request is not rate limited and infact does not even require an API key.
{
"success": true,
"timestamp": 1718892703869,
"date": "2024-06-20",
"currencies": [
"USD",
"AED",
"AFN",
"ALL",
"AMD",
"ANG",
"AOA",
[ . . . ]
}
}
The API's response will always contain a success object returning whether the request was successful or not.
Available Endpoints
The Currencies API comes with 4 endpoints, each providing a different functionality.
- Supported currencies endpoint
Retuns all 135+ native currencies supported by Stripe and our API. These requests are not rate limited.
- Convert to smallest unit endpoint
Converts a currency and amount into the smallest unit, the amount value stored in a Stripe price object.
- Convert from smallest unit endpoint
Converts a currency and smallest unit amount (the amount value stored in Stripe price objects) into the amount.
- Convert currency endpoint
Allows for conversion of any amount from one currency to another.
SSL Connection
All Currencies.dev subscription plans come with 256-bit SSL encryption. To connect to the API via SSL, simply use the https protocol instead of standard http.
Potential Errors
Whenever a requested resource is not available or an API call fails for another reason, a JSON error is returned. Errors always come with an error code and a description.
Example Error: The following error is returned if your 60 second rate limit API request volume has been exceeded.
{
"success": false,
"error": {
"code": 429,
"type": "rate_limit",
"info": "You have already made 10 requests in the past 60 seconds."
}
}
Other Errors:
Endpoints
Supported Currencies Endpoint
The Currencies API comes with a constantly updated endpoint returning all available currencies, which matches Stripe's available currencies. To access this list, make a request to the API'ssupported_currencies endpoint.
API Request:
Request Parameters:
API Response:
{
"success": true,
"timestamp": 1718892703869,
"date": "2024-06-20",
"currencies": [
"USD",
"AED",
"AFN",
"ALL",
"AMD",
"ANG",
"AOA",
[ . . . ]
}
}
Response Objects:
Supported Currencies Endpoint:
const url = 'https://api.currencies.dev/supported_currencies?api_key={YOUR_API_KEY}';
const options = {
method: 'GET'
}
try {
const response = await fetch(url, options);
const result = await response.text();
console.log(result);
} catch (error) {
console.error(error);
}
Convert To Smallest Unit Endpoint
In Stripe, the "amount" value on price objects represents the unit amount to be charged in the smallest currency unit. Most currencies multiply by 100 (e.g., $10.00 is 1000 cents), while some, like the Japanese yen, do not (e.g., ¥1000 is 1000). Currency unit definitions can change frequently and unpredictably, making it challenging to keep up. Fortunately, you can make API requests to ourconvert_to_smallest_unit endpoint to convert prices to the up-to-date Stripe amount.
API Request:
https://api.currencies.dev/convert_to_smallest_unit
?api_key=API_KEY
¤cy=USD
&amount=5.50
Request Parameters:
API Response:
{
"success": true,
"query": {
"amount": 5.5,
"currency": "usd"
},
"info": {
"timestamp": 1719244781602,
"decimals": 2
},
"date": "2024-06-24",
"result": 550
}
Response Objects:
Convert To Smallest Unit Endpoint:
const url = 'https://api.currencies.dev/convert_to_smallest_unit?currency=USD&amount=5.50&api_key={YOUR_API_KEY}';
const options = {
method: 'GET'
}
try {
const response = await fetch(url, options);
const result = await response.text();
console.log(result);
} catch (error) {
console.error(error);
}
Convert From Smallest Unit Endpoint
In Stripe, the "amount" value on price objects represents the unit amount to be charged in the smallest currency unit. To get the price in a way we are used to seeing, for most currencies we divide by 100 (e.g. for USD, 1000 is $10.00), while some, like the Japanese yen, do not (e.g., 1000 is ¥1000). Currency unit definitions can change frequently and unpredictably, making it challenging to keep up. Fortunately, you can make API requests to ourconvert_from_smallest_unit endpoint to convert amounts from stripe objects to the way our users are used to seeing them.
API Request:
https://api.currencies.dev/convert_from_smallest_unit
?api_key=API_KEY
¤cy=USD
&amount=550
Request Parameters:
API Response:
{
"success": true,
"query": {
"amount": 550,
"currency": "usd"
},
"info": {
"timestamp": 1719244781602,
"decimals": 2
},
"date": "2024-06-24",
"result": 5.5
}
Response Objects:
Convert From Smallest Unit Endpoint:
const url = 'https://api.currencies.dev/convert_from_smallest_unit?currency=USD&amount=550&api_key={YOUR_API_KEY}';
const options = {
method: 'GET'
}
try {
const response = await fetch(url, options);
const result = await response.text();
console.log(result);
} catch (error) {
console.error(error);
}
Convert Currency Endpoint
The Currencies.dev API comes with a separate currency conversion endpoint, which can be used to convert any amount from one currency to another. In order to convert currencies, please use the API'sconvert_currency endpoint, append the from and to parameters and set them to your preferred base and target currency codes.
API Request:
https://api.currencies.dev/convert_currency
?api_key=API_KEY
&from=GBP
&to=JPY
&amount=25
Request Parameters:
API Response:
{
"success": true,
"query": {
"from": "gbp",
"to": "jpy",
"amount": 25
},
"info": {
"timestamp": 1719244781602,
"rate": 199.2668
},
"date": "2024-06-24",
"result": 4981.67
}
Response Objects:
Convert From Smallest Unit Endpoint:
const url = 'https://api.currencies.dev/convert_currency?from=GBP&to=JPY&amount=25&api_key={YOUR_API_KEY}';
const options = {
method: 'GET'
}
try {
const response = await fetch(url, options);
const result = await response.text();
console.log(result);
} catch (error) {
console.error(error);
}