API Reference
Introduction Authentication Rate Limits Response Format Error Codes
Endpoints
Latest Exchange Rates Historical Exchange Rates Convert Currency Currency List
Code Samples
PHP JavaScript cURL

Introduction

The Currency API provides a simple and reliable way to get the latest exchange rates, historical rates, convert between currencies, and retrieve a list of available currencies. The API is RESTful and returns data in JSON format.

Base URL: https://api.thecurrencyapi.com

Authentication

All API requests require an API key. You can include your API key as a query parameter in all requests:

https://api.thecurrencyapi.com/endpoint?api_key=YOUR_API_KEY

Alternatively, you can pass your API key in the request headers:

X-API-Key: YOUR_API_KEY
Never share your API key publicly or commit it to source code repositories.

Rate Limits

API usage is limited based on your subscription plan. Each API call counts as one request against your monthly allowance. The API response includes your current usage information:

{
    "success": true,
    "message": "Success",
    "code": 200,
    "account": {
        "monthly_allowance": 1000,
        "current_month_allowance": 950,
        "monthly_allowance_reset_date": "2025-06-01"
    },
    "data": { ... }
}

Response Format

All API responses follow the same format:

{
    "success": true|false,
    "message": "Success or error message",
    "code": 200, // HTTP status code
    "account": { ... }, // Account information
    "data": { ... } // Response data
}

Error Codes

The API uses standard HTTP status codes to indicate the success or failure of an API request:

Code Description
200 Success
400 Bad Request (general error)
401 Unauthorized (API key issues)
404 Not Found (resource not found)
422 Unprocessable Entity (validation error)
429 Too Many Requests (rate limit exceeded)
500 Internal Server Error (server-side issues)
503 Service Unavailable (external API issues)

Latest Exchange Rates

Get the latest exchange rates for one or multiple currencies.

Endpoint

GET /latest

Parameters

Parameter Type Required Description
api_key string Yes Your API key
from string Yes Base currency code (e.g., USD, EUR)
to string Yes Target currency code(s), comma-separated for multiple currencies (e.g., EUR or EUR,GBP,JPY)

Example Request

https://api.thecurrencyapi.com/latest?api_key=YOUR_API_KEY&from=USD&to=EUR,GBP,JPY

Example Response

{
    "success": true,
    "message": "Success",
    "code": 200,
    "account": {
        "monthly_allowance": 1000,
        "current_month_allowance": 950,
        "monthly_allowance_reset_date": "2025-06-01"
    },
    "data": {
        "base_currency": "USD",
        "last_updated_at": "2025-06-04 10:30:15",
        "exchange_rates": {
            "EUR": 0.92105,
            "GBP": 0.78651,
            "JPY": 149.30215
        }
    }
}

Historical Exchange Rates

Get historical exchange rates for a specific date.

Endpoint

GET /historical

Parameters

Parameter Type Required Description
api_key string Yes Your API key
date string Yes Date in YYYY-MM-DD format
from string Yes Base currency code (e.g., USD, EUR)
to string Yes Target currency code(s), comma-separated for multiple currencies (e.g., EUR or EUR,GBP,JPY)

Example Request

https://api.thecurrencyapi.com/historical?api_key=YOUR_API_KEY&date=2025-01-15&from=USD&to=EUR,GBP

Example Response

{
    "success": true,
    "message": "Success",
    "code": 200,
    "account": {
        "monthly_allowance": 1000,
        "current_month_allowance": 949,
        "monthly_allowance_reset_date": "2025-06-01"
    },
    "data": {
        "base_currency": "USD",
        "requested_date": "2025-01-15",
        "actual_date": "2025-01-15 16:00:00",
        "exchange_rates": {
            "EUR": 0.91854,
            "GBP": 0.78123
        }
    }
}

Convert Currency

Convert an amount from one currency to another using the latest exchange rates.

Endpoint

GET /convert

Parameters

Parameter Type Required Description
api_key string Yes Your API key
from string Yes Source currency code (e.g., USD)
to string Yes Target currency code (e.g., EUR)
amount number Yes Amount to convert (must be a non-empty number)

Example Request

https://api.thecurrencyapi.com/convert?api_key=YOUR_API_KEY&from=USD&to=EUR&amount=100

Example Response

{
    "success": true,
    "message": "Success",
    "code": 200,
    "account": {
        "monthly_allowance": 1000,
        "current_month_allowance": 948,
        "monthly_allowance_reset_date": "2025-06-01"
    },
    "data": {
        "from": "USD",
        "to": "EUR",
        "amount": 100,
        "exchange_rate": 0.92105,
        "converted_amount": "92.10",
        "last_updated_at": "2025-06-04 10:30:15"
    }
}

Currency List

Get a list of all available currencies.

Endpoint

GET /currencylist

Parameters

Parameter Type Required Description
api_key string Yes Your API key

Example Request

https://api.thecurrencyapi.com/currencylist?api_key=YOUR_API_KEY

Example Response

{
    "success": true,
    "message": "Success",
    "code": 200,
    "account": {
        "monthly_allowance": 1000,
        "current_month_allowance": 947,
        "monthly_allowance_reset_date": "2025-06-01"
    },
    "data": {
        "currencies": {
            "USD": "United States Dollar",
            "EUR": "Euro",
            "GBP": "British Pound Sterling",
            "JPY": "Japanese Yen",
            "AUD": "Australian Dollar",
            "CAD": "Canadian Dollar",
            "CHF": "Swiss Franc",
            "CNY": "Chinese Yuan"
            // ... more currencies
        }
    }
}

PHP Sample Code

Here's how to use the API with PHP:

<?php
// Your API key
$apiKey = 'YOUR_API_KEY';

// Base URL
$baseUrl = 'https://api.thecurrencyapi.com';

// Function to make API requests
function callApi($endpoint, $params = []) {
    global $apiKey, $baseUrl;
    
    // Add API key to parameters
    $params['api_key'] = $apiKey;
    
    // Build URL with query parameters
    $url = $baseUrl . $endpoint . '?' . http_build_query($params);
    
    // Initialize cURL
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 10);
    
    // Execute request
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    
    // Check for errors
    if (curl_errno($ch)) {
        $error = curl_error($ch);
        curl_close($ch);
        return ['success' => false, 'message' => 'cURL error: ' . $error];
    }
    
    curl_close($ch);
    
    // Parse JSON response
    $result = json_decode($response, true);
    
    return $result;
}

// Example: Get latest exchange rates
$latestResult = callApi('latest', ['from' => 'USD', 'to' => 'EUR,GBP,JPY']);

if ($latestResult['success']) {
    echo "Base currency: " . $latestResult['data']['base_currency'] . "\n";
    echo "Last updated: " . $latestResult['data']['last_updated_at'] . "\n";
    echo "Exchange rates:\n";
    foreach ($latestResult['data']['exchange_rates'] as $currency => $rate) {
        echo "$currency: $rate\n";
    }
} else {
    echo "Error: " . $latestResult['message'] . "\n";
}

// Example: Get historical exchange rates
$historicalResult = callApi('historical', [
    'date' => '2025-01-15',
    'from' => 'USD',
    'to' => 'EUR,GBP'
]);

if ($historicalResult['success']) {
    echo "Base currency: " . $historicalResult['data']['base_currency'] . "\n";
    echo "Date: " . $historicalResult['data']['requested_date'] . "\n";
    echo "Historical rates:\n";
    foreach ($historicalResult['data']['exchange_rates'] as $currency => $rate) {
        echo "$currency: $rate\n";
    }
} else {
    echo "Error: " . $historicalResult['message'] . "\n";
}

// Example: Convert currency
$convertResult = callApi('convert', [
    'from' => 'USD',
    'to' => 'EUR',
    'amount' => 100
]);

if ($convertResult['success']) {
    echo "From: " . $convertResult['data']['from'] . "\n";
    echo "To: " . $convertResult['data']['to'] . "\n";
    echo "Amount: " . $convertResult['data']['amount'] . " " . $convertResult['data']['from'] . "\n";
    echo "Exchange rate: " . $convertResult['data']['exchange_rate'] . "\n";
    echo "Converted amount: " . $convertResult['data']['converted_amount'] . " " . $convertResult['data']['to'] . "\n";
} else {
    echo "Error: " . $convertResult['message'] . "\n";
}
?>

JavaScript Sample Code

Here's how to use the API with JavaScript:

// Your API key
const apiKey = 'YOUR_API_KEY';

// Base URL
const baseUrl = 'https://api.thecurrencyapi.com';

// Function to make API requests
async function callApi(endpoint, params = {}) {
    // Add API key to parameters
    params.api_key = apiKey;
    
    // Build URL with query parameters
    const url = `${baseUrl}${endpoint}?${new URLSearchParams(params)}`;
    
    try {
        // Make request
        const response = await fetch(url, {
            method: 'GET',
            headers: {
                'Accept': 'application/json'
            }
        });
        
        // Parse JSON response
        const data = await response.json();
        return data;
    } catch (error) {
        return {
            success: false,
            message: `Error: ${error.message}`
        };
    }
}

// Example: Get latest exchange rates
async function getLatestRates() {
    const result = await callApi('latest', { 
        from: 'USD', 
        to: 'EUR,GBP,JPY' 
    });
    
    if (result.success) {
        console.log(`Base currency: ${result.data.base_currency}`);
        console.log(`Last updated: ${result.data.last_updated_at}`);
        console.log('Exchange rates:');
        Object.entries(result.data.exchange_rates).forEach(([currency, rate]) => {
            console.log(`${currency}: ${rate}`);
        });
    } else {
        console.error(`Error: ${result.message}`);
    }
}

// Example: Get historical exchange rates
async function getHistoricalRates() {
    const result = await callApi('historical', {
        date: '2025-01-15',
        from: 'USD',
        to: 'EUR,GBP'
    });
    
    if (result.success) {
        console.log(`Base currency: ${result.data.base_currency}`);
        console.log(`Date: ${result.data.requested_date}`);
        console.log('Historical rates:');
        Object.entries(result.data.exchange_rates).forEach(([currency, rate]) => {
            console.log(`${currency}: ${rate}`);
        });
    } else {
        console.error(`Error: ${result.message}`);
    }
}

// Example: Convert currency
async function convertCurrency() {
    const result = await callApi('convert', {
        from: 'USD',
        to: 'EUR',
        amount: 100
    });
    
    if (result.success) {
        console.log(`From: ${result.data.from}`);
        console.log(`To: ${result.data.to}`);
        console.log(`Amount: ${result.data.amount} ${result.data.from}`);
        console.log(`Exchange rate: ${result.data.exchange_rate}`);
        console.log(`Converted amount: ${result.data.converted_amount} ${result.data.to}`);
    } else {
        console.error(`Error: ${result.message}`);
    }
}

// Call the functions
getLatestRates();
getHistoricalRates();
convertCurrency();

cURL Sample Code

Here's how to use the API with cURL:

# Your API key
API_KEY="YOUR_API_KEY"

# Base URL
BASE_URL="https://api.thecurrencyapi.com"

# Example: Get latest exchange rates
curl -G "${BASE_URL}/latest" \
  --data-urlencode "api_key=${API_KEY}" \
  --data-urlencode "from=USD" \
  --data-urlencode "to=EUR,GBP,JPY"

# Example: Get historical exchange rates
curl -G "${BASE_URL}/historical" \
  --data-urlencode "api_key=${API_KEY}" \
  --data-urlencode "date=2025-01-15" \
  --data-urlencode "from=USD" \
  --data-urlencode "to=EUR,GBP"

# Example: Convert currency
curl -G "${BASE_URL}/convert" \
  --data-urlencode "api_key=${API_KEY}" \
  --data-urlencode "from=USD" \
  --data-urlencode "to=EUR" \
  --data-urlencode "amount=100"

# Example: Get currency list
curl -G "${BASE_URL}/currencylist" \
  --data-urlencode "api_key=${API_KEY}"