path: root/core/api-corebank.rst

..
  This file is part of GNU TALER.

  Copyright (C) 2014-2020 Taler Systems SA

  TALER is free software; you can redistribute it and/or modify it under the
  terms of the GNU Affero General Public License as published by the Free Software
  Foundation; either version 2.1, or (at your option) any later version.

  TALER is distributed in the hope that it will be useful, but WITHOUT ANY
  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.

  You should have received a copy of the GNU Affero General Public License along with
  TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>

.. target audience: developer, core developer

.. _corebank-api:

====================
Taler Core Bank API
====================

.. contents:: Table of Contents

Introduction
------------

The Libeufin bank provides a minimal core banking system.  In addition to that,
it provides features for local/regional currencies.

Authentication
--------------

Some requests require the client to authenticate via HTTP Basic auth (RFC 7617)
or using a bearer token which can be obtained or refreshed from the
``/accounts/$USERNAME/token`` endpoint.
When using Basic authentication, the user-id must be the bank
username, and the password the password for the corresponding user.

Another way to obtain a login token is by manually configuring it for certain
endpoints.  For example, the exchange could give an auditor read-only access to
the taler-wire-gateway facade via such a manually configured access token.

The ``admin`` user is a special, hard-coded username. Some requests require the
client to authenticate as the admin.

.. http:post:: /accounts/$USERNAME/token

   See :ref:`DD 48 token endpoint <dd48-token>`.


Bank Web UI
-----------

The web UI for the bank is typically served under ``/``.

Config
------

.. http:get:: /config

  **Response:**

  .. ts:def:: Config

    interface Config {
      // Name of this API, always "taler-corebank".
      name: string;

      // API version in the form $n:$n:$n
      version: string;

      // If 'true', the server provides local currency
      // conversion support.
      // If missing or false, some parts of the API
      // are not supported and return 404.
      have_cashout?: boolean;

      // Fiat currency.  That is the currency in which
      // cash-out operations ultimately wire money.
      // Only applicable if have_cashout=true.
      fiat_currency?: string;

      // How many digits should the amounts be rendered
      // with by default. Small capitals should
      // be used to render fractions beyond the number
      // given here (like on gas stations).
      currency_fraction_digits: number;

      // How many decimal digits an operation can
      // have. Wire transfers with more decimal 
      // digits will not be accepted.
      currency_fraction_limit: number;
    }


Account Management
------------------

.. _bank-account-register:

.. http:post:: /accounts

   Create a new bank account.  Depending on the configuration,
   the account creation is self-serve, or only restricted to
   the administrators.

   **Request:**

   .. ts:def:: RegisterAccountRequest

     interface RegisterAccountRequest {
       // Username
       username: string;

       // Password.
       password: string;

       // Legal name of the account owner
       name: string;

       // Defaults to false.
       is_public?: boolean;

       // Is this a taler exchange account?
       // If true:
       // - incoming transactions to the account that do not
       //   have a valid reserve public key are automatically
       // - the account provides the taler-wire-gateway-api endpoints
       // Defaults to false.
       is_taler_exchange?: boolean;

       // Addresses where to send the TAN for transactions.
       // Currently only used for cashouts.
       // If missing, cashouts will fail.
       // In the future, might be used for other transactions
       // as well.
       challenge_contact_data?: ChallengeContactData;

       // 'payto' address pointing a bank account
       // external to the bank.
       // Payments will be sent to this bank account
       // when the user wants to convert the local currency
       // back to fiat currency outside bank.
       cashout_payto_uri?: string;

       // Internal payto URI of this bank account.
       // Used mostly for testing.
       internal_payto_uri?: string;
     }

   .. ts:def:: ChallengeContactData

     interface ChallengeContactData {

       // E-Mail address
       email?: EmailAddress;

       // Phone number.
       phone?: PhoneNumber;
     }


   **Response:**

   :http:statuscode:`204 No content`:
     The account was successfully created.
   :http:statuscode:`400 Bad request`:
     Input data was invalid.  For example, the client specified a invalid
     phone number or e-mail address.
   :http:statuscode:`403 Forbidden`:
     The response should indicate one of the following reasons.

   * A reserved username was attempted, like ``admin`` or ``bank``.
   * An unauthorized user tried to create the account

   :http:statuscode:`409 Conflict`:
     The internal account payto URI or username already exists.

.. _delete-account:

.. http:delete:: /accounts/$USERNAME

  Delete the account whose username is ``$USERNAME``.  The deletion
  succeeds only if the balance is *zero*.  Typically only available to
  the administrator, but can be configured to allow ordinary users too.

  **Response:**

  :http:statuscode:`204 No content`:
    The account was successfully deleted.
  :http:statuscode:`403 Forbidden`:
    Either the request specified a reserved internal username, like
    ``admin`` or ``bank``, or the client didn't have the rights to this
    call.
  :http:statuscode:`404 Not found`:
    The username was not found.
  :http:statuscode:`412 Precondition failed`:
    The balance was not zero.


.. _account-reconfig:

.. http:patch:: /accounts/$USERNAME

   Allows reconfiguring the account data of ``$USERNAME``.

   **Request:**

   .. ts:def:: AccountReconfiguration

     interface AccountReconfiguration {

       // Addresses where to send the TAN for transactions.
       // Currently only used for cashouts.
       // If missing, cashouts will fail.
       // In the future, might be used for other transactions
       // as well.
       challenge_contact_data?: ChallengeContactData;

       // 'payto' address pointing a bank account
       // external to the bank.
       // Payments will be sent to this bank account
       // when the user wants to convert the local currency
       // back to fiat currency outside the bank.
       cashout_address?: string;

       // Legal name associated with $username.
       // When missing, the old name is kept.
       name?: string;

       // If present, change the is_exchange configuration.
       // See `RegisterAccountRequest`
       is_exchange?: boolean;
     }

   **Response:**

   :http:statuscode:`204 No content`:
     Operation successful.

   :http:statuscode:`403 Forbidden`:
     The rights to change ``$USERNAME`` are not sufficient.
     That includes the case where a correctly authenticated
     user tries to change their legal name.  It also
     includes the case where 'admin' tries to change its
     own account.

   :http:statuscode:`404 Not found`:
     The account pointed by ``$USERNAME``
     was not found.


.. _account-password-reconfig:

.. http:patch:: /accounts/$USERNAME/auth

   Allows changing the account's password.

   **Request:**

   .. ts:def:: AccountPasswordChange

     interface AccountPasswordChange {

       // New password.
       new_password: string;
     }

   **Response:**

   :http:statuscode:`204 No content`:
     Operation successful.


.. _account-list:

.. http:get:: ${BANK_API_BASE_URL}/public-accounts

  Show those accounts whose histories are publicly visible.  For example,
  accounts from donation receivers.  As such, this request is unauthenticated.

  **Response**

  **Details**

  .. ts:def:: PublicAccountsResponse

    interface PublicAccountsResponse {
      public_accounts: PublicAccount[];
    }

  .. ts:def:: PublicAccount

    interface PublicAccount {
      payto_uri: string;

      balance: Balance;

      // The account name (=username) of the
      // bank account.
      account_name: string;
    }


.. http:get:: /accounts

   Obtains a list of the accounts registered at the bank.
   It returns only the information that this API handles, without
   any balance or transactions list.
   This request is only available to the administrator.

   **Request:**

   :query filter_name: *Optional.*
     Pattern to filter on the account legal name.  Given
     the filter 'foo', all the results will **contain**
     'foo' in their legal name.  Without this option,
     all the existing accounts are returned.

   **Response:**

   :http:statuscode:`200 OK`:
     At least one account was found.
     The server responds with a `ListBankAccountsResponse` object.
   :http:statuscode:`204 No Content`:
     No accounts were found for the given request.
   :http:statuscode:`403 Forbidden`:
     A ordinary user invoked this call.

   **Details:**

   .. ts:def:: ListBankAccountsResponse

      interfaces ListBankAccountsResponse {
        accounts: AccountMinimalData[];
      }

   .. ts:def:: Balance

      interface Balance {
        amount: Amount;
        credit_debit_indicator: "credit" | "debit";
      }

   .. ts:def:: AccountMinimalData

      interface AccountMinimalData {
        // Username
        username: string;

        // Legal name of the account owner.
        name: string;

        // current balance of the account
        balance: Balance;

        // Number indicating the max debit allowed for the requesting user.
        debit_threshold: Amount;
      }

.. _bank-account-info:

.. http:get:: /accounts/$USERNAME

   Obtains information relative to the account owned by
   ``$USERNAME``.  The request is available to the administrator
   and ``$USERNAME`` itself.

   **Response:**

  :http:statuscode:`200 OK`:
    The bank responds with an `AccountData` object.

   **Details:**

   .. ts:def:: AccountData

     interface AccountData {
       // Legal name of the account owner.
       name: string;

       // Available balance on the account.
       balance: Balance;

       // payto://-URI of the account.
       payto_uri: string;

       // Number indicating the max debit allowed for the requesting user.
       debit_threshold: Amount;

       contact_data?: ChallengeContactData;

       // 'payto' address pointing the bank account
       // where to send cashouts.  This field is optional
       // because not all the accounts are required to participate
       // in the merchants' circuit.  One example is the exchange:
       // that never cashouts.  Registering these accounts can
       // be done via the access API.
       cashout_payto_uri?: string;
     }

Transactions
------------

.. http:get:: ${BANK_API_BASE_URL}/accounts/${account_name}/transactions

   Retrieve a subset of transactions related to $account_name.  Without
   query parameters, it returns the last 5 transactions.

   The list of returned transactions is determined by a row ID *starting point*
   and a signed non-zero integer *delta*:

   * If *delta* is positive, return a list of up to *delta* transactions (all matching
     the filter criteria) strictly **after** the starting point.  The transactions are sorted
     in **ascending** order of the row ID.
   * If *delta* is negative, return a list of up to *-delta* transactions (all matching
     the filter criteria) strictly **before** the starting point.  The transactions are sorted
     in **descending** order of the row ID.

   If *starting point* is not explicitly given, it defaults to:

   * A value that is **smaller** than all other row IDs if *delta* is **positive**.
   * A value that is **larger** than all other row IDs if *delta* is **negative**.

   **Request**

   :query long_poll_ms: Optional number to express how many milliseconds the server
     should wait for at least one result to be shown.  If not given, the server
     responds immediately, regardless of the result.
   :query start: *Optional.*
     Row identifier to explicitly set the *starting point* of the query.
   :query delta:
     The *delta* value that determines the range of the query.

   **Response**

   .. ts:def:: BankAccountTransactionsResponse

     interface BankAccountTransactionsResponse {
       transactions: BankAccountTransactionInfo[];
     }

.. http:get:: ${BANK_API_BASE_URL}/accounts/${account_name}/transactions/${transaction_id}

   **Response**

   Retrieve the transaction whose identifier is ``transaction_id``,
   in the following format:

   .. ts:def:: BankAccountTransactionInfo

     interface BankAccountTransactionInfo {
       creditor_payto_uri: string;
       debtor_payto_uri: string;

       amount: Amount;
       direction: "debit" | "credit";

       subject: string;

       // Transaction unique ID.  Matches
       // $transaction_id from the URI.
       row_id: number;
       date: Timestamp;
     }


.. http:post:: ${BANK_API_BASE_URL}/accounts/${account_name}/transactions

   Create a new transaction where the bank account with the label ``account_name`` is **debited**.

   **Request**

   .. ts:def:: BankAccountTransactionCreate

      interface CreateBankAccountTransactionCreate {

        // Address in the Payto format of the wire transfer receiver.
        // It needs at least the 'message' query string parameter.
        payto_uri: string;

        // Transaction amount (in the $currency:x.y format), optional.
        // However, when not given, its value must occupy the 'amount'
        // query string parameter of the 'payto' field.  In case it
        // is given in both places, the payto_uri's takes the precedence.
        amount: string;
      }

   **Response**

   :http:statuscode:`200 OK`:
      the transaction has been created.

   :http:statuscode:`400 Bad Request`:
      the request was invalid or the payto://-URI used unacceptable features.


Taler Withdrawals
-----------------

.. http:post:: ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals

  Create a withdrawal operation, resulting in a ``taler://withdraw`` URI.

  **Request**

  .. ts:def:: BankAccountCreateWithdrawalRequest

    interface BankAccountCreateWithdrawalRequest {
      // Amount to withdraw.
      amount: Amount;
    }

  **Response**

  .. ts:def:: BankAccountCreateWithdrawalResponse

    interface BankAccountCreateWithdrawalResponse {
      // ID of the withdrawal, can be used to view/modify the withdrawal operation.
      // This ID will be globally unique and grant control over the operation to
      // abort or confirm it.
      withdrawal_id: string;

      // URI that can be passed to the wallet to initiate the withdrawal.
      taler_withdraw_uri: string;
    }

  :http:statuscode:`403 Forbidden`:
    The operation was rejected due to insufficient funds.

.. http:get:: ${BANK_API_BASE_URL}/withdrawals/${withdrawal_id}

  Query the status of a withdrawal operation. Does not require further
  authentication as knowledge of the withdrawal ID serves as an authenticator.

  **Response**

  **Details**

  .. ts:def:: BankAccountGetWithdrawalResponse

    interface BankAccountGetWithdrawalResponse {
      // Amount that will be withdrawn with this withdrawal operation.
      amount: Amount;

      // Was the withdrawal aborted?
      aborted: boolean;

      // Has the withdrawal been confirmed by the bank?
      // The wire transfer for a withdrawal is only executed once
      // both ``confirmation_done`` is ``true`` and ``selection_done`` is ``true``.
      confirmation_done: boolean;

      // Did the wallet select reserve details?
      selection_done: boolean;

      // Reserve public key selected by the exchange,
      // only non-null if ``selection_done`` is ``true``.
      selected_reserve_pub: string | null;

      // Exchange account selected by the wallet, or by the bank
      // (with the default exchange) in case the wallet did not provide one
      // through the Integration API.
      selected_exchange_account: string | null;
    }


.. http:post:: ${BANK_API_BASE_URL}/withdrawals/${withdrawal_id}/abort

  Abort a withdrawal operation.  Has no effect on an already aborted
  withdrawal operation.  Does not require further authentication as knowledge
  of the withdrawal ID serves as an authenticator.

  :http:statuscode:`200 OK`: The withdrawal operation has been aborted.  The response is an empty JSON object.
  :http:statuscode:`409 Conflict`:  The reserve operation has been confirmed previously and can't be aborted.


.. http:post:: ${BANK_API_BASE_URL}/withdrawals/${withdrawal_id}/confirm

  Confirm a withdrawal operation.  Has no effect on an already confirmed
  withdrawal operation.  This call is responsible for wiring the funds to the
  exchange.  Does not require further authentication as knowledge of the
  withdrawal ID serves as an authenticator.

  **Response**

  :http:statuscode:`200 OK`:
     The withdrawal operation has been confirmed.  The response is an empty JSON object.
  :http:statuscode:`409 Conflict`:
     The withdrawal has been aborted previously and can't be confirmed.
  :http:statuscode:`422 Unprocessable Entity` (New):
     The withdraw operation cannot be confirmed because no exchange and reserve public key selection happened before.

Cashouts
--------

.. _account-cashout:

.. http:post:: /accounts/$USERNAME/cashouts

   Initiates a conversion to fiat currency.  The external
   bank account to be
   credited is the one specified at registration time via the
   *cashout_address* parameter.  The bank internal account
   is specified via ``$USERNAME``.
   The bank sends a TAN to the customer to let them confirm the
   operation.  The request is only available to ordinary users, not
   to the administrator.

   .. note::

     Consult the `cashout rates call <cashout-rates_>`_ to learn
     about any applicable fee or exchange rate.

   .. note::

     FIXME: Eventually, the env variables will be replaced with
     configuration settings.

     To test this operation without relying on any SMS/E-mail provider,
     Libeufin offers two methods: defining an environment variable called
     ``LIBEUFIN_CASHOUT_TEST_TAN`` or specifying the value ``file`` to
     the ``tan_channel`` field of the `request object <cashout-request_>`_.
     Assuming ``LIBEUFIN_CASHOUT_TEST_TAN`` is set to *T*, every */confirm*
     operation can use *T* as the TAN.  Setting instead the ``tan_channel``
     field to ``file`` will cause the server to (over)write every TAN to
     ``/tmp/cashout-tan.txt``.  If both are used, the environment
     variable takes the precedence.


   **Request:**

   `CashoutRequest <cashout-request_>`_

   .. ts:def:: TanChannel

     enum TanChannel {
       SMS = "sms",
       EMAIL = "email",
       FILE = "file"
     }

   .. _cashout-request:

   .. ts:def:: CashoutRequest

     interface CashoutRequest {

       // Optional subject to associate to the
       // cashout operation.  This data will appear
       // as the incoming wire transfer subject in
       // the user's external bank account.
       subject?: string;

       // That is the plain amount that the user specified
       // to cashout.  Its $currency is the (regional) currency of the
       // bank instance.
       amount_debit: Amount;

       // That is the amount that will effectively be
       // transferred by the bank to the user's bank
       // account, that is external to the regional currency.
       // It is expressed in the fiat currency and
       // is calculated after the cashout fee and the
       // exchange rate.  See the /cashout-rates call.
       // The client needs to calculate this amount
       // correctly based on the amount_debit and the cashout rate,
       // otherwise the request will fail.
       amount_credit: Amount;

       // Which channel the TAN should be sent to.  If
       // this field is missing, it defaults to SMS.
       // The default choice prefers to change the communication
       // channel respect to the one used to issue this request.
       tan_channel?: TanChannel;
     }

   **Response:**

   :http:statuscode:`202 Accepted`:
     The cashout request was correctly created and
     the TAN authentication now is pending.
     This returns the `CashoutPending` response.
   :http:statuscode:`409 Conflict`:
     The user did not share any contact data where to send the TAN,
     the account does not have sufficient funds, or the
     exchange rate was calculated incorrectly by the client.
   :http:statuscode:`503 Service unavailable`:
     The bank does not support the TAN channel for this operation.

   **Details:**

   .. ts:def:: CashoutPending

     interface CashoutPending {
       // ID identifying the operation being created
       // and now waiting for the TAN confirmation.
       cashout_id: string;
     }


.. _cashout-abort:

.. http:post:: /accounts/$USERNAME/cashouts/$CASHOUT_ID/abort

   Aborts the ``$CASHOUT_ID`` operation.

   **Response:**

   :http:statuscode:`204 No content`:
     ``$CASHOUT_ID`` was found in the *pending* state
     and got successfully aborted.
   :http:statuscode:`404 Not found`:
     ``$CASHOUT_ID`` is not found.  Note: that happens
     also when ``$CASHOUT_ID`` got aborted before this request.
   :http:statuscode:`409 Conflict`:
     ``$CASHOUT_ID`` was already confirmed.


.. _cashout-confirm:

.. http:post:: /accounts/$USERNAME/cashouts/$CASHOUT_ID/confirm

   Confirms the ``$CASHOUT_ID`` operation by providing its
   TAN.  The request should still be authenticated with
   the users credentials.

   **Request:**

   .. ts:def:: CashoutConfirm

     interface CashoutConfirm {
       // the TAN that confirms $CASHOUT_ID.
       tan: string;
     }

   **Response:**

   :http:statuscode:`204 No content`:
     The request succeeded, either for the first time, or it already was
     confirmed previously (idempotency!).
   :http:statuscode:`403 Forbidden`:
     Wrong TAN or bad credentials.
   :http:statuscode:`404 Not found`:
     ``$CASHOUT_ID`` is not found.  Note: that happens
     also when ``$CASHOUT_ID`` got aborted before this request.
   :http:statuscode:`409 Conflict`:
     The user changed their cash-out address between the creation and the confirmation of ``$CASHOUT_ID``.


.. _cashout-rates:

.. http:get:: /cashout-rate

  This public endpoint allows clients to calculate
  the exchange rate between the regional currency
  and the external banking system.

  This endpoint shows how the bank would apply the cash-out
  ratio and fee to one input amount.  Typically, frontends
  ask this endpoint before creating cash-out operations.
  At least one of the two query parameters must be provided.  If both are
  given, then the server checks their correctness.  Amounts must include the
  currency.

  **Request:**

  :query amount_debit: this is the amount that the user will get
    deducted from their regional bank account.

  :query amount_credit: this is the amount that the user will receive
    in their fiat bank account.

  **Response:**

  .. ts:def:: CashoutConversionResponse

    interface CashoutConversionResponse {
      // Amount that the user will get deducted from their regional
      // bank account, according to the 'amount_credit' value.
      amount_debit: Amount;
      // Amount that the user will receive in their fiat
      // bank account, according to 'amount_debit'.
      amount_credit: Amount;
    }


  :http:statuscode:`200 OK`:
    Response is a `CashoutConversionResponse`.
  :http:statuscode:`400 Bad request`:
    Both parameters have been provided and the calculation is not correct,
    or none of them has been provided.
  :http:statuscode:`404 Not found`:
    The server does not support local currency conversion.


.. _circuit-cashouts:

.. http:get:: /accounts/$USERNAME/cashouts

  Returns the list of all the (pending and confirmed) cash-out operations
  for an account.

  **Response:**

  .. ts:def:: Cashouts

    interface Cashouts {
      // Every string represents a cash-out operation ID.
      cashouts: CashoutInfo[];
    }

  .. ts:def:: CashoutInfo

    interface CashoutInfo {
      cashout_id: string;
      status: "pending" | "confirmed";
    }

  :http:statuscode:`200 OK`:
    At least one cash-out operation was found.

  :http:statuscode:`204 No Content`:
    No cash-out operations were found at the bank

.. http:get:: /cashouts

  Returns the list of all the (pending and confirmed) cash-out operations
  for **all** accounts.

  Typically can only be used by the administrators.

  .. note::

    We might want to add a filter in the future to only
    query pending cashout operations.

  **Response:**

  .. ts:def:: GlobalCashouts

    interface GlobalCashouts {
      // Every string represents a cash-out operation ID.
      cashouts: { cashout_id: string, username: string}[];
    }

  .. ts:def:: GlobalCashoutInfo

    interface GlobalCashoutInfo {
      cashout_id: string;
      username: string;
      status: "pending" | "confirmed";
    }

  :http:statuscode:`200 OK`:
    At least one cash-out operation was found.

  :http:statuscode:`204 No Content`:
    No cash-out operations were found at the bank

.. _circuit-cashout-details:

.. http:get:: /accounts/$USERNAME/cashouts/$CASHOUT_ID

  Returns information about the status of the ``$CASHOUT_ID`` operation.
  The request is available to the administrator and the account owner.

  **Response:**

  `CashoutStatusResponse <cashout-status_>`_

  .. _cashout-status:

  .. ts:def:: CashoutStatus

    interface CashoutStatusResponse {
      status: "pending" | "confirmed";

      // Amount debited to the internal
      // regional currency bank account.
      amount_debit: Amount;

      // Amount credited to the external bank account.
      amount_credit: Amount;

      // Transaction subject.
      subject: string;

      // Fiat bank account that will receive the cashed out amount.
      // Specified as a payto URI.
      credit_payto_uri: string;

      // Time when the cashout was created.
      creation_time: Timestamp;

      // Time when the cashout was confirmed via its TAN.
      // Missing when the operation wasn't confirmed yet.
      confirmation_time?: Timestamp;
    }

  **Response:**

  :http:statuscode:`404 Not found`:
    The cashout operation was not found.
    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: DecimalNumber; 

      // Exchange rate to sell the local currency for the external one
      sell_at_ratio: DecimalNumber; 

      // Fee to subtract after applying the buy ratio.
      buy_in_fee: DecimalNumber;

      // Fee to subtract after applying the sell ratio.
      sell_out_fee: DecimalNumber;
    }

  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 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:**

   :query timeframe: this parameter admits one of the following values.  It is optional,
     defaulting to 'hour'.

     * hour
     * day
     * month
     * year
     * decade

   :query which: this parameter points at a particular element of the *timeframe* parameter.  Following are the admitted values for each one.  It is optional, defaulting to the last snapshot taken of the *timeframe* parameter.

     * hour: from 00 to 23
     * day: from 1 to the last day of the current month.
     * month: from 1 to 12
     * year: Gregorian year in the YYYY format.
     * decade: the least Y0 digits of a Gregorian year.  Banks should treat such decades as starting from the year 2000.  For example, if Y=2, this decade denotes the years 2020 to 2029.

  **Response:**

    :http:statuscode:`200 OK`: the bank responds with `MonitorResponse`.

    :http:statuscode:`404 Not Found`: the bank doesn't have the conversion service.

    .. note::

      API consumers may combine the values in the response with other
      factors to serve different views to their users.

    :http:statuscode:`400 Bad Request`:
      this error may indicate that the *which* parameter is not appropriate for the selected *timeframe*.  For example, timeframe=month and which=20 would result in this error.

  .. ts:def:: MonitorResponse

    interface MonitorResponse {

      // This number identifies how many cashin operations
      // took place in the timeframe specified in the request.
      // This number corresponds to how many withdrawals have
      // been initiated by a wallet owner.  Note: wallet owners
      // are NOT required to be customers of the libeufin-bank.
      cashinCount: number;

      // This amount accounts how much external currency has been
      // spent to withdraw Taler coins in the internal currency.
      // The exact amount of internal currency being created can be
      // calculated using the advertised conversion rates.
      cashinExternalVolume: Amount;

      // This number identifies how many cashout operations were
      // confirmed in the timeframe speficied in the request.
      cashoutCount: number;

      // This amount corresponds to how much *external* currency was
      // paid by the libeufin-bank administrator to fulfill all the
      // confirmed cashouts related to the timeframe specified in the
      // request.
      cashoutExternalVolume: Amount;

      // This number identifies how many payments were made by a
      // Taler exchange to a merchant bank account in the internal
      // currency, in the timeframe specified in the request.
      talerPayoutCount: number;

      // This amount accounts the overall *internal* currency that
      // has been paid by a Taler exchange to a merchant internal
      // bank account, in the timeframe specified in the request.
      talerPayoutInternalVolume: Amount;
    }


Taler Bank Integration API
--------------------------

.. http:any:: /taler-integration/*

  All endpoints under this prefix are specified by the.
  :doc:`GNU Taler bank integration API </core/api-bank-integration>`.
  This API handles the communication with Taler wallets.

Taler Wire Gateway API
----------------------

.. http:any:: /accounts/$USERNAME/taler-wire-gateway/*

   All endpoints under this prefix are specified
   by the :doc:`GNU Taler wire gateway API </core/api-bank-wire>`.

   The endpoints are only available for accounts configured with ``is_exchange=true``.

Taler Revenue API
----------------------

.. http:any:: /accounts/$USERNAME/taler-revenue/*

   All endpoints under this prefix are specified
   by the :doc:`GNU Taler Revenue API </core/api-bank-revenue>`.

EBICS Host
----------

The Taler bank can be configured to serve bank account transactions and allow
payment initiations via the EBICS protocol.

This is an optional feature, not all implementations of the API support it.

.. http:post:: /ebicshost

   EBICS base URL.  This URL allows clients to make EBICS requests to one of
   the configured EBICS hosts.