---
title: "Currency Converter Widget — AllRatesToday Documentation"
description: "Embed a free currency converter on any website with one line of code. No API key needed — official ECB reference rates keyless, real-time mid-market rates with a free key. JavaScript and iframe embeds, full attribute reference."
canonical: https://allratestoday.com/docs/widget/
source: AllRatesToday (https://allratestoday.com/) — Markdown mirror of the page above; index of all pages at https://allratestoday.com/llms.txt
generated: 2026-10-23T08:34:27.138Z
---

# Currency Converter Widget — AllRatesToday Documentation

Embed a free currency converter on any website with one line of code. No API key needed — official ECB reference rates keyless, real-time mid-market rates with a free key. JavaScript and iframe embeds, full attribute reference.

By [Madhushan](https://allratestoday.com/authors/madhushan/), Founder & Lead Developer

  **No API key needed.** Keyless embeds use our [open central-bank endpoint](https://allratestoday.com/official-rates-widget/) (official ECB reference rates, updated daily, 30+ major currencies) — just keep the "Exchange rates by AllRatesToday" attribution link visible. Add a [free API key](https://allratestoday.com/register) for real-time mid-market rates across 150+ currencies, dedicated quota and usage stats in your dashboard.

# Currency Converter Widget

A drop-in currency converter you can embed on any website. Keyless it shows official ECB reference rates (updated each business day, 30+ major currencies); with a free API key it uses the same real-time mid-market rates as the AllRatesToday API across 150+ currencies. It isolates its styles (Shadow DOM) so it never clashes with your page's CSS. There's also a live preview on the [widget page](https://allratestoday.com/widget/).

## JavaScript embed (recommended)

Paste this where you want the converter to appear — it works immediately, no signup:

```
<!-- AllRatesToday currency converter (no API key needed) -->
<div class="art-currency-widget" data-base="USD" data-target="EUR"></div>
<a href="https://allratestoday.com">Exchange rates by AllRatesToday</a>
<script async src="https://allratestoday.com/widget.js"></script>
```

## iframe embed

No JavaScript required — works on any CMS, including ones that strip scripts:

```
<iframe
  src="https://allratestoday.com/embed/converter?base=USD&target=EUR&theme=light"
  width="400" height="320" frameborder="0" loading="lazy"
  title="Currency converter by AllRatesToday"></iframe>
```

## Attributes

| Attribute | Default | Description |
| --- | --- | --- |
| `data-api-key` | — | Optional. Your API key for real-time mid-market rates, 150+ currencies, dedicated quota + stats (use `key=` on the iframe URL) |
| `data-base` | `USD` | Starting "from" currency (ISO 4217) |
| `data-target` | `EUR` | Starting "to" currency (ISO 4217) |
| `data-amount` | `1` | Starting amount |
| `data-theme` | `light` | `light` or `dark` |

## Optional: add a free API key

Without a key the widget uses daily official ECB reference rates from the edge-cached open endpoint. With a [free key](https://allratestoday.com/register) (`data-api-key="art_live_…"`) it switches to real-time mid-market rates across 150+ currencies, conversions run on your plan's dedicated quota and show up in your [dashboard](https://allratestoday.com/dashboard) — see [pricing](https://allratestoday.com/pricing).

## The endpoints it calls

The widget is a thin client. Keyless embeds call the [open central-bank endpoint](https://allratestoday.com/official-rates-widget/) (`GET /api/open/central-bank/ecb?source=USD&target=EUR`, no key); keyed embeds call the keyed endpoint below. You can call either directly if you'd rather build your own UI:

```
GET https://allratestoday.com/api/widget/rate?source=USD&target=EUR&key=YOUR_API_KEY
```

Response:

```
{ "rate": 0.8663, "source": "mid-market" }
```

The key may also be sent as a header: `Authorization: Bearer YOUR_API_KEY`. The endpoint sends `Access-Control-Allow-Origin: *`, so it works from the browser on any domain.

## Error responses

| Status | Meaning | Widget shows |
| --- | --- | --- |
| `400` | Missing `source` or `target` | — |
| `401` | Invalid or disabled API key (keyed mode only) | "Invalid API key" + register link |
| `404` | Pair not in the ECB table (keyless mode only) | "Pair not covered" + free-key link |
| `429` | Monthly request limit exceeded | "Monthly limit reached" + upgrade link |
| `502` | Upstream rate provider error | "Rate unavailable" |

## A note on key visibility

Because the widget runs in the browser, the API key is visible in your page's source — this is normal for client-side keys. Usage is always counted against your quota, and you can disable or rotate a key anytime from the [dashboard](https://allratestoday.com/dashboard). For server-to-server use, keep your key on the backend and call the [authenticated rates endpoint](https://allratestoday.com/docs/#auth-rates) instead.

## License & attribution

The widget script is MIT-licensed. The "Exchange rates by AllRatesToday" link **must remain visible** on keyless embeds — it's how we keep the open endpoint free for everyone. Keyed embeds are welcome to keep it too.