Currency exchange
The Currency Exchange operations are available for business users to perform currency exchange operations between wallets in different currencies.
To allow currency exchange operations, Service users with appropriate permission should top-up the special type of account exchange_reserve for each currency.
Currency exchange operation is also used when a User deletes one of his wallets with a positive balance and the funds can be transferred (exchanged to different currency) to another wallet of the User.
To exchange the currency User should:
1. Choose the type of operation (Sell or Buy)
Example:
In exchange type SELL it means that a user wants to sell EUR from his EUR wallet.
In exchange type BUY it means that a user wants to buy USD and put the amount to his USD wallet and pay for that operation from EUR wallet.
2. Choose the source wallet
3. Choose the destination wallet
4. Enter amount
5. The system validates the wallets and checks if the operation is available for the User, as well as calculates commission and checks the limits for the operation.
6. Confirm exchange.
Commission for currency exchange
The commission for currency exchange operation will be added for sell or deducted for buy from the system exchange rate.
Sell and buy are from the system point-of-view:
- sell – system sells currency to a customer, so the commission will be added to the system exchange rate
- buy – system buys currency from a customer, so the commission will be deducted from the system exchange rate
Currency scale calculation for currency exchange
Sell
- System scales amount to sell according to the “from account currency”
- System compares the “from account” balance and the “amount to sell”
- System calculates:
- topup amount -> “to account currency” scale
- withdraw amount -> “from account currency” scale
{ "topUpAmount" : 0.9180990000, "withdrawAmount" : 60000.0000, "exchangeRate" : { "inCurrency" : { "id" : "4a72ea60-f994-44bd-9d2b-64ec15e14d1d", "sn" : "USD", "code" : "USD", "symbol" : "$" }, "outCurrency" : { "id" : "4a4917e4-7134-470f-9f89-9d1e26217acd", "sn" : "BTC", "code" : "BTC", "symbol" : "₿" }, "rate" : 0.00001530165000000000, "organisationId" : "64fdc325-11de-42ef-b490-5c4f31303711" } }
Buy
- System scales “amount to buy” to the “to account currency”
- System compares the withdrawAmount (with “from account currency” scale, “buy amount” * “rate”) with the “from account” balance
- System calculates:
- topup amount -> to account currency scale
- withdraw amount -> from account currency scale
{ "topUpAmount" : 1.0000000000, "withdrawAmount" : 65352.4293, "exchangeRate" : { "inCurrency" : { "id" : "4a72ea60-f994-44bd-9d2b-64ec15e14d1d", "sn" : "USD", "code" : "USD", "symbol" : "$" }, "outCurrency" : { "id" : "4a4917e4-7134-470f-9f89-9d1e26217acd", "sn" : "BTC", "code" : "BTC", "symbol" : "₿" }, "rate" : 0.00001530165000000000, "organisationId" : "64fdc325-11de-42ef-b490-5c4f31303711" } }
Working with API
You can find the list of APIs related to Currency Exchange in the following sections of Swagger:
- Currency Exchange (view rates, calculate the rate, execute exchange operation)
- Commission rule management (set up commission settings for exchange operations)
Sell and Buy logic in API implementation
APIs for commission calculation and operation execution have the same request body structure.
In exchange type SELL it means that as a user I want to sell 100 EUR from “inCoinSerial”:
“{{EUR account}}” and get the exchanged amount into my “outCoinSerial”: “{{USD account}}”
{ "inCoinSerial": "{{EUR account}}", "outCoinSerial": "{{USD account}}", "exchangeType": "sell", "amount": 100 }
In exchange type BUY it means that as a user I want to buy 99 USD into “outCoinSerial”: “{{USD account}}” and pay for that operation from my “inCoinSerial”: “{{EUR account}}”
{ "inCoinSerial": "{{EUR account}}", "outCoinSerial": "{{USD account}}", "exchangeType": "buy", "amount": 99 }
To ease the understanding of this flow you can imagine this logic from the perspective of the currency exchange office:
- you bring 100 EUR to Sell, it’s incoming operation “inCoinSerial” and receive USD, it’s an outgoing operation “outCoinSerial”
- you came to buy 99 USD and the cashier tells that firstly you need to give 85 EUR, it’s an incoming operation “inCoinSerial” and then he gives you 99 USD, it’s an outgoing operation “outCoinSerial”