> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bunny.build/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /currency-exchange

> Get real-time exchange rates between 160+ currencies, with the current mid-market rate, converted amount, and last-update timestamp.

## Endpoint

```
GET https://api.bunny.build/api/v1/currency-exchange?from=USD&to=BRL&amount=100
```

## Authentication

| Header      | Required | Value                    |
| ----------- | -------- | ------------------------ |
| `X-API-Key` | Yes      | Your API key (`bun_...`) |

## Overview

Get real-time exchange rates between any two currencies. Bunny's Currency Exchange API supports 160+ currencies and returns the current mid-market rate, the converted amount, and the timestamp of the last rate update.

## Use cases

* Display prices in the visitor's local currency
* Process multi-currency payments and invoices
* Build currency converter widgets
* Sync inventory prices across markets

## Details

Rates are refreshed frequently and cached for up to 60 minutes. Provide `from` and `to` as ISO 4217 currency codes (e.g. `USD`, `BRL`, `EUR`). Optionally pass `amount` to get a converted value directly.

## Query parameters

| Parameter | Type   | Required | Description                                 |
| --------- | ------ | -------- | ------------------------------------------- |
| `from`    | string | Yes      | Source currency code (ISO 4217, e.g. `USD`) |
| `to`      | string | Yes      | Target currency code (ISO 4217, e.g. `BRL`) |
| `amount`  | number | No       | Amount to convert (default: `1`)            |

## Response

### 200 OK

| Field        | Type   | Description                                                                   |
| ------------ | ------ | ----------------------------------------------------------------------------- |
| `from`       | string | Source currency code                                                          |
| `to`         | string | Target currency code                                                          |
| `rate`       | number | Exchange rate (1 unit of `from` expressed in `to`)                            |
| `amount`     | number | The amount that was converted (mirrors the `amount` query param, default `1`) |
| `converted`  | number | Result of `amount * rate`, rounded to 6 decimal places                        |
| `updated_at` | string | Timestamp of the last rate update (from the upstream provider)                |

**Example**

```json theme={null}
{
  "from": "USD",
  "to": "BRL",
  "rate": 5.423100,
  "amount": 100,
  "converted": 542.31,
  "updated_at": "Mon, 23 Jun 2025 00:02:01 +0000"
}
```

### 401 Unauthorized

```json theme={null}
{
  "detail": "Missing API key. Include X-API-Key header."
}
```

### 402 Payment Required

```json theme={null}
{
  "detail": "Monthly quota exceeded. Upgrade your plan."
}
```

### 422 Unprocessable Entity

Invalid currency code.

```json theme={null}
{
  "detail": "Invalid currency code"
}
```

### 429 Too Many Requests

```json theme={null}
{
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}
```

## cURL example

```bash theme={null}
curl "https://api.bunny.build/api/v1/currency-exchange?from=USD&to=BRL&amount=100" \
  -H "X-API-Key: bun_your_api_key"
```