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.
composer require unirate/statamicThe addon's service provider is auto-discovered. Publish the config if you want to override the defaults:
php artisan vendor:publish --tag=unirate-configSet your API key in .env:
UNIRATE_API_KEY=your-key-hereGet a free API key at unirateapi.com.
{{# 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 }}$100 USD ≈ €{{ unirate:convert from="USD" to="EUR" amount="100" /}}{{ unirate:currencies }}
<option value="{{ code }}">{{ code }}</option>
{{ /unirate:currencies }}{{ unirate:vat country="DE" }}
{{ country_name }} VAT: {{ vat_rate }}%
{{ /unirate:vat }}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.
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.
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]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) |
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.
composer install
./vendor/bin/phpunitThe suite mocks all HTTP traffic — no live API calls or key required.
Found a bug or need help? Open an issue on GitHub Issues. For questions about your API key or plan, see unirateapi.com.
MIT — see LICENSE.
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.