exchangerate.devA realised foreign exchange gain or loss is the difference between the home-currency value at booking and at settlement. The gain-loss endpoint values both dates using the same official table for a receivable or payable.
- A realised gain or loss compares the value at booking with the value at settlement.
- Use the same official table to value both dates.
- Keep the lookup ID to retrieve the answer's publication evidence.
Compare booking and settlement values
A foreign-currency receivable or payable has a home-currency value when booked and a home-currency value when settled.
The difference is a realised foreign exchange gain or loss. Identify whether the amount is a receivable or payable when requesting the calculation.
Calculate at the official rate
POST /v1/official/{country}/{type}/gain-loss calculates the realised gain or loss in the home currency. It requires Pro.
Supply currency, amount, booked_on, settled_on and kind. Set kind to receivable or payable.
The endpoint values both dates at the selected table's official rate.
Use the same table for both dates
The country and type in the endpoint select one table for the calculation. That table supplies the rate valid on the booking date and the rate valid on the settlement date.
Using the same table keeps the comparison tied to one authority's table across both dates. Mixing tables would also change the basis of the comparison.
Keep evidence for the calculation
On Pro, each answer carries an X-Lookup-Id header. Keep that identifier with the calculation.
GET /v1/official/evidence/{lookup_id} returns what was answered, when and from which publication.
For the underlying rates, a date lookup with expand=source provides the exact printed value and units, publication number, publication date, source document URL and retrieval time. Corrections create new versions, and superseded versions are kept.