README

Official PHP client for the XRates exchange rate API. Multi-source FX rates aggregated from ECB, CBR, FloatRates, fawazahmed0 and IMF, served via a single REST endpoint.

• Documentation: https://xratesapi.com/docs
• Free tier: 100 requests/month, no credit card — sign up
• Status: https://xratesapi.com/status

Requirements

• PHP 8.1+
• Guzzle 7.5+ (or any PSR-compatible HTTP client)

Installation

composer require xratesapi/php-sdk

Quick start

use XRatesApi\Client;

$client = new Client('YOUR_API_KEY');

// Latest rates: rates[T] = "X T per 1 base"
$response = $client->latest('USD', ['EUR', 'GBP']);
// ['base' => 'USD', 'rates' => ['EUR' => 0.864, 'GBP' => 0.79], ...]

// Historical
$response = $client->historical('2026-05-01', 'USD', ['EUR']);

// Convert an amount
$response = $client->convert('USD', 'EUR', 100.0);
// ['from' => 'USD', 'to' => 'EUR', 'amount' => 100, 'result' => 86.4]

// Time-series
$response = $client->timeseries('2026-01-01', '2026-01-31', 'USD', ['EUR']);

// Rate fluctuation
$response = $client->fluctuation('2026-01-01', '2026-01-31', 'USD', ['EUR']);

// Currencies
$response = $client->currencies();

// Public status (no API key required, but the client sends one anyway)
$response = $client->status();

Error handling

Every HTTP error maps to one of four exception types, all extending XRatesApi\Exceptions\ApiException:

use XRatesApi\Exceptions\RateLimitException;
use XRatesApi\Exceptions\ApiException;

try {
    $rates = $client->latest('USD', ['EUR']);
} catch (RateLimitException $e) {
    // back off and retry
} catch (ApiException $e) {
    // log and surface to caller
    error_log("XRates: " . $e->getMessage());
}

Custom HTTP client

The constructor accepts any \GuzzleHttp\ClientInterface, so you can plug in your own configured client (timeouts, retry middleware, proxy, etc.):

$guzzle = new \GuzzleHttp\Client([
    'timeout' => 5,
    'connect_timeout' => 2,
]);

$client = new Client('YOUR_API_KEY', $guzzle);

Custom base URL

Useful for tests or self-hosted deployments:

$client = new Client('YOUR_API_KEY', null, 'https://staging.xratesapi.com');

Versioning

This SDK follows semver. The Client::VERSION constant is sent in the User-Agent header on every request, which helps us debug integration issues if you contact support.

Contributing

PRs welcome. Run the tests:

composer install
composer test

License

MIT — see LICENSE file.