Check foreign exchange rates

A foreign exchange (FX) rate is a rate at which one currency is exchanged for another. For example, an exchange rate of 114 Japanese Yen to the US Dollar means that ¥114 can be bought for US$1, or US$1 can be bought for ¥114.

Currencycloud provides two web services for checking foreign exchange rates. In this cookbook, you will:

  • 1. Use Currencycloud’s basic rate lookup service to get basic foreign exchange rate information for a pair of currencies.
  • 2. Use Currencycloud’s detailed rate lookup service to get a full quotation for converting money from one currency to another.

Step 1: Login

Please refer to the Authentication cookbook for instructions to start a new API session.

Step 2: Get basic exchange rate information

Currencycloud’s Get Basic Rates endpoint provides real-time exchange rate data.

Quotes are given on currency pairs. A currency pair is two standard currency codes joined together: “EURUSD”, “GBPUSD”, “GBPJPY”, etc. The first currency in the pair is the base currency. The second is the quote currency. The result indicates how much of the quote currency is needed to buy one unit of the base currency.

For example, to find out how many Pound Sterling (GBP) are needed to buy EUR €1.00, make the following HTTP call. Note the use of the currency pair “EURGBP” in the query string.

GET /v2/rates/find?currency_pair=EURGBP
X-Auth-Token: ea6d13c7bc50feb46cf978d137bc01a2

If exchange rate information is available for the requested currency pair, you’ll get a response similar to the following.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "rates": {
    "EURGBP": [
      "0.805300",
      "0.805900"
    ]
  },
  "unavailable": []
}

The two rates in the response are the “bid” and “offer” prices. The bid price is applicable if you are selling the base currency. The offer rate is applicable if you are buying the base currency. So:

  • 1. Selling EUR €1,000.00 would buy GBP £805.30.
  • 2. To buy EUR €1,000.00 you would need to sell GBP £805.90.

Step 3: Get a detailed quote

To find out exactly how much it will cost you to trade funds in one currency for another, use Currencycloud’s Get Detailed Rates endpoint. For example, to get a quote buy 10,000 Euros using funds from your Pound Sterling balance, make the following call:

GET /v2/rates/detailed

Parameter Name Parameter Type Example Value
buy_currency Query String EUR
sell_currency Query String GBP
amount Query String 10000.00
fixed_side Query String buy
X-Auth-Token Header ea6d13c7bc50feb46cf978d137bc01a2

On success, the response payload will contain details of Currencycloud’s quotation to make the conversion. The following example tells you that you can sell GBP £8,059 to buy EUR €10,000. The quote is valid until 1pm on 5 June 2018 (UTC time).

HTTP/1.1 200 OK
Content-Type: application/json

{
  "settlement_cut_off_time": "2018-06-05T13:00:00Z",
  "currency_pair": "EURGBP",
  "client_buy_currency": "EUR",
  "client_sell_currency": "GBP",
  "client_buy_amount": "10000.00",
  "client_sell_amount": "8059.00",
  "fixed_side": "buy",
  "client_rate": "0.8059",
  "partner_rate": null,
  "core_rate": "0.8059",
  "deposit_required": false,
  "deposit_amount": "0.0",
  "deposit_currency": "GBP",
  "mid_market_rate": "0.8056"
}

When you fetch exchange rate information from the Get Basic Rates endpoint, the returned currency pair string will match exactly the value of the currency_pair input parameter. However, when you get a quote from the Get Detailed Rates endpoint, the value of the currency_pair property in the response will be standardised, adhering to market conventions for currency pair notation.

It is conventional to represent a pairing of Euros to Pound Sterling as “EURGBP”, never “GBPEUR”, regardless which of the two currencies you are buying and selling. By default, the least valuable currency is the second unit in a currency pair. But there are some exceptions. If any of the following currencies are quoted against each other, then the currency appearing first in the list will be the first in the currency pair.

  • – EUR
  • – GBP
  • – AUD
  • – NZD
  • – USD
Was this page helpful?
Yes
No