Get Historical Rate

Query the rate history of a currency pair so the Merchant can reconcile and analyse past quotes. Historical rates are retained for at least 2 months.

The API supports two modes:

• Single day (type = 1) — return the rate snapshots recorded on a given date.
• Date range (type = 2) — return the daily average rate for each day in a date range.

Path

• URL: /cb-core/api/v1/fx/get-historical-rate
• Method: POST
• Description: Query the rate history of a currency pair.

Request

Request table

Params	Data Type	Required	Description
request_id	string(50)	Yes	Unique code that identifies the request. Suggested format: MerchantCode + BK + YYYYMMDD + UniqueId
request_time	string(19)	Yes	Time the Merchant sends the request. Format: YYYY-MM-DD HH:MM:SS
merchant_code	string(20)	Yes	Merchant code provided by Baokim before integration
type	int(1)	Yes	Query mode. 1: rate snapshots on a single date. 2: daily average rate over a date range
from_currency	string(10)	Yes	The foreign currency code (e.g. USD). Only one currency code is allowed
to_currency	string(10)	Yes	The quote currency code (e.g. VND). Only one currency code is allowed
date	string(21)	Yes	When type = 1: a single date YYYY-MM-DD. When type = 2: a date range start_date,end_date, e.g. 2026-04-01,2026-06-01

Request Example — type = 1

{
  "request_id": "MERCHANT1234BK202606054",
  "request_time": "2026-06-05 10:15:30",
  "merchant_code": "MERCHANT1234",
  "type": 1,
  "from_currency": "USD",
  "to_currency": "VND",
  "date": "2026-06-01"
}

Request Example — type = 2

{
  "request_id": "MERCHANT1234BK202606055",
  "request_time": "2026-06-05 10:15:30",
  "merchant_code": "MERCHANT1234",
  "type": 2,
  "from_currency": "USD",
  "to_currency": "VND",
  "date": "2026-04-01,2026-06-01"
}

Response

Response Table

Params	Data Type	Required	Description
response_code	int(4)	Yes	Result code from Baokim, as per the Error Codes table
response_message	string(200)	Yes	Description of the result code
merchant_code	string(20)	Yes	Merchant code provided by Baokim before integration
data	Object	Yes	Historical rate result

Data Object Structure (inside data)

Params	Data Type	Description
currency_pair	string(10)	Currency pair in BASE/QUOTE format (e.g. USD/VND)
type	int(1)	The query mode echoed back (1 or 2)
result	Array of Objects	List of historical rate points

result Array Structure

Params	Data Type	Description
timestamp	string(19)	When type = 1: the snapshot time YYYY-MM-DD HH:MM:SS. When type = 2: the date YYYY-MM-DD
bid	decimal(18,4)	Buying rate at that point (daily average when type = 2)
ask	decimal(18,4)	Selling rate at that point (daily average when type = 2)

Response Example — type = 1

{
  "response_code": 200,
  "response_message": "Success",
  "merchant_code": "MERCHANT1234",
  "data": {
    "currency_pair": "USD/VND",
    "type": 1,
    "result": [
      { "timestamp": "2026-06-01 08:00:00", "bid": 26400.0000, "ask": 26460.0000 },
      { "timestamp": "2026-06-01 09:00:00", "bid": 26430.0000, "ask": 26490.0000 },
      { "timestamp": "2026-06-01 10:05:00", "bid": 26445.0000, "ask": 26505.0000 },
      { "timestamp": "2026-06-01 15:00:00", "bid": 26460.0000, "ask": 26520.0000 }
    ]
  }
}

Response Example — type = 2

{
  "response_code": 200,
  "response_message": "Success",
  "merchant_code": "MERCHANT1234",
  "data": {
    "currency_pair": "USD/VND",
    "type": 2,
    "result": [
      { "timestamp": "2026-04-01", "bid": 26200.1500, "ask": 26260.4500 },
      { "timestamp": "2026-04-02", "bid": 26250.1000, "ask": 26310.2000 },
      { "timestamp": "2026-04-03", "bid": 26255.2341, "ask": 26315.6300 }
    ]
  }
}

Error Code

Response Code	Response Message
200	Success
101	System Error
110	Merchant Code Invalid
120	Invalid Signature
404	Currency Pair Not Supported
422	Validation Error
429	Too Many Requests