exchange-rate-history
Historical Exchange Rate API
Provides historical exchange rate data for specified currencies over a specific time period. Supports retrieval by month or custom date ranges.
Usage Cost
2 coins/call
Quick Start
Use a unified response envelope and call directly from your backend.
https://openapi.toolkk.com/v1/exchange-rate-historycURL Example
curl --request POST \
--url 'https://openapi.toolkk.com/v1/exchange-rate-history' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: YOUR_API_KEY' \
--data '{\n "code": "货币编号,货币编号或货币名称必须输入其中一个",\n "name": "货币名称,货币编号或货币名称必须输入其中一个",\n "month": "查询年月(yyyyMM),month和startDate、endDate不能同时为空",\n "startDate": "查询起始时间yyyyMMdd,month和startDate、endDate不能同时为空",\n "endDate": "查询结束时间yyyyMMdd,month和startDate、endDate不能同时为空"\n}'Python Example
import os
import requests
url = "https://openapi.toolkk.com/v1/exchange-rate-history"
payload = {
"code": "货币编号,货币编号或货币名称必须输入其中一个",
"name": "货币名称,货币编号或货币名称必须输入其中一个",
"month": "查询年月(yyyyMM),month和startDate、endDate不能同时为空",
"startDate": "查询起始时间yyyyMMdd,month和startDate、endDate不能同时为空",
"endDate": "查询结束时间yyyyMMdd,month和startDate、endDate不能同时为空"
}
headers = {
"Content-Type": "application/json",
"X-API-Key": os.getenv("TOOLKK_API_KEY", "YOUR_API_KEY"),
}
response = requests.request("POST", url, headers=headers, json=payload, timeout=30)
response.raise_for_status()
print(response.json())Go Example
package main
import (
"bytes"
"fmt"
"io"
"net/http"
)
func main() {
endpoint := "https://openapi.toolkk.com/v1/exchange-rate-history"
payload := []byte("{\n \"code\": \"货币编号,货币编号或货币名称必须输入其中一个\",\n \"name\": \"货币名称,货币编号或货币名称必须输入其中一个\",\n \"month\": \"查询年月(yyyyMM),month和startDate、endDate不能同时为空\",\n \"startDate\": \"查询起始时间yyyyMMdd,month和startDate、endDate不能同时为空\",\n \"endDate\": \"查询结束时间yyyyMMdd,month和startDate、endDate不能同时为空\"\n}")
req, err := http.NewRequest("POST", endpoint, bytes.NewBuffer(payload))
if err != nil {
panic(err)
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-API-Key", "YOUR_API_KEY")
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
panic(err)
}
fmt.Println(string(body))
}Java Example
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class ToolkkExample {
public static void main(String[] args) throws Exception {
String payload = "{\n \"code\": \"货币编号,货币编号或货币名称必须输入其中一个\",\n \"name\": \"货币名称,货币编号或货币名称必须输入其中一个\",\n \"month\": \"查询年月(yyyyMM),month和startDate、endDate不能同时为空\",\n \"startDate\": \"查询起始时间yyyyMMdd,month和startDate、endDate不能同时为空\",\n \"endDate\": \"查询结束时间yyyyMMdd,month和startDate、endDate不能同时为空\"\n}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://openapi.toolkk.com/v1/exchange-rate-history"))
.method("POST", HttpRequest.BodyPublishers.ofString(payload))
.header("Content-Type", "application/json")
.header("X-API-Key", "YOUR_API_KEY")
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}PHP Example
<?php
$endpoint = 'https://openapi.toolkk.com/v1/exchange-rate-history';
$payload = "{\n \"code\": \"货币编号,货币编号或货币名称必须输入其中一个\",\n \"name\": \"货币名称,货币编号或货币名称必须输入其中一个\",\n \"month\": \"查询年月(yyyyMM),month和startDate、endDate不能同时为空\",\n \"startDate\": \"查询起始时间yyyyMMdd,month和startDate、endDate不能同时为空\",\n \"endDate\": \"查询结束时间yyyyMMdd,month和startDate、endDate不能同时为空\"\n}";
$ch = curl_init($endpoint);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'X-API-Key: YOUR_API_KEY',
],
CURLOPT_POSTFIELDS => $payload,
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
curl_close($ch);
echo $response;Response Example
{
"msg": "成功",
"code": 200,
"taskNo": "687882815162227863699691",
"data": {
"currencyCode": "USD",
"currencyName": "美元",
"startDate": "20191001",
"endDate": "20191101",
"month": "201910",
"list": [
{
"middle_rate": "705.33",
"selling_rate": "705.55",
"cash_buying_rate": "696.86",
"buying_rate": "702.58",
"cash_selling_rate": "705.55",
"publish_time": "2019-10-31"
},
{
"middle_rate": "705.82",
"selling_rate": "707.26",
"cash_buying_rate": "698.54",
"buying_rate": "704.27",
"cash_selling_rate": "707.26",
"publish_time": "2019-10-30"
}
]
}
}Examples illustrate the response structure. Actual results depend on the API response.
- Authentication
- Send X-API-Key in request headers
- Rate limit
- 600 req/min
- Timeout
- 10000 ms
Send your API Key in the X-API-Key header from your backend.
Check both HTTP status and business fields before treating a call as successful.
Use retries and backoff together with rate limits in high-frequency scenarios.
Request Fields
Send requests from your server with the key in the X-API-Key header.
Request Fields
Fields are read from the API schema. Missing descriptions and examples are marked as unspecified.
| Path | Type | Required | Description | Sample |
|---|---|---|---|---|
| code | string | No | 货币编号,货币编号或货币名称必须输入其中一个 | Unspecified |
| name | string | No | 货币名称,货币编号或货币名称必须输入其中一个 | Unspecified |
| month | string | No | 查询年月(yyyyMM),month和startDate、endDate不能同时为空 | Unspecified |
| startDate | string | No | 查询起始时间yyyyMMdd,month和startDate、endDate不能同时为空 | Unspecified |
| endDate | string | No | 查询结束时间yyyyMMdd,month和startDate、endDate不能同时为空 | Unspecified |
Request Example
{
"code": "货币编号,货币编号或货币名称必须输入其中一个",
"name": "货币名称,货币编号或货币名称必须输入其中一个",
"month": "查询年月(yyyyMM),month和startDate、endDate不能同时为空",
"startDate": "查询起始时间yyyyMMdd,month和startDate、endDate不能同时为空",
"endDate": "查询结束时间yyyyMMdd,month和startDate、endDate不能同时为空"
}- Authentication
- Send X-API-Key in request headers
- Rate limit
- 600 req/min
- Timeout
- 10000 ms
Response Fields
Examples illustrate the response structure. Actual results depend on the API response.
Response Fields
Fields are read from the API schema. Missing descriptions and examples are marked as unspecified.
| Path | Type | Required | Description | Sample |
|---|---|---|---|---|
| msg | string | No | code对应的描述 | 成功 |
| code | number | No | 返回码,详见code返回码说明 | 200 |
| taskNo | string | No | 本次唯一请求号 | 687882815162227863699691 |
| data | object | No | Unspecified | Unspecified |
| data.currencyCode | string | No | 货币编号 | USD |
| data.currencyName | string | No | 货币名称 | 美元 |
| data.startDate | string | No | 开始日期 | 20191001 |
| data.endDate | string | No | 结束日期 | 20191101 |
| data.month | string | No | 结束日期 | 201910 |
| data.list | array | No | Unspecified | [{"middle_rate":"705.33","selling_rate":"705.55","cash_buying_rate":"696.86","buying_rate":"702.58","cash_selling_rate":"705.55","publish_time":"2019-10-31"},{"middle_rate":"705.82","selling_rate":"707.26","cash_buying_rate":"698.54","buying_rate":"704.27","cash_selling_rate":"707.26","publish_time":"2019-10-30"}] |
| data.list[] | object | Unspecified | Unspecified | Unspecified |
Response Example
{
"msg": "成功",
"code": 200,
"taskNo": "687882815162227863699691",
"data": {
"currencyCode": "USD",
"currencyName": "美元",
"startDate": "20191001",
"endDate": "20191101",
"month": "201910",
"list": [
{
"middle_rate": "705.33",
"selling_rate": "705.55",
"cash_buying_rate": "696.86",
"buying_rate": "702.58",
"cash_selling_rate": "705.55",
"publish_time": "2019-10-31"
},
{
"middle_rate": "705.82",
"selling_rate": "707.26",
"cash_buying_rate": "698.54",
"buying_rate": "704.27",
"cash_selling_rate": "707.26",
"publish_time": "2019-10-30"
}
]
}
}Documentation
Capabilities, use cases, and considerations.
API Overview
The Historical Exchange Rate API allows developers to retrieve exchange rate fluctuations for specific currencies over a past period. By providing a currency code or name, along with a target month or custom start and end dates, the API returns detailed daily exchange rate data for that timeframe. This includes the TT (Telegraphic Transfer) buying/selling rates, cash buying/selling rates, and the BOC (Bank of China) conversion rate.
Use Cases
- Financial Settlement & Auditing: Cross-border enterprises can verify historical exchange rates for specific dates during transaction settlements or financial audits.
- Data Analysis & Trend Forecasting: Financial analysts and researchers can use historical forex data for market trend analysis and model building.
- Cross-Border E-Commerce Platforms: Provide users with exchange rate references for historical orders or use the data for internal cost accounting.
- Travel & Currency Exchange Services: Display historical exchange rate trends to help users formulate currency exchange strategies.
Request & Response Details
Request Parameter Highlights:
- You must specify the target currency using either
code(currency code, e.g., USD) or (currency name, e.g., US Dollar). At least one is required.