API Reference

Full documentation for all xchangr8 endpoints, authentication, and rate limits.

Authentication

Every request must include your API key. Two methods are supported:

Preferred X-API-Key: xc8_live_YOUR_KEY — HTTP header
Alternative ?apikey=xc8_live_YOUR_KEY — query parameter
Rate limit headers

Every response includes these headers so you can track your usage:

Response headers
X-RateLimit-Limit:     333
X-RateLimit-Remaining: 312
X-RateLimit-Reset:     1749340860
GET /v1/latest

Returns the latest exchange rates for all supported currencies (or a filtered subset). Rates are refreshed every 60 seconds on Starter and higher plans, and every 10 minutes on the Free plan.

Parameters
Parameter Type Required Description
base string Optional Base currency code. All returned rates are relative to this currency. Default: USD
symbols string Optional Comma-separated list of currency codes to include in the response. If omitted, all supported currencies are returned.
Example request
bash 
curl "https://api.xchangr8.com/v1/latest?base=JPY&symbols=USD,EUR,AUD" \
  -H "X-API-Key: xc8_live_YOUR_KEY"
Example response
JSON 
{
  "base":        "JPY",
  "timestamp":   1749340800,
  "freshness":   "1m ago",
  "source":      "fastforex",
  "rates": {
    "USD": 0.006673,
    "EUR": 0.006140,
    "AUD": 0.010281
  }
}
GET /v1/convert

Convert a specific amount from one currency to another using the latest available rate. Useful for checkout flows and single-shot conversions without needing to fetch the full rates object.

Parameters
Parameter Type Required Description
from string Required Source currency code (e.g. USD)
to string Required Target currency code (e.g. JPY)
amount number Required The amount to convert, in the source currency
Example request
bash 
curl "https://api.xchangr8.com/v1/convert?from=USD&to=JPY&amount=100" \
  -H "X-API-Key: xc8_live_YOUR_KEY"
Example response
JSON 
{
  "from":      "USD",
  "to":        "JPY",
  "amount":    100,
  "result":    14985.00,
  "rate":      149.85,
  "timestamp": 1749340800
}
GET /v1/historical

Returns exchange rates for a specific past date. Historical data is available from January 1, 2020. Useful for invoicing, auditing, and displaying past transaction values.

Parameters
Parameter Type Required Description
date string Required Date in YYYY-MM-DD format (e.g. 2025-01-15)
base string Optional Base currency. Default: USD
symbols string Optional Comma-separated currency codes to filter the response
Example request
bash 
curl "https://api.xchangr8.com/v1/historical?date=2025-01-15&base=USD&symbols=JPY,EUR" \
  -H "X-API-Key: xc8_live_YOUR_KEY"
Example response
JSON 
{
  "base":      "USD",
  "date":      "2025-01-15",
  "timestamp": 1736899200,
  "source":    "fastforex",
  "rates": {
    "JPY": 157.42,
    "EUR": 0.9134
  }
}
GET /v1/timeseries

Returns a daily rate series for a date range. Ideal for charts, trend analysis, and reporting dashboards. The maximum range depends on your plan.

Plan limits: Free plan — 7 days max. Starter plan — 365 days max.

Parameters
Parameter Type Required Description
start_date string Required Start of the date range in YYYY-MM-DD format
end_date string Required End of the date range in YYYY-MM-DD format
base string Optional Base currency. Default: USD
symbols string Optional Comma-separated currency codes to filter the response
Example request
bash 
curl "https://api.xchangr8.com/v1/timeseries?start_date=2025-01-01&end_date=2025-01-07&base=USD&symbols=JPY,EUR" \
  -H "X-API-Key: xc8_live_YOUR_KEY"
Example response
JSON 
{
  "base":       "USD",
  "start_date": "2025-01-01",
  "end_date":   "2025-01-07",
  "rates": {
    "2025-01-01": { "JPY": 156.90, "EUR": 0.9120 },
    "2025-01-02": { "JPY": 157.10, "EUR": 0.9115 },
    "2025-01-03": { "JPY": 157.33, "EUR": 0.9108 },
    // ... continues for each date in range
  }
}
GET /v1/currencies

Returns a map of all currency codes to their full names. Useful for building currency pickers and validating input values. This endpoint is not rate-limited and may be cached aggressively.

Parameters

No parameters. This endpoint takes no query parameters or headers beyond the API key.

Example request
bash 
curl https://api.xchangr8.com/v1/currencies \
  -H "X-API-Key: xc8_live_YOUR_KEY"
Example response
JSON 
{
  "currencies": {
    "USD": "US Dollar",
    "EUR": "Euro",
    "JPY": "Japanese Yen",
    "GBP": "British Pound Sterling",
    "AUD": "Australian Dollar",
    "CAD": "Canadian Dollar",
    "CHF": "Swiss Franc",
    "CNY": "Chinese Yuan",
    "HKD": "Hong Kong Dollar",
    "SGD": "Singapore Dollar",
    "KRW": "South Korean Won",
    "INR": "Indian Rupee",
    // ... 31 currencies total
  }
}