Official Ruby 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
- Pure stdlib:
net/http+json— zero runtime dependencies
- Ruby 3.0+
Add to your Gemfile:
gem"unirate-api"Then:
bundle installOr install directly:
gem install unirate-apirequire"unirate"client=UniRate::Client.new(api_key: ENV.fetch("UNIRATE_API_KEY"))# Current raterate=client.get_rate(from: "USD",to: "EUR")puts"USD -> EUR: #{rate}"# Converteuros=client.convert(amount: 100,from: "USD",to: "EUR")puts"100 USD = #{euros} EUR"# All supported currenciescurrencies=client.get_supported_currenciesputs"#{currencies.size} currencies supported"Get a free API key at https://unirateapi.com.
All methods use keyword arguments. Currency and country codes are upcased automatically before the request is sent.
# Single pairrate=client.get_rate(from: "USD",to: "EUR")# => Float# All rates for a baserates=client.get_rate(from: "USD")# => Hash{String=>Float}# Convert an amountresult=client.convert(amount: 100,from: "USD",to: "EUR")# => Float# Supported currency listcodes=client.get_supported_currencies# => Array<String>All historical methods require a Pro API key; they raise UniRate::ApiError (with status_code: 403) on the free tier.
# Rate on a specific daterate=client.get_historical_rate(date: "2024-01-01",from: "USD",to: "EUR")# All rates on a daterates=client.get_historical_rates(date: "2024-01-01",base: "USD")# Convert using historical rateamount=client.convert_historical(amount: 100,from: "USD",to: "EUR",date: "2024-01-01")# Time series (up to 5 years)series=client.get_time_series(start_date: "2024-01-01",end_date: "2024-01-07",base: "USD",currencies: ["EUR","GBP"])# Available historical coverage per currencylimits=client.get_historical_limits# All countriesall=client.get_vat_rates# Single country (ISO-3166 alpha-2)germany=client.get_vat_rates(country: "DE")putsgermany["vat_data"]["vat_rate"]# => 19.0All methods raise subclasses of UniRate::Error:
beginrate=client.get_rate(from: "USD",to: "ZZZ")rescueUniRate::AuthenticationError# invalid API key (HTTP 401)rescueUniRate::InvalidCurrencyError# unknown currency code (HTTP 404)rescueUniRate::RateLimitError# back off and retry (HTTP 429)rescueUniRate::InvalidDateError# bad date format or bad request (HTTP 400)rescueUniRate::ApiError=>e# other HTTP error — e.status_code, e.responseend| Status | Error class |
|---|---|
| 400 | UniRate::InvalidDateError |
| 401 | UniRate::AuthenticationError |
| 403 | UniRate::ApiError (status 403 — Pro-only endpoint) |
| 404 | UniRate::InvalidCurrencyError |
| 429 | UniRate::RateLimitError |
| 503 | UniRate::ApiError (status 503) |
| other | UniRate::ApiError |
| network | UniRate::Error (base) |
The client uses Net::HTTP directly, so WebMock stubs requests transparently in tests:
require"webmock/rspec"require"unirate"stub_request(:get,"https://api.unirateapi.com/api/rates").with(query: hash_including("from"=>"USD","to"=>"EUR")).to_return(status: 200,body: {rate: "0.9321"}.to_json)client=UniRate::Client.new(api_key: "test")rate=client.get_rate(from: "USD",to: "EUR")# => 0.9321Run the suites in this repo:
bundle exec rspec spec/client_spec.rb # ~14 WebMock-based mock tests
UNIRATE_API_KEY=your-key bundle exec rspec spec/live_spec.rb # live (free-tier only)- Currency endpoints: standard rate limits apply
- Historical endpoints: 50 requests/hour on the free tier
- VAT endpoints: 1800 requests/hour on the free tier
- unirate-api-python (PyPI:
unirate-api) - unirate-api-nodejs (npm:
unirate-api) - unirate-api-swift (Swift Package Manager)
UniRate ships official integrations for 40+ ecosystems, all maintained under the UniRate-API org.
Core clients (9 languages)Python · Node.js / TypeScript · Go · Rust · Java · Ruby · PHP · .NET · Swift
JavaScript / TypeScriptReact · Next.js · Remix · SvelteKit · Vue · Angular · Nuxt · NestJS · tRPC
Static-site generatorsAstro · Eleventy · Hugo · Jekyll
CMS & e-commerceWagtail · WordPress · WooCommerce · Drupal · Strapi · Medusa · Symfony · Laravel · Directus
Data, AI & backendLangChain (Python) · LangChain.js · FastAPI · Flask · Django REST Framework · Apache Airflow · dbt
Platform & toolsMCP server · CLI · Cloudflare Workers · Home Assistant · n8n · Google Sheets · VS Code · Obsidian
Money library bridgesmoney gem (Ruby) · NodaMoney (.NET)
Get a free API key at unirateapi.com.
MIT — see LICENSE.