Get a detailed, tradeable rate quote to convert money from one currency to another. The quotation provided will be based on the spread table of the authenticated user. There is also the option to provide a specific date for the conversion to occur.

This endpoint provides a current tradeable rate for a single currency pair. It should be used as the start of the flow before a conversion is booked. This endpoint should be used where accuracy is the most important aspect, such as when a trade is about to be booked.

The API responses shown below are static. If you want to try out the API please login, or register for an API key

API parameters

X-Auth-Token header string Authentication token.
buy_currency query string Currency purchased. Three-digit code.
sell_currency query string Currency sold. Three-digit code.
fixed_side query string Fix the buy or sell currency. buy
amount query string Amount of the fixed buy or sell currency.
on_behalf_of query string A contact UUID for the sub-acccount you're acting on behalf of.
conversion_date query string Date of delivery of purchase currency. ISO 8601 format YYYY-MM-DD. If not specified, deals settle in two working days. date
conversion_date_preference query string Available only if conversion_date is not provided. Must be one of the following:
'earliest' for earliest available conversion date. Make sure there is sufficient time to send funds to Currencycloud.
'next_day' for next day available conversion date - T+1.
'default' for conversion - T+1 for APAC, T+2 for everywhere else.
'optimize_liquidity' for maximizing chances of getting a successful rate. Most relevant for exotic pairs. Conversion is within 1 or 2 working days depending on currencies.
curl -X GET  --header "X-Auth-Token: XXXX-XXXXX-XXXX"  https://devapi.currencycloud.com/v2/rates/detailed


    "settlement_cut_off_time": "2022-02-02T15:00:00Z",
    "currency_pair": "GBPUSD",
    "client_buy_currency": "GBP",
    "client_sell_currency": "USD",
    "client_buy_amount": "100.0",
    "client_sell_amount": "140.81",
    "fixed_side": "buy",
    "client_rate": "1.4081",
    "partner_rate": null,
    "core_rate": "1.4081",
    "deposit_required": false,
    "deposit_amount": "0.0",
    "deposit_currency": "USD",
    "mid_market_rate": "1.408"
Error Codes
HTTP Status Code Description Params
400 unique_value_parameters Following parameters should not have same values: sell_currency, buy_currency { "parameters" => "sell_currency, buy_currency" }
rate_could_not_be_retrieved Rate could not be retrieved
ccy_pair_is_not_tradeable Given currency pair is not tradeable
fixed_side_not_in_range fixed_side should be in range: sell, buy { "range" => "sell, buy" }
fixed_side_is_required fixed_side is required
conversion_date_type_is_wrong conversion_date should be of date type { "type" => "date" }
invalid_delivery_date The delivery date you have requested cannot be met for this currency pair
sell_currency_is_in_invalid_format sell_currency is in invalid format
sell_currency_is_required sell_currency is required
currency_pair_not_available_for_weekend Currency pair is not available for weekend
amount_type_is_wrong amount should be of numeric type { "type" => "numeric" }
amount_is_required amount is required
amount_is_too_small amount can not be smaller than 1 { "minvalue" => 1 }
buy_currency_is_in_invalid_format buy_currency is in invalid format
buy_currency_is_required buy_currency is required
on_behalf_of_self You cannot act on behalf of your own Contact
contact_not_found Contact was not found for this id
amount_is_in_invalid_format amount should be of numeric type with 2 dp { "type" => "numeric_with_precision", "precision" => 2 }
invalid_conversion_date_combination conversion_date_preference can not be specified along side a date parameter
invalid_conversion_date_preference not a valid conversion date preference, possible options are earliest, optimize_liquidity, default, next_day
401 invalid_supplied_credentials Authentication failed with the supplied credentials
429 too_many_requests Too many requests have been made to the api. Please refer to the Developer Center for more information
500 internal_server_error Internal server error
503 service_unavailable Service is temporary unavailable
Was this post helpful?
Let us know if you liked the post. That’s the only way we can improve.