unirate-api 0.1.0

UniRate D Client

Official D client for the UniRate API — free, real-time and historical currency exchange rates plus VAT rates.

• Real-time exchange rates between 170+ currencies (fiat + crypto)
• Historical rates back to 1999
• Time-series ranges up to 5 years
• Currency conversion (current and historical)
• VAT rates for countries worldwide
• Free tier, no credit card required
• Zero third-party dependencies — only the D standard library (std.net.curl + std.json)

Requirements

• A D compiler (DMD 2.100+ or a recent LDC) and dub
• libcurl available at link/run time (bundled with most D toolchains)

Installation

Add the dependency with dub:

dub add unirate-api

or in your dub.json:

"dependencies": {
    "unirate-api": "~>0.1.0"
}

Quick start

import unirate;
import std.process : environment;
import std.stdio : writefln;

void main()
{
    auto client = new Client(environment["UNIRATE_API_KEY"]);

    double rate = client.getRate("USD", "EUR");
    writefln("USD -> EUR: %.4f", rate);

    double euros = client.convert(100, "USD", "EUR");
    writefln("100 USD = %.2f EUR", euros);
}

Get a free API key at https://unirateapi.com.

API

Construction

auto client = new Client(
    "your-api-key",
    30.seconds,                     // request timeout (default 30s)
    "https://api.unirateapi.com",   // base URL (override for tests)
);

Current rates

double rate = client.getRate("USD", "EUR");
// → double

double[string] rates = client.getAllRates("USD");
// → currency code -> rate

double result = client.convert(100, "USD", "EUR");
// → double

string[] codes = client.getSupportedCurrencies();
// → list of currency codes

Historical data (Pro-gated — 403 on free tier)

double rate = client.getHistoricalRate("2024-01-01", "USD", "EUR");

double[string] rates = client.getHistoricalRates("2024-01-01", "USD");

double amount = client.convertHistorical(100, "USD", "EUR", "2024-01-01");

auto series = client.getTimeSeries(
    "2024-01-01", "2024-01-07",
    1,                       // amount
    "USD",                   // base
    ["EUR", "GBP"],          // pass [] for all currencies
);

auto limits = client.getHistoricalLimits();

VAT rates

auto all = client.getVatRates();

auto de = client.getVatRate("DE");
writeln(de.vatData.vatRate); // 19.0

format and callback

Every method accepts an optional trailing CallOptions argument for the API's format and callback query parameters:

client.getRate("USD", "EUR", CallOptions("xml"));

The typed methods always decode JSON, so requesting a non-JSON format will fail to parse — build the URL yourself if you need a raw XML/CSV body.

Error handling

All errors derive from UniRateException. Catch that to handle every failure, or a specific subclass to branch on the HTTP semantics:

import unirate;

try
{
    auto rate = client.getRate("USD", "ZZZ");
}
catch (AuthenticationException e)  { /* 401 — invalid API key */ }
catch (InvalidCurrencyException e) { /* 404 — unknown currency code */ }
catch (RateLimitException e)       { /* 429 — back off and retry */ }
catch (InvalidDateException e)     { /* 400 — bad request parameters */ }
catch (APIException e)
{
    // Any other non-2xx, including 403 on Pro-gated endpoints and 503.
    writefln("status %d: %s", e.statusCode, e.responseBody);
}
catch (UniRateException e)         { /* transport / parse failure */ }

Dependency injection for tests

The constructor accepts a Transport delegate — Response delegate(string url, string[string] headers) — so tests can run entirely offline without libcurl:

import unirate;
import core.time : seconds;

Response stub(string url, string[string] headers)
{
    return Response(200, `{"rate": "0.9"}`);
}

auto client = new Client("test-key", 30.seconds, "https://mock.local", &stub);
assert(client.getRate("USD", "EUR") == 0.9);

Rate limits

• Currency endpoints: standard rate limits apply
• Historical endpoints: 50 requests/hour on the free tier
• VAT endpoints: 1800 requests/hour on the free tier

Testing

dub test                           # mock tests (no network)
UNIRATE_API_KEY=... dub test       # additionally runs the free-tier live tests

Related clients

• unirate-api-python (PyPI: unirate-api)
• unirate-api-nodejs (npm: unirate-api)
• unirate-api-go
• unirate-api-rust (crates.io: unirate-api)

<!-- unirate-ecosystem-footer:start -->

Other UniRate clients

UniRate ships official client libraries and framework integrations across the ecosystem. The repos below are all maintained under the UniRate-API org.

• Languages: Python · Node.js / TypeScript · Go · Rust · Java · Ruby · PHP · .NET · Swift
• Web frameworks: NestJS · Django / Wagtail · FastAPI · Flask · React · tRPC
• Static-site generators: Astro · Eleventy · Hugo
• Data / orchestration: Airflow · dbt · LangChain
• Workflow / no-code: n8n · Google Sheets · MCP server
• Editors / tools: VS Code · Obsidian

Get a free API key at unirateapi.com. <!-- unirate-ecosystem-footer:end -->

License

MIT — see LICENSE.