Global rates
The Conversion Extension fetches a list of exchange rates from Open Exchange Rates every 5 minutes. The Conversion Extension also stores a history of rates between currencies (for the recent past, it stores the rates for every 5 minutes. After 7 days it only stores one rate per hour per day).
When you activate the Conversion Extension, it automatically adds a list of global rates (updated every 5 mins) which allows the wallet apps to display the value of currencies in a user’s accounts in their chosen display currency e.g. showing what their EUR account balance is in USD. Whenever a value in the wallet apps is converted for display in a different currency, the wallet apps will always use a global rate for this calculation unless a custom rate overrides it.
Custom rate pairs
Custom rate pairs are comprised of a “from” and “to" currency and are defined in relation to a base currency, which in Rehive is always USD. Once the USD base rate is set, the Conversion Extension will use the base USD rate to work out all other rates between your custom rate currency and all other currencies.
You can override a global rate using a custom rate pair. With a custom rate pair, you can directly modify the rate or how the rate is calculated. If a custom rate pair exists, the wallet apps will use the rate value from the custom rate pair instead of the global rates for display. Custom rate pairs do not allow for currency exchange transactions - for that you need to set up Conversion Pairs.
Custom rate pairs can be used to define a rate between “from” and “to” currencies which are not included in the global rate pairs list e.g. between USD and a custom points currency. To set a custom rate for a custom points currency to be 1/100th the value of USD you would create a custom rate pair and set the rate to 0.01.
Path
You can use the path functionality in custom rate pairs to make the rate of a custom rate pair track the rate of another global or custom rate pair e.g. to make testnet bitcoin’s exchange rate to USD track the same rate as livenet bitcoin to USD. This path would simply be USD:XBT
Conversion pairs
In order to allow users to make conversion transactions in the wallet, admins need to create conversion pairs. Conversion pairs define:
Which currencies users can convert between (the "from currency" and "to currency").
In which direction conversions can be done i.e. from USD to EUR, or from EUR to USD. In order to allow users to convert both ways, two separate sets of conversion pairs would need to be set up.
Conversion pairs can be configured to calculate the conversion rate between the two currencies in 3 ways:
Auto - The rate will automatically be retrieved from an available global or custom rate pair e.g. a conversion pair of USD:ZAR will use the rate of the global rate pair USD:ZAR, unless a custom one has been specified which would override the global rate pair. This will be the most commonly used setting.
Rate - Set a fixed value rate. This will ignore any rate between global or custom rate pairs and only use this value always for conversion transactions.
Path - This is an advanced field. It can be used to dynamically calculate a rate based on an expression. The expression can be either a basic mathematical expression or can combine mathematical expressions and functions defined by Rehive.
Please contact Rehive if you would like assistance with paths. Here are some examples to help you get started:
Getting the rate for converting from EUR to ZAR |
|
This path emulates what happens when “Auto” is selected for the currency pair EUR:ZAR. It first gets the ZAR to USD rate, then gets the EUR to USD rate, and derives the EUR to ZAR rate by dividing the ZAR to USD rate by the EUR to USD rate. This happens because Rehive’s base currency for rates is USD. |
Bonus or more favorable rates |
|
This path is an example of USD:ZAR + a fixed value. It pads the rate by 1. e.g. if the rate for USD to ZAR is 17.05, the above path would output a rate of 18.05. The user would get 1 more ZAR than they would get from the regular rate. This acts like a bonus.
To make a less favorable rate, change the |
Less favorable rate |
|
This path would make the rate between USD and ZAR be 98% of the actual rate. You might do this if you wanted the user to get less ZAR from their USD than they would from the regular rate.
If the original rate for USD to ZAR is 17.05, this path would output a rate of 16.70, meaning the user would get less ZAR for their USD. |
Complicated more favorable rate |
|
This path first calculates the rate of EUR to ZAR by getting the USD:ZAR rate and dividing it by the USD:EUR rate (because the base rate is always in USD):
To create a less favorable rate where the user would get less ZAR for their EUR, change the |
Quote duration
When creating a conversion pair an admin can stipulate a quote duration. This is the period of time for which a rate will remain fixed while the user decides if they want to complete the transaction. The default duration is 10 minutes if a duration is not specified.
Operational account
When creating a conversion pair an admin must set an operational account which will be used to facilitate the conversions. This account should have a healthy balance of the currencies that will be converted between. The below example will illustrate how the Conversion Extension uses the operational account:
A user wants to convert 1 USD to EUR. The quoted rate is 1 EUR for 1.1669 USD. If they convert their 1 USD they will receive 0.86 EUR. They accept the conversion quote. The Conversion Extension makes the following transactions in order to facilitate the conversion:
First, a debit of the user’s USD account for 1 USD and a credit to the operational account for 1 USD.
Second, a debit on the operational account for 0.86 EUR and a credit to the user’s EUR account for 0.86 EUR.
The user wanting to do the conversion and the operational account facilitating the conversion both need to have an account with EUR and USD currencies.
Conversions
Conversions are a list of complete or quoted conversions. A quoted conversion is either a currently pending conversion which has not yet been completed or an expired conversion quote where the quote duration ran out (whether because a user took too long or they decided not to complete the conversion). Admins can see the user who initiated the conversion, which currencies they wanted to convert between, the from and to amount, the rate at the time at which the exchange quote was requested, and the current status of the conversion.
