[taler-docs] branch master updated: Conversion rates endpoint.

[gnunet]

This is an automated email from the git hooks/post-receive script.

ms pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 73338e3a Conversion rates endpoint.
73338e3a is described below

commit 73338e3a1ae0dd3826e0e0bb1aff23ee13a1f430
Author: MS <ms@taler.net>
AuthorDate: Thu Oct 5 15:39:12 2023 +0200

    Conversion rates endpoint.
---
 core/api-corebank.rst | 60 +++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 54 insertions(+), 6 deletions(-)

diff --git a/core/api-corebank.rst b/core/api-corebank.rst
index b2b96d71..5d8bec6f 100644
--- 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::
 

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.