API Documentation

Complete reference for all XRates API endpoints. Get started in minutes.

Last updated: March 18, 2026

OpenAPI 3.0 Spec (JSON) Postman Collection

New here? Start with the Free Exchange Rate API overview, see the FX Rates API use cases, or compare XRates with Fixer.io and ExchangeRate-API.

Get free API key

Authentication

Most API endpoints require authentication using a Bearer token. After creating an account, you can find your API key in the dashboard.

Include your API key in the Authorization header of every request:

Authorization Header

Authorization: Bearer YOUR_API_KEY

Important: Keep your API key secret. Do not expose it in client-side code, public repositories, or share it with unauthorized parties. If your key is compromised, regenerate it immediately from your dashboard.

Base URL

All API requests should be made to the following base URL:

https://xratesapi.com/api/v1

Error Handling

The API uses standard HTTP status codes. Error responses include a JSON body with details:

HTTP status codes and their descriptions
Status Code	Description
200	Success
401	Unauthorized - Invalid or missing API key
422	Validation error - Invalid parameters
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Error Response Example

{
  "success": false,
  "error": {
    "code": 401,
    "message": "Invalid API key."
  }
}

Official SDKs

Hand-written, thin wrappers over the REST API — same seven methods and the same four-tier error hierarchy (ApiError, AuthenticationError, RateLimitError, ValidationError) in every language. ~200 lines of source each, MIT-licensed, no leaky generated types.

PHP

composer require xratesapi/php-sdk

JavaScript / TypeScript

npm install @xratesapi/sdk

Python

pip install xratesapi

go get github.com/xratesapi/go-sdk

Ruby

gem install xratesapi

Side-by-side guide →

Same code, five languages

Working in a language we don't cover yet? Point your favourite client generator at the OpenAPI 3.0 spec — we publish it precisely so you can.

Endpoints

GET Public

/api/v1/status

Check the API status and availability. This endpoint does not require authentication and can be used for health checks and monitoring.

Parameters

No parameters required.

Example Request

cURL

curl https://xratesapi.com/api/v1/status

Example Response

200 OK

{
  "success": true,
  "status": "operational",
  "message": "XRates API is running.",
  "timestamp": "2026-03-09T12:00:00Z"
}

GET

/api/v1/latest

Retrieve the latest exchange rates. Returns the most recent exchange rate data available for the specified base currency and target symbols.

Parameters

Parameters for GET /api/v1/latest
Parameter	Type	Required	Description
base	string	No	Base currency code (default: USD)
symbols	string	No	Comma-separated list of target currency codes

Example Request

cURL

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://xratesapi.com/api/v1/latest?base=USD&symbols=EUR,GBP"

Example Response

200 OK

{
  "success": true,
  "base": "USD",
  "date": "2026-03-09",
  "rates": {
    "EUR": 0.9214,
    "GBP": 0.7843
  }
}

GET

/api/v1/{date}

Retrieve historical exchange rates for a specific date. The date must be provided in YYYY-MM-DD format.

Parameters

Parameters for GET /api/v1/{date}
Parameter	Type	Required	Description
{date}	string	Yes	Date in YYYY-MM-DD format (URL path parameter)
base	string	No	Base currency code (default: USD)
symbols	string	No	Comma-separated list of target currency codes

Example Request

cURL

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://xratesapi.com/api/v1/2026-03-01?base=USD&symbols=EUR,GBP"

Example Response

200 OK

{
  "success": true,
  "historical": true,
  "base": "USD",
  "date": "2026-03-01",
  "rates": {
    "EUR": 0.8621,
    "GBP": 1.3298
  }
}

GET

/api/v1/currencies

Retrieve a list of all supported currencies with their full names. Useful for building currency selectors and validating currency codes.

Parameters

No parameters required.

Example Request

cURL

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://xratesapi.com/api/v1/currencies"

Example Response

200 OK

{
  "success": true,
  "currencies": {
    "USD": "United States Dollar",
    "EUR": "Euro",
    "GBP": "British Pound Sterling",
    "JPY": "Japanese Yen",
    "CHF": "Swiss Franc",
    "CAD": "Canadian Dollar",
    "AUD": "Australian Dollar",
    "CNY": "Chinese Yuan",
    "RUB": "Russian Ruble",
    "..."
  }
}

GET

/api/v1/convert

Convert an amount from one currency to another using the latest exchange rates. Returns both the converted amount and the exchange rate used.

Parameters

Parameters for GET /api/v1/convert
Parameter	Type	Required	Description
from	string	Yes	Source currency code
to	string	Yes	Target currency code
amount	number	Yes	Amount to convert

Example Request

cURL

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://xratesapi.com/api/v1/convert?from=USD&to=EUR&amount=100"

Example Response

200 OK

{
  "success": true,
  "query": {
    "from": "USD",
    "to": "EUR",
    "amount": 100
  },
  "info": {
    "rate": 0.9214,
    "timestamp": "2026-03-09T12:00:00Z"
  },
  "date": "2026-03-09",
  "result": 92.14
}

GET

/api/v1/timeseries

Retrieve daily exchange rates between two dates. Useful for building charts and analyzing currency trends over time. Maximum date range is 365 days.

Parameters

Parameters for GET /api/v1/timeseries
Parameter	Type	Required	Description
start_date	string	Yes	Start date in YYYY-MM-DD format
end_date	string	Yes	End date in YYYY-MM-DD format
base	string	No	Base currency code (default: USD)
symbols	string	No	Comma-separated list of target currency codes

Example Request

cURL

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://xratesapi.com/api/v1/timeseries?start_date=2026-01-01&end_date=2026-01-31&base=USD&symbols=EUR"

Example Response

200 OK

{
  "success": true,
  "timeseries": true,
  "base": "USD",
  "start_date": "2026-01-01",
  "end_date": "2026-01-31",
  "rates": {
    "2026-01-01": {
      "EUR": 0.8612
    },
    "2026-01-02": {
      "EUR": 0.8625
    },
    "2026-01-03": {
      "EUR": 0.8598
    },
    "...": "..."
  }
}

GET

/api/v1/fluctuation

Retrieve currency fluctuation data between two dates. Returns the start rate, end rate, change amount, and change percentage for each specified currency. Maximum date range is 365 days.

Parameters

Parameters for GET /api/v1/fluctuation
Parameter	Type	Required	Description
start_date	string	Yes	Start date in YYYY-MM-DD format
end_date	string	Yes	End date in YYYY-MM-DD format
base	string	No	Base currency code (default: USD)
symbols	string	No	Comma-separated list of target currency codes

Example Request

cURL

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://xratesapi.com/api/v1/fluctuation?start_date=2026-01-01&end_date=2026-01-31&base=USD&symbols=EUR"

Example Response

200 OK

{
  "success": true,
  "fluctuation": true,
  "base": "USD",
  "start_date": "2026-01-01",
  "end_date": "2026-01-31",
  "rates": {
    "EUR": {
      "start_rate": 0.8612,
      "end_rate": 0.9214,
      "change": 0.0042,
      "change_pct": 0.4878
    }
  }
}

Ready to Start Building?

Get your free API key and start making requests in minutes.

Get Free API Key