UniRate — Live Currency Exchange Rates

Antlers tags for live currency exchange rates, conversion, currency lists, and VAT rates via the UniRate API.

A Statamic addon that brings live currency exchange rates, conversion, supported-currency lists, and VAT rates into your Antlers templates — powered by the UniRate API.

Compatibility: Statamic 5 and 6 (PHP 8.2+). CI runs the test suite against both majors.

Installation

composer require unirate/statamic

The addon's service provider is auto-discovered. Publish the config if you want to override the defaults:

php artisan vendor:publish --tag=unirate-config

Set your API key in .env:

UNIRATE_API_KEY=your-key-here

Get a free API key at unirateapi.com.

Antlers tags

{{ unirate:rate }}

{{# Single rate. Use the self-closing /}} form for single tags, so Antlers #}}
{{# never pairs them with a later {{ /unirate:rate }} closing tag. #}}
1 USD = {{ unirate:rate from="USD" to="EUR" /}} EUR
 
{{# As a pair, with graceful error handling #}}
{{ unirate:rate from="USD" to="GBP" }}
{{ if error }}Unavailable{{ else }}{{ rate }}{{ /if }}
{{ /unirate:rate }}
 
{{# Loop every rate for a base currency #}}
{{ unirate:rate from="USD" }}
{{ currency }}: {{ rate }}
{{ /unirate:rate }}

{{ unirate:convert }}

$100 USD ≈ €{{ unirate:convert from="USD" to="EUR" amount="100" /}}

{{ unirate:currencies }}

{{ unirate:currencies }}
<option value="{{ code }}">{{ code }}</option>
{{ /unirate:currencies }}

{{ unirate:vat }}

{{ unirate:vat country="DE" }}
{{ country_name }} VAT: {{ vat_rate }}%
{{ /unirate:vat }}

Failing gracefully

Tags never break the page. On any failure — an HTTP error, a timeout, or the API being unreachable — a single tag renders nothing, and a tag pair renders its contents once with an {{ error }} variable so you can present a fallback:

{{ unirate:currencies }}
{{ if error }}
<option disabled>Currencies unavailable</option>
{{ else }}
<option value="{{ code }}">{{ code }}</option>
{{ /if }}
{{ /unirate:currencies }}

Error messages never contain the request URL or your API key. After a connection failure the addon stops calling the API for 30 seconds, so an outage costs one timeout per page instead of one per tag.

Caching

Successful responses are cached in your default cache store for 10 minutes (UNIRATE_CACHE_TTL, in seconds) so pages don't call the API on every render. Set UNIRATE_CACHE_TTL=0 to disable. Failed requests are never cached.

Using the client directly

The addon registers a singleton UniRate\Statamic\UniRateClient you can inject or resolve in your own code:

use UniRate\Statamic\UniRateClient;
 
$client = app(UniRateClient::class);
 
$rate = $client->getRate('USD', 'EUR'); // 0.92
$allRates = $client->getRate('USD'); // ['EUR' => 0.92, ...]
$converted = $client->convert('EUR', 100, 'USD'); // 92.5
$currencies = $client->getSupportedCurrencies(); // ['USD', 'EUR', ...]
$vat = $client->getVatRates('DE'); // ['country_name' => 'Germany', 'vat_rate' => 19.0]

Configuration

config/unirate.php:

Key Env Default
api_key UNIRATE_API_KEY —
base_url UNIRATE_API_BASE_URL https://api.unirateapi.com
timeout UNIRATE_TIMEOUT 5 (seconds)
cache_ttl UNIRATE_CACHE_TTL 600 (seconds, 0 = off)

Error handling

The client throws UniRate\Statamic\UniRateException for every failure, including timeouts and connection errors (code 0). HTTP errors carry the status as the exception code:

Status Meaning
400 Invalid request parameters
401 Missing or invalid API key
403 Endpoint requires a Pro subscription
404 Currency not found or no data available
429 Rate limit exceeded
503 Service unavailable

Historical endpoints (getHistoricalRate) are Pro-gated and return 403 on the free tier.

Testing

composer install
./vendor/bin/phpunit

The suite mocks all HTTP traffic — no live API calls or key required.

Support

Found a bug or need help? Open an issue on GitHub Issues. For questions about your API key or plan, see unirateapi.com.

License

MIT — see LICENSE.

Related clients

Part of the official UniRate client family: Python, Node/TypeScript, Swift, Java, Go, Rust, Ruby, PHP, and .NET, plus framework integrations for Laravel, Symfony, WordPress, and more.