unirate-api (Clojure)

Official Clojure client for the UniRate API — free currency exchange rates, historical data, and VAT rates.

• Zero-ceremony HTTP. Transport is the JDK's built-in java.net.http; the only third-party runtime dependency is the official org.clojure/data.json parser.
• Full API parity with the other UniRate clients (Python, Node, Go, Rust, Swift, …).
• Testable by design. Inject a :transport function to run without a network.

Requirements

• JDK 11+ (for java.net.http)
• Clojure CLI (clojure / deps.edn) or Leiningen

Installation

deps.edn:

com.unirateapi/unirate-api {:mvn/version "0.1.0"}

Leiningen project.clj:

[com.unirateapi/unirate-api "0.1.0"]

Published on Clojars.

Quick start

(require '[unirate.client :as unirate])

(def client (unirate/make-client "your-api-key"))

;; Current rate (returns a double)
(unirate/get-rate client "USD" "EUR")            ;; => 0.9321

;; All rates for a base currency (returns {code double})
(unirate/get-all-rates client "USD")             ;; => {"EUR" 0.93, "GBP" 0.79, ...}

;; Convert an amount
(unirate/convert client 100 "USD" "EUR")         ;; => 93.21

;; Supported currency codes
(unirate/get-supported-currencies client)        ;; => ["USD" "EUR" "GBP" ...]

;; VAT rates
(unirate/get-vat-rate client "DE")               ;; => {"country" "DE" "vat_data" {...}}
(unirate/get-vat-rates client)                   ;; => {"date" ... "vat_rates" {...}}

Currency and country codes are uppercased for you before the request.

The client is a plain map; construct it once and pass it to each function. To override the timeout or base URL:

(unirate/make-client "your-api-key" {:timeout-seconds 20
                                     :base-url "https://api.unirateapi.com"})

API

Function	Returns
(get-rate client from to)	double
(get-all-rates client base)	{code double}
(convert client amount from to)	double
(get-supported-currencies client)	[code ...]
(get-historical-rate client date from to)	double (Pro)
(get-historical-rates client date base)	{code double} (Pro)
(convert-historical client amount from to date)	double (Pro)
(get-time-series client start end opts)	{date {code double}} (Pro)
(get-historical-limits client)	parsed map (Pro)
(get-vat-rates client)	parsed map
(get-vat-rate client country)	parsed map

Every function takes an optional trailing options map supporting :format and :callback query parameters; get-time-series also takes :amount, :base, and :currencies.

Endpoints marked (Pro) require a Pro subscription and return HTTP 403 on the free tier (surfaced as an :api error — see below).

Error handling

Every error is a clojure.lang.ExceptionInfo carrying a :unirate/error-type keyword in its ex-data. Catch the base type to handle any failure, or branch on the type:

(try
  (unirate/get-rate client "USD" "EUR")
  (catch clojure.lang.ExceptionInfo e
    (case (:unirate/error-type (ex-data e))
      :authentication   (println "check your API key")
      :rate-limit       (println "slow down")
      :invalid-currency (println "unknown currency")
      :invalid-date     (println "bad date")
      :api              (println "API error" (:status (ex-data e)))
      (throw e))))

:unirate/error-type	HTTP	Meaning
:invalid-date	400	Malformed date / invalid request parameters
:authentication	401	Missing or invalid API key
:invalid-currency	404	Unknown currency or no data available
:rate-limit	429	Request quota exceeded
:api	other	Any other non-2xx (403 Pro-gate, 503, …); carries :status + :response-body
:unirate	—	Transport / parse / generic failure (the base type)

Rate limits

The free tier is generous but finite. A 429 surfaces as a :rate-limit error — back off and retry. Historical and time-series endpoints require a Pro plan and return 403 (an :api error with :status 403) on the free tier.

Testing

clojure -M:test          # mock suite (offline)
UNIRATE_API_KEY=… clojure -M:test   # also runs the free-tier live suite

The mock suite injects a stub :transport, so it never hits the network. The live suite self-skips when UNIRATE_API_KEY is unset.

Publishing

Deployment is automated by .github/workflows/release.yml on a vX.Y.Z tag. One-time setup (maintainer):

1. Verify the com.unirateapi group on Clojars (Groups → verify via the unirateapi.com DNS TXT record, or via the GitHub organisation).
2. Create a Clojars deploy token and set the repo secrets CLOJARS_USERNAME and CLOJARS_PASSWORD.

Related clients

Part of the UniRate client family: Python, Node/TypeScript, Go, Rust, Swift, Java, Ruby, PHP, .NET, Dart, D, and more. See github.com/UniRate-API.

License

MIT © 2026 Unirate Team. See LICENSE.