commit 73338e3a1ae0dd3826e0e0bb1aff23ee13a1f430
parent 5c3cb57728603765b5c52ae4a8b88baca06e658b
Author: MS <ms@taler.net>
Date: Thu, 5 Oct 2023 15:39:12 +0200
Conversion rates endpoint.
Diffstat:
1 file changed, 54 insertions(+), 6 deletions(-)
diff --git a/core/api-corebank.rst b/core/api-corebank.rst
@@ -908,15 +908,62 @@ Cashouts
Aborted cashout operations will also not be found.
+Conversion rates
+----------------
+
+..
+ FIXME: throughout API docs and implementations, the following names
+ are used interchangeably: local, regional, internal currency. As well
+ these: external, fiat, currency. Style should tend to use only one.
+
+.. http:get:: /conversion-rates
+
+ This call shows the current conversion rates between the local and the
+ external currency. The external currency is the one mentioned in the
+ *fiat_currency* field of `Config`.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`: `ConversionRatesResponse`.
+
+ :http:statuscode:`404 Not Found`: the bank doesn't provide any conversion service.
+
+ .. ts:def:: ConversionRatesResponse
+
+ interface ConversionRatesResponse {
+
+ // Exchange rate to buy the local currency from the external one
+ buy_at_ratio: FractionalNumber;
+
+ // Exchange rate to sell the local currency for the external one
+ sell_at_ratio: FractionalNumber;
+
+ // Fee to subtract after applying the buy ratio.
+ buy_in_fee: FractionalNumber;
+
+ // Fee to subtract after applying the sell ratio.
+ sell_out_fee: FractionalNumber;
+ }
+
+ For example, given a local currency LC, a fiat currency FC,
+ a *sell_at_ratio* = 0.9 and *sell_out_fee* = 0.03, selling
+ 10 LC would result in the following FC: (10 * 0.9) - 0.03
+ = 8.97 FC. On the other hand, given *buy_at_ratio* = 1.1
+ and *buy_in_fee* = 0.01, a user wanting to spend 10 FC to
+ buy the LC would result in the following LC: (10 * 1.1) -
+ 0.01 = 10.99 LC.
+
+
Monitor
-------
.. http:get:: /monitor
- When the bank has cashouts, this call lets the bank administrator monitor
- the cashin and cashout operations that were made from and to an external
- currency. It shows as well figures related to (internal) payments made
- by a Taler exchange component to merchant bank accounts.
+ When the bank provides conversion between the local currency and an
+ external one, this call lets the bank administrator monitor the cashin
+ and cashout operations that were made from and to the external currency.
+ It shows as well figures related to (internal) payments made by a Taler
+ exchange component to merchant bank accounts.
**Request:**
@@ -939,8 +986,9 @@ Monitor
**Response:**
- :http:statuscode:`200 OK`:
- the bank responds with `MonitorResponse`.
+ :http:statuscode:`200 OK`: the bank responds with `MonitorResponse`.
+
+ :http:statuscode:`404 Not Found`: the bank doesn't have the conversion service.
.. note::
