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

# Exchange Rates

> Look up the daily rate between two currencies

An exchange rate tells you how many units of one currency equal one unit of another on a given date.

Supported currencies are listed in [Currencies](https://docs.numeral.com/essentials/currencies.md#supported-currencies-by-api-version).

Endpoints
[Retrieve an exchange rateGET/tax/exchange\_rates](#retrieve-an-exchange-rate)

## The Exchange rate object

### Attributes

**object** `string, value is "tax.exchange_rate"`

String representing the object's type.

**date** `string`

The date of the rate, `YYYY-MM-DD` (UTC).

**base\_currency** `string`

ISO 4217 code of the currency converted from, in uppercase.

**target\_currency** `string`

ISO 4217 code of the currency converted to, in uppercase.

**rate** `number`

Units of `target_currency` per 1 unit of `base_currency`. Not rounded. `1` when both currencies are the same.

For weekends and market holidays, the rate is from the most recent trading day.

```json The Exchange rate object theme={null}
{
  "object": "tax.exchange_rate",
  "date": "2026-09-30",
  "base_currency": "USD",
  "target_currency": "EUR",
  "rate": 0.861245
}
```

## Retrieve an exchange rate

Returns the rate between two currencies on a date. [Try it in the API reference](https://docs.numeral.com/api-reference/v2026-03-01/endpoint/get_exchange_rate).

### Parameters

**date** `string` *required*

The date, `YYYY-MM-DD` (UTC). Can't be later than today in UTC.

**base\_currency** `string` *required*

ISO 4217 code of the currency to convert from, e.g. `USD`. Case-insensitive.

**target\_currency** `string` *required*

ISO 4217 code of the currency to convert to, e.g. `EUR`. Case-insensitive.

Any other query parameter returns `UNRECOGNIZED_FIELD`.

### Returns

An [Exchange rate object](#the-exchange-rate-object). Currency codes come back in uppercase, whatever case you sent.

```bash GET /tax/exchange_rates theme={null}
curl 'https://api.numeralhq.com/tax/exchange_rates?date=2026-09-30&base_currency=USD&target_currency=EUR' \
  -H 'Authorization: Bearer <token>' \
  -H 'X-API-Version: 2026-03-01'
```

```json Response theme={null}
{
  "object": "tax.exchange_rate",
  "date": "2026-09-30",
  "base_currency": "USD",
  "target_currency": "EUR",
  "rate": 0.861245
}
```

## Errors

Errors return `code`, `type`, and `message`. Handle them by `type`. Full list in [Error Codes](https://docs.numeral.com/api-reference/v2026-03-01/error-codes.md).

Checks run in the order below. If a request has more than one error, only the first is returned.

| HTTP | `type` | When |
| - | - | - |
| 400 | `UNRECOGNIZED_FIELD` | A query parameter other than `date`, `base_currency`, or `target_currency` was sent. |
| 400 | `MISSING_FIELD` | A required query parameter is missing or empty. |
| 400 | `INVALID_DATE` | `date` isn't a valid calendar date in `YYYY-MM-DD` format. |
| 400 | `DATE_OUT_OF_RANGE` | `date` is later than today in UTC. |
| 400 | `INVALID_CURRENCY_CODE` | `base_currency` or `target_currency` isn't a three-letter code. |
| 400 | `UNSUPPORTED_CURRENCY_CODE` | `base_currency` or `target_currency` isn't a [supported currency](https://docs.numeral.com/essentials/currencies.md#supported-currencies-by-api-version). |
| 404 | `EXCHANGE_RATE_NOT_FOUND` | No rate is available for the currency pair on that date. |

```json Date out of range theme={null}
{
  "code": 400,
  "type": "DATE_OUT_OF_RANGE",
  "message": "date 2099-01-01 is in the future. Latest available date is 2026-10-20 (today, UTC)."
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.