---
title: Historical Currency Converter API Reference
version: 1.0.0
description: Convert an amount from one currency to another using exchange rates from a specific historical date. Supports fiat, crypto, and metals. Returns the date, source and target currencies, the historical rate, and the converted amount. All parameters are case-insensitive for both fiat/currency codes and crypto/symbols.
openapi: 3.1.1
servers:
  - https://api.apifreaks.com/v1.0
paths: 1
operations: 1
schemas: 2
---

## Table of Contents

- [Historical Currency Converter API Reference v1.0.0](#historical-currency-converter-api-reference-v100)
  - [Authentication](#authentication)
  - [Currency APIs](#currency-apis)
    - [convertHistorical](#converthistorical)
      - [Parameters](#parameters)
      - [Responses](#responses)
  - [Schemas](#schemas)
    - [HistoricalCurrencyConverterResponse](#historicalcurrencyconverterresponse)
    - [ErrorResponse](#errorresponse)



# Historical Currency Converter API Reference v1.0.0

Convert an amount from one currency to another using exchange rates from a specific historical date. Supports fiat, crypto, and metals. Returns the date, source and target currencies, the historical rate, and the converted amount. All parameters are case-insensitive for both fiat/currency codes and crypto/symbols.

Base URLs:

* [https://api.apifreaks.com/v1.0](https://api.apifreaks.com/v1.0)

## Authentication

* API Key (ApiKeyAuthHeader)
    - Parameter Name: **X-apiKey**, in: header. Pass your API key via the X-apiKey request header.

* API Key (ApiKeyAuthQuery)
    - Parameter Name: **apiKey**, in: query. Pass your API key via the apiKey query parameter.

## Currency APIs

### convertHistorical

`GET /currency/converter/historical/prices`

*Convert currency with historical rates*

Converts an amount using exchange rates from a specific historical date.

#### Parameters

|Name|In|Type|Required|Description|
|---|---|---|---|---|
|format|query|string|false|Response format: `json` (default) or `xml`.|
|from|query|string|true|Source currency code.|
|to|query|string|true|Target currency code.|
|amount|query|number(float)|false|Amount to convert, as a decimal. Defaults to `1`. Must be numeric — non-numeric values return a 400 (negative values are accepted despite the error message's wording).|
|date|query|string|true|Historical date in `YYYY-MM-DD` format.|

##### Enumerated Values

|Parameter|Value|
|---|---|
|format|json|
|format|xml|

> Example responses

> Successful operation

```json
{
  "date": "2025-01-10",
  "from": "USD",
  "to": "EUR",
  "rate": "0.97620",
  "givenAmount": "100.0",
  "convertedAmount": "97.620"
}
```

> Bad request - Invalid amount or date format

```json
{
  "error": "Invalid Param Exception",
  "message": "please pass correct parameters",
  "path": "/v1.0/currency/converter/historical/prices",
  "status": 400,
  "timestamp": "2026-07-27T12:07:03.772Z"
}
```

```json
{
  "timestamp": 1785154024296,
  "status": 400,
  "error": "Method Argument Type Mismatch",
  "message": "Invalid Amount. Please provide amount in decimal format and greater than 0!",
  "path": "/v2.0/convert/historical"
}
```

```json
{
  "timestamp": 1785154024931,
  "status": 400,
  "error": "Invalid Param Exception",
  "message": "Provided Date 10-01-2025 is in invalid format. It should be like  YYYY-MM-DD!",
  "path": "/v2.0/convert/historical"
}
```

> Not found - Currency or date not available

```json
{
  "timestamp": 1785154025547,
  "status": 404,
  "error": "Not Found Exception",
  "message": "Rates of provided date 2099-01-01 are not available in our database.",
  "path": "/v2.0/convert/historical"
}
```

```json
{
  "timestamp": 1785154026188,
  "status": 404,
  "error": "Not Found Exception",
  "message": "Rates of provided currency ZZZ are not available in our database!",
  "path": "/v2.0/convert/historical"
}
```

#### Responses

|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successful operation|[HistoricalCurrencyConverterResponse](#historicalcurrencyconverterresponse)|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad request - Invalid amount or date format|[ErrorResponse](#errorresponse)|
|404|[Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)|Not found - Currency or date not available|[ErrorResponse](#errorresponse)|

#### Response Headers

|Status|Header|Type|Format|Description|
|---|---|---|---|---|
|200|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|400|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|404|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|

To perform this operation, you must be authenticated by means of one of the following methods:
ApiKeyAuthHeader, ApiKeyAuthQuery

## Schemas

### HistoricalCurrencyConverterResponse

Historical currency conversion response containing the historical rate and converted amount.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|date|string|true|none|Date and time with timezone (UTC) when the rate was recorded.|
|from|string|true|none|Source currency code.|
|to|string|true|none|Target currency code.|
|rate|string|true|none|Conversion rate from source to target currency.|
|givenAmount|string|true|none|The amount provided for conversion.|
|convertedAmount|string|true|none|The converted amount in the target currency.|

### ErrorResponse

Standard error envelope returned by the API on failed requests. Gateway-level validation errors use an ISO 8601 timestamp and the public endpoint path; currency-service errors use a Unix millisecond timestamp and an internal service path instead.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|timestamp|string | integer|false|none|Timestamp when the error occurred — ISO 8601 string for gateway errors, Unix milliseconds integer for currency-service errors.|
|status|integer|false|none|HTTP status code returned with the error.|
|error|string|false|none|Specific error type (e.g., Invalid Param Exception, Method Argument Type Mismatch, Not Found Exception).|
|message|string|true|none|Human-readable error message describing the failure.|
|path|string|false|none|API endpoint path (gateway errors) or internal service path (currency-service errors) that produced the error.|