taler-docs

api-auditor.rst (79023B)

---

 ..
   This file is part of GNU TALER.
   Copyright (C) 2018-2024 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/>
 
   @author Christian Grothoff
 
 ============================
 The Auditor RESTful JSON API
 ============================
 
 The API specified here follows the :ref:`general conventions <http-common>`
 for all details not specified in the individual requests.
 The `glossary <https://docs.taler.net/taler-developer-manual.html#developer-glossary>`_
 defines all specific terms used in this section.
 
 .. contents:: Table of Contents
   :local:
 
 .. _authentication:
 
 --------------
 Authentication
 --------------
 
 Each auditor instance has separate authentication settings for the private API resources
 of that instance.
 
 Currently, the API supports two main authentication methods:
 
 * ``external``:  With this method, no checks are done by the auditor backend.
   Instead, a reverse proxy / API gateway must do all authentication/authorization checks.
 * ``token``: With this method, the client must provide a ``Authorization: Bearer $TOKEN``
   header, where ``$TOKEN`` is a secret authentication token configured for the instance which must begin with the RFC 8959 prefix.
 
 .. _auditor-version:
 
 -------------------------
 Obtaining Auditor Version
 -------------------------
 
 This endpoint is used by merchants to obtain a list of all exchanges audited by
 this auditor.  This may be required for the merchant to perform the required
 know-your-customer (KYC) registration before issuing contracts.
 
 .. http:get:: /config
 
   Get the protocol version and some meta data about the auditor.
   This specification corresponds to ``current`` protocol being version **v2**.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The auditor responds with an `AuditorVersion`_ object. This request should
     virtually always be successful.
 
   **Details:**
 
   .. _AuditorVersion:
   .. code-block:: tsref
 
     interface AuditorVersion {
       // libtool-style representation of the Taler protocol version, see
       // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
       // The format is "current:revision:age".  Note that the auditor
       // protocol is versioned independently of the exchange's protocol.
       version: string;
 
       // URN of the implementation (needed to interpret 'revision' in version).
       // @since v0, may become mandatory in the future.
       implementation?: string;
 
       // Return which currency this auditor is auditing for.
       currency: string;
 
       // EdDSA master public key of the auditor.
       auditor_public_key: EddsaPublicKey;
 
       // EdDSA master public key of the exchange.
       // Added in protocol v1.
       exchange_master_public_key: EddsaPublicKey;
     }
 
   .. note::
 
     This endpoint is still experimental (and is not yet implemented at the
     time of this writing).
 
 
 .. _deposit-confirmation:
 
 ---------------------
 Deposit Confirmations
 ---------------------
 
 Merchants should probabilistically submit some of the deposit
 confirmations they receive from the exchange to auditors to ensure
 that the exchange does not lie about recording deposit confirmations
 with the exchange. Participating in this scheme ensures that in case
 an exchange runs into financial trouble to pay its obligations, the
 merchants that did participate in detecting the bad behavior can be
 paid out first.
 
 .. http:put:: /deposit-confirmation
 
   Submits a `DepositConfirmation` to the exchange. Should succeed
   unless the signature provided is invalid or the exchange is not
   audited by this auditor.
 
   **Response:**
 
   :http:statuscode:`200 Ok`:
         The auditor responds with a `DepositAudited` object.
         This request should virtually always be successful.
   :http:statuscode:`403 Forbidden`:
         The signature on the deposit confirmation is invalid.
   :http:statuscode:`410 Gone`:
         The public key used to sign the deposit confirmation
         was revoked.
 
   **Details:**
 
   .. ts:def:: DepositAudited
 
     interface DepositAudited {
       // TODO: maybe change to ``204 No content`` instead?
     }
 
   .. ts:def:: DepositConfirmation
 
     interface DepositConfirmation {
 
       // Hash over the contract for which this deposit is made.
       h_contract_terms: HashCode;
 
       // Hash over the extensions.
       h_extensions: HashCode;
 
       // Hash over the wiring information of the merchant.
       h_wire: HashCode;
 
       // Time when the deposit confirmation confirmation was generated.
       timestamp: Timestamp;
 
       // How much time does the merchant have to issue a refund
       // request?  Zero if refunds are not allowed.
       refund_deadline: Timestamp;
 
       // By what time does the exchange have to wire the funds?
       wire_deadline: Timestamp;
 
       // Amount to be deposited, excluding fee.  Calculated from the
       // amount with fee and the fee from the deposit request.
       amount_without_fee: Amount;
 
       // Array of public keys of the deposited coins.
       coin_pubs: EddsaPublicKey[];
 
       // Array of deposit signatures of the deposited coins.
       // Must have the same length as ``coin_pubs``.
       coin_sigs: EddsaSignature[];
 
       // The Merchant's public key.  Allows the merchant to later refund
       // the transaction or to inquire about the wire transfer identifier.
       merchant_pub: EddsaPublicKey;
 
       // Signature from the exchange of type
       // ``TALER_SIGNATURE_EXCHANGE_CONFIRM_DEPOSIT``.
       exchange_sig: EddsaSignature;
 
       // Public signing key from the exchange matching ``exchange_sig``.
       exchange_pub: EddsaPublicKey;
 
       // Master public key of the exchange corresponding to ``master_sig``.
       // Identifies the exchange this is about.
       // @deprecated since v1 (now ignored, global per auditor)
       master_pub: EddsaPublicKey;
 
       // When does the validity of the exchange_pub end?
       ep_start: Timestamp;
 
       // When will the exchange stop using the signing key?
       ep_expire: Timestamp;
 
       // When does the validity of the exchange_pub end?
       ep_end: Timestamp;
 
       // Exchange master signature over ``exchange_sig``.
       master_sig: EddsaSignature;
     }
 
   .. note::
 
     This endpoint is still experimental (and is not yet implemented at the
     time of this writing). A key open question is whether the auditor
     should sign the response information.
 
 
 .. _auditor-monitoring-spa-api:
 
 --------------
 Monitoring API
 --------------
 
 The following entries specify how to access the results of an audit.
 
 For most endpoints, rows may be marked as 'suppressed' to not send them again
 upon subsequent GET requests.  To do this, a
 :ts:type:`GenericAuditorMonitorPatchRequest` object is used in the respective
 PATCH request.
 
 **Details:**
 
   .. ts:def:: GenericAuditorMonitorPatchRequest
 
     interface GenericAuditorMonitorPatchRequest {
 
       // If true, subsequent GET requests will not return this element by default
       suppressed : boolean;
 
     }
 
 
 .. _fee-time-inconsistency-list:
 
 Fee Time Inconsistencies
 ------------------------
 
 This section highlights cases where validity periods associated with wire fees
 the exchange may charge merchants are invalid.  This usually means that the
 validity periods given for the same type of fee are overlapping and it is thus
 unclear which fee really applies.  This is a sign of a serious
 misconfiguration or data corruption as usually the exchange logic should
 prevent such a fee configuration from being accepted.
 
 .. http:get:: /monitoring/fee-time-inconsistency
 
   Get a list of fee time inconsistencies stored by the auditor.
 
   The following query parameters are optional, and can be used to customise the response:
 
   **Request:**
 
   :query limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
   :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
   :query return_suppressed: A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.
 
   With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The auditor responds with a top level array of :ts:type:`FeeTimeInconsistency` objects. If no elements could be found, an empty array is returned
 
   **Details:**
 
   .. ts:def:: FeeTimeInconsistency
 
     interface FeeTimeInconsistency {
 
       // Row ID of the fee in the exchange database.
       row_id : Integer;
 
       // Specifies the wire method for which the fee is inconsistent.
       type : string;
 
       // Gives the start date of the inconsistent fee.
       time : Timestamp;
 
       // Human readable description of the problem.
       diagnostic : string;
 
       // True if this diagnostic was suppressed.
       suppressed : boolean;
 
     }
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 .. http:patch:: /monitoring/fee-time-inconsistency/$SERIAL_ID
 
   This endpoint is used to suppress selected elements of fee time
   inconsistencies.  Updates the 'suppressed' field of a fee time inconsistency
   element with row ID ``$SERIAL_ID``.
 
   **Request:**
 
   The body must be a `GenericAuditorMonitorPatchRequest`.
 
   **Response:**
 
   :http:statuscode:`204 No Content`:
     The element has been updated.
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 .. _emergency-list:
 
 Emergencies
 -----------
 
 This endpoint is used to obtain a list of emergencies.
 
 Emergencies are errors where the total value of coins deposited (of a
 particular denomination) exceeds the total value that the exchange remembers
 issuing.  This usually means that the private keys of the exchange were
 compromised (stolen or factored) and subsequently used to sign coins off the
 books.  If this happens, all coins of the respective denomination that the
 exchange has redeemed so far may have been created by the attacker, and the
 exchange would have to refund all of the outstanding coins from ordinary
 users.  Thus, the risk exposure is the amount of coins in circulation for a
 particular denomination and the maximum loss for the exchange from this type
 of compromise.
 
 The difference between emergencies and emergencies by count is how the auditor
 detected the problem: by comparing amounts, or by counting coins.
 Theroretically, counting coins should always detect an issue first, but given
 the importance of emergencies, the auditor checks both total amounts and total
 numbers of coins (they may differ as coins may be partially deposited).
 
 .. http:get:: /monitoring/emergency
 
   Get a list of emergencies stored by the auditor.
 
   The following query parameters are optional, and can be used to customise the response:
 
   **Request:**
 
   :query limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
   :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
   :query return_suppressed: A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.
 
 
   With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The auditor responds with a top level array of :ts:type:`Emergency` objects. If no elements could be found, an empty array is returned
 
   **Details:**
 
   .. ts:def:: Emergency
 
     interface Emergency {
 
       // Unique row identifier
       row_id : Integer;
 
       // Hash of denomination public key
       denompub_h : HashCode;
 
       // What is the total value of all coins of this denomination that
       // were put into circulation (and thus the maximum loss the
       // exchange may experience due to this emergency).
       denom_risk : Amount;
 
       // What is the loss we have experienced so far (that
       // is, the amount deposited in excess of the amount
       // we issued).
       denom_loss : Amount;
 
       // When did the exchange start issuing coins in this the denomination.
       deposit_start : Timestamp;
 
       // When does the deposit period end for coins of this denomination.
       deposit_end : Timestamp;
 
       // What is the value of an individual coin of this denomination.
       value : Amount;
 
       // True if this diagnostic was suppressed.
       suppressed : boolean;
 
     }
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 .. http:patch:: /monitoring/emergency/$SERIAL_ID
 
   This endpoint is used to suppress select elements of emergencies.
   Update the 'suppressed' field of an emergency element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
 
   **Response:**
 
   :http:statuscode:`204 No Content`:
     The element has been updated.
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 .. _emergency-by-count-list:
 
 Emergencies By Count
 --------------------
 
 This endpoint is used to obtain a list of emergencies by count.
 
 Emergencies are errors where more coins were deposited than the
 exchange remembers issuing.  This usually means that the private keys
 of the exchange were compromised (stolen or factored) and subsequently
 used to sign coins off the books.  If this happens, all coins of the
 respective denomination that the exchange has redeemed so far may have
 been created by the attacker, and the exchange would have to refund
 all of the outstanding coins from ordinary users.  Thus, the risk
 exposure is the amount of coins in circulation for a particular
 denomination and the maximum loss for the exchange from this type of
 compromise.
 
 Emergencies "by count" are cases where this type of money printing was
 detected simply by counting the number of coins the exchange officially put
 into circulation and comparing it to the number of coins that were redeemed.
 If the number of redeemed coins is higher than the number of issued coins, the
 auditor reports an emergency-by-count.
 
 .. http:get:: /monitoring/emergency-by-count
 
   Get a list of emergencies by count stored by the auditor.
 
   The following query parameters are optional, and can be used to customise the response:
 
   **Request:**
 
   :query limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
   :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
   :query return_suppressed: A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.
 
 
   With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The auditor responds with a top level array of :ts:type:`EmergencyByCount` objects.
 
   **Details:**
 
   .. ts:def:: EmergencyByCount
 
     interface EmergencyByCount {
 
       // Row ID of the fee in the exchange database.
       row_id : Integer;
 
       // Hash of the public denomination key to which the
       // emergency applies.
       denompub_h : HashCode;
 
       // Number of coins the exchange officially issued of this
       // denomination.
       num_issued : Integer;
 
       // Number of coins that were redeemed.
       num_known : Integer;
 
       // What is the total value of all coins of this denomination that
       // were put into circulation (and thus the maximum loss the
       // exchange may experience due to this emergency).
       risk : Amount;
 
       // When did the exchange start issuing coins in this the denomination.
       start : Timestamp;
 
       // When does the deposit period end for coins of this denomination.
       deposit_end : Timestamp;
 
       // What is the value of an individual coin of this denomination.
       value : Amount;
 
       // True if this diagnostic was suppressed.
       suppressed : boolean;
 
     }
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 .. http:patch:: /monitoring/emergency-by-count/$SERIAL_ID
 
   This endpoint is used to suppress select elements of emergencies by count.
   Update the 'suppressed' field of an emergency by count element with row ID
   ``$SERIAL_ID``, according to :ts:type:`GenericAuditorMonitorPatchRequest`,
   stored by the auditor.
 
   **Request:**
 
   The body must be a `GenericAuditorMonitorPatchRequest`.
 
   **Response:**
 
   :http:statuscode:`204 No Content`:
     The element has been updated.
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 .. _row-inconsistency-list:
 
 Row Inconsistencies
 -------------------
 
 This section highlights inconsistencies in a specific row of a specific table
 of the exchange.  Row inconsistencies are reported from different sources, and
 largely point to some kind of data corruption (or bug). Nothing is implied
 about the seriousness of the inconsistency. Most inconsistencies are detected
 if some signature fails to validate. The affected table is noted in the
 'table' field. A description of the nature of the inconsistency is noted in
 'diagnostic'.
 
 .. http:get:: /monitoring/row-inconsistency
 
   Get a list of row inconsistencies stored by the auditor.
 
   The following query parameters are optional, and can be used to customise the response:
 
   **Request:**
 
   :query limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
   :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
   :query return_suppressed: A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.
 
   With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The auditor responds with a top level array of :ts:type:`RowInconsistency` objects.
 
   **Details:**
 
   .. ts:def:: RowInconsistency
 
     interface RowInconsistency {
 
       // Number of the affected row.
       row_id : Integer;
 
       // Name of the affected exchange table.
       row_table : string;
 
       // Human-readable diagnostic about what went wrong.
       diagnostic : string;
 
       // True if this diagnostic was suppressed.
       suppressed : boolean;
 
     }
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 .. http:patch:: /monitoring/row-inconsistency/$SERIAL_ID
 
   This endpoint is used to suppress select elements of row inconsistencies.
   Update the 'suppressed' field of a row inconsistency element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
 
   **Response:**
 
   :http:statuscode:`204 No Content`:
     The element has been updated.
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 .. _reserve-in-inconsistency-list:
 
 Reserve In Inconsistencies
 --------------------------
 
 This section lists cases where the exchange's and auditor's expectation of
 amounts transferred into a reserve differs.  Basically, the exchange database
 states that a certain reserve was credited for a certain amount via a wire
 transfer, but the auditor disagrees about this basic fact.  This may result in
 either a customer loosing funds (by being issued less digital cash than they
 should be) or the exchange loosing funds (by issuing a customer more digital
 cash than they should be).
 
 .. http:get:: /monitoring/reserve-in-inconsistency
 
   Get a list of reserve in inconsistencies stored by the auditor.
 
   The following query parameters are optional, and can be used to customise the response:
 
   **Request:**
 
   :query limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
   :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
   :query return_suppressed: A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.
 
 
   With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The auditor responds with a top level array of :ts:type:`ReserveInInconsistency` objects.
 
   **Details:**
 
   .. ts:def:: ReserveInInconsistency
 
     interface ReserveInInconsistency {
 
       // Unique row identifier
       row_id : Integer;
 
       // Amount the exchange expects to be in the reserve
       amount_exchange_expected : Amount;
 
       // Amount deposited into the reserve
       amount_wired : Amount;
 
       // Public key of the reserve
       reserve_pub : EddsaPublicKey;
 
       // Time of the deposit
       timestamp : Timestamp;
 
       // Account associated with the reserve
       account : string;
 
       // Human readable diagnostic of the problem
       diagnostic : string;
 
       // True if this diagnostic was suppressed.
       suppressed : boolean;
 
     }
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 
 
 .. http:patch:: /monitoring/reserve-in-inconsistency/$SERIAL_ID
 
   This endpoint is used to suppress select elements of reserve in inconsistencies.
   Update the 'suppressed' field of a reserve in inconsistency element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
 
   **Response:**
 
   :http:statuscode:`204 No Content`:
     The element has been updated.
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 .. _purse-not-closed-inconsistencies-list:
 
 Purse Not Closed Inconsistencies
 --------------------------------
 
 This section highlights cases, in which either payer or payee did not finish
 their part of a P2P payment. This caused a purse --– which may contain some
 money --- to reach its expiration date.  However, the exchange failed to
 properly expire the purse, which means the payer did not get their money back.
 The cause is usually that the **taler-exchange-expire** helper is not running
 properly.
 
 
 .. http:get:: /monitoring/purse-not-closed-inconsistencies
 
   Get a list of purse not closed inconsistencies stored by the auditor.
 
   The following query parameters are optional, and can be used to customise the response:
 
   **Request:**
 
   :query limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
   :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
   :query return_suppressed: A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.
 
   With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The auditor responds with a top level array of :ts:type:`PurseNotClosedInconsistencies` objects.
 
 
 
   **Details:**
 
   .. ts:def:: PurseNotClosedInconsistencies
 
     interface PurseNotClosedInconsistencies {
 
       // Unique row identifier.
       row_id : Integer;
 
       // Public key of the affected purse
       purse_pub : EddsaPublicKey;
 
       // Amount still in the purse, which should have been refunded
       amount : Amount;
 
       // When the purse expired
       expiration_date : Timestamp;
 
       // True if this diagnostic was suppressed.
       suppressed : boolean;
 
     }
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 .. http:patch:: /monitoring/purse-not-closed-inconsistencies/$SERIAL_ID
 
   This endpoint is used to suppress select elements of purse not closed
   inconsistencies.  Update the 'suppressed' field of a purse not closed
   inconsistencies element with row ID ``$SERIAL_ID``, according to
   :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
 
   **Response:**
 
   :http:statuscode:`204 No Content`:
     The element has been updated.
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 Early Aggregations
 ------------------
 
 .. _early-aggregation-list:
 
 
 This endpoint returns cases in which wire transfers are encountered before their
 justifications. This can be harmless, if the justifications appear shortly afterwards.
 
 .. http:get:: /monitoring/early-aggregation
 
   Get a list of early aggregations.
   @since protocol **v2**.
 
   The following query parameters are optional, and can be used to customise the response:
 
   **Request:**
 
   :query limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
   :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
   :query return_suppressed: A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.
 
   With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The auditor responds with a top level array of :ts:type:`GetEarlyAggregationResponse` objects.
 
   **Details:**
 
   .. ts:def:: GetEarlyAggregationResponse
 
     interface GetEarlyAggregationResponse {
 
       // Array of aggregations lacking a justification.
       early_aggregations: EarlyAggregationEntry[];
 
     }
 
   .. ts:def:: EarlyAggregationEntry
 
     interface EarlyAggregationEntry {
 
       // Unique row identifier in the auditor table
       row_id : Integer;
 
       // Row identifier in the exchange's batch deposit table
       batch_deposit_serial_id : Integer;
 
       // Row identifier in the exchange's tracking table
       tracking_serial_id : Integer;
 
       // Amount that was aggregated early.
       balance : Amount;
 
       // True if this diagnostic was suppressed.
       suppressed : boolean;
 
     }
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 
 Pending Deposits
 ----------------
 
 .. _pending-deposits-list:
 
 This endpoint returns cases in which deposits are pending, that is an
 expected wire transfer for a given deposit was not yet found even though
 it is past the wire deadline.
 This can be harmless, if the wire transfers appear shortly afterwards.
 
 .. http:get:: /monitoring/pending-deposits
 
   Get a list of pending deposits.
   @since protocol **v2**.
 
   The following query parameters are optional, and can be used to customise the response:
 
   **Request:**
 
   :query limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
   :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
   :query return_suppressed: A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.
 
   With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The auditor responds with a top level array of :ts:type:`GetPendingDepositsResponse` objects.
 
   **Details:**
 
   .. ts:def:: GetPendingDepositsResponse
 
     interface GetPendingDepositsResponse {
 
       // Array of pending deposits.
       pending_deposits: PendingDepositEntry[];
 
     }
 
   .. ts:def:: PendingDepositEntry
 
     interface PendingDepositEntry {
 
       // Unique row identifier in the auditor table
       row_id : Integer;
 
       // Row identifier in the exchange's batch deposit table
       batch_deposit_serial_id : Integer;
 
       // Amount that was aggregated early.
       total_amount : Amount;
 
       // Hash of the bank account that should have received the funds.
       h_wire : HashCode;
 
       // When was the deadline for the transfer.
       deadline : Timestamp;
 
       // True if this diagnostic was suppressed.
       suppressed : boolean;
 
     }
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 
 
 
 
 .. _reserve-not-closed-inconsistency-list:
 
 Reserve Not Closed Inconsistencies
 ----------------------------------
 
 This section highlights cases, in which reserves were not closed, despite being expired.
 As a result, customers that wired funds to the exchange and then failed to withdraw them
 are not getting their money back. The cause is usually that the **taler-exchange-closer**
 process is not running properly.
 
 .. http:get:: /monitoring/reserve-not-closed-inconsistency
 
   Get a list of reserve not closed inconsistencies stored by the auditor.
 
   The following query parameters are optional, and can be used to customise the response:
 
   **Request:**
 
   :query limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
   :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
   :query return_suppressed: A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.
 
   With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The auditor responds with a top level array of :ts:type:`ReserveNotClosedInconsistency` objects.
 
 
 
   **Details:**
 
   .. ts:def:: ReserveNotClosedInconsistency
 
     interface ReserveNotClosedInconsistency {
 
       // Unique row identifier
       row_id : Integer;
 
       // Public key of the reserve
       reserve_pub : EddsaPublicKey;
 
       // Amount still in the reserve at the time of expiration
       balance : Amount;
 
       // Date the reserve expired
       expiration_time : Timestamp;
 
       // Human readable string describing the problem
       diagnostic : string;
 
       // True if this diagnostic was suppressed.
       suppressed : boolean;
 
     }
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 
 
 .. http:patch:: /monitoring/reserve-not-closed-inconsistency/$SERIAL_ID
 
   This endpoint is used to suppress select elements of reserve not closed
   inconsistencies.  Update the 'suppressed' field of a reserve not closed
   inconsistency element with row ID ``$SERIAL_ID``, according to
   :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
 
   **Response:**
 
   :http:statuscode:`204 No Content`:
     The element has been updated.
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 
 
 .. _reserve-balance-insufficient-inconsistency-list:
 
 Reserve Balance Insufficient Inconsistencies
 --------------------------------------------
 
 This section highlights cases where more coins were withdrawn from a
 reserve than the reserve contained funding for.  This is a serious
 compromise resulting in proportional financial losses to the exchange.
 
 .. http:get:: /monitoring/reserve-balance-insufficient-inconsistency
 
   Get a list of reserve balance insufficient inconsistencies stored by the auditor.
 
   The following query parameters are optional, and can be used to customise the response:
 
   **Request:**
 
   :query limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
   :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
   :query return_suppressed: A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.
 
 
   With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The auditor responds with a top level array of :ts:type:`ReserveBalanceInsufficientInconsistency` objects.
 
 
 
   **Details:**
 
   .. ts:def:: ReserveBalanceInsufficientInconsistency
 
     interface ReserveBalanceInsufficientInconsistency {
 
       // Unique row identifier
       row_id : Integer;
 
       // Public key of the affected reserve
       reserve_pub : EddsaPublicKey;
 
       // Whether this inconsistency is profitable for the exchange
       inconsistency_gain : boolean;
 
       // Amount possibly lost or gained by the exchange
       inconsistency_amount : Amount;
 
       // True if this diagnostic was suppressed.
       suppressed : boolean;
 
     }
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 
 
 
 .. http:patch:: /monitoring/reserve-balance-insufficient-inconsistency/$SERIAL_ID
 
   This endpoint is used to suppress select elements of reserve balance insufficient
   inconsistencies.  Update the 'suppressed' field of a reserve balance
   insufficient inconsistency element with row ID ``$SERIAL_ID``, according to
   :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
 
   **Response:**
 
   :http:statuscode:`204 No Content`:
     The element has been updated.
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 .. _invalid-signature-losses-list:
 
 Invalid Signature Losses
 ------------------------
 
 This section lists operations that the exchange performed, but for which the
 signatures provided are invalid. Hence the operations are invalid and the
 amount involved could be a loss for the exchange (as the involved parties
 could successfully dispute the resulting transactions).
 
 .. http:get:: /monitoring/bad-sig-losses
 
   Get a list of invalid signature losses stored by the auditor.
 
   The following query parameters are optional, and can be used to customise the response:
 
   **Request:**
 
   :query limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
   :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
   :query return_suppressed: A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.
   :query operation: A string. If specified, only returns eligible rows with this :ts:type:`BadSigLosses`.operation value. The default value is NULL which means to not filter by operation.
   :query op_spec_pub: An EddsaPublicKey (in base32 encoding). If given, use its value to only return rows with this :ts:type:`BadSigLosses`.operation_specific_pub value. The default value is NULL.
 
   With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The auditor responds with a top level array of :ts:type:`BadSigLosses` objects.
 
   **Details:**
 
   .. ts:def:: BadSigLosses
 
     interface BadSigLosses {
 
       // Unique row identifier
       row_id : Integer;
 
       // Operation performed, even though a signature was invalid
       operation : string;
 
       // Amount considered lost by the exchange
       loss : Amount;
 
       // Public key associated with an operation
       operation_specific_pub : EddsaPublicKey;
 
       // True if this diagnostic was suppressed.
       suppressed : boolean;
 
     }
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 .. http:patch:: /monitoring/bad-sig-losses/$SERIAL_ID
 
   This endpoint is used to suppress select elements of bad sig losses.  Update the
   'suppressed' field of a bad sig losses element with row ID ``$SERIAL_ID``,
   according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the
   auditor.
 
   **Response:**
 
   :http:statuscode:`204 No Content`:
     The element has been updated.
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 .. _coin-inconsistency-list:
 
 Coin Inconsistencies
 --------------------
 
 This section lists cases where the exchange made arithmetic errors found when
 looking at the transaction history of a coin.  The totals sum up the differences
 in amounts that matter for profit/loss calculations of the exchange. When an
 exchange merely shifted money from customers to merchants (or vice versa) without
 any effects on its own balance, those entries are excluded from the total.
 
 .. http:get:: /monitoring/coin-inconsistency
 
   Get a list of coin inconsistencies stored by the auditor.
 
   The following query parameters are optional, and can be used to customise the response:
 
   **Request:**
 
   :query limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
   :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
   :query return_suppressed: A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.
 
 
   With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The auditor responds with a top level array of :ts:type:`CoinInconsistency` objects.
 
   **Details:**
 
   .. ts:def:: CoinInconsistency
 
     interface CoinInconsistency {
 
       // Unique row identifier
       row_id : Integer;
 
       // The operation performed by the exchange
       operation : string;
 
       // Total the exchange calculated
       exchange_amount : Amount;
 
       // Total the auditor calculated
       auditor_amount : Amount;
 
       // Public key of the coin in question
       coin_pub : EddsaPublicKey;
 
       // Whether this arithmetic error was profitable for the exchange
       profitable : boolean;
 
       // True if this diagnostic was suppressed.
       suppressed : boolean;
 
     }
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 .. http:patch:: /monitoring/coin-inconsistency/$SERIAL_ID
 
   This endpoint is used to suppress select elements of coin inconsistencies.
   Update the 'suppressed' field of a coin inconsistency element with row ID
   ``$SERIAL_ID``, according to :ts:type:`GenericAuditorMonitorPatchRequest`,
   stored by the auditor.
 
   **Response:**
 
   :http:statuscode:`204 No Content`:
     The element has been updated.
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 
 
 .. _denominations-without-signatures-list:
 
 Denominations Without Signatures
 --------------------------------
 
 This section highlights denomination keys that lack a proper
 signature from the **taler-auditor-offline** tool. This may be
 legitimate, say in case where the auditor's involvement in the
 exchange business is ending and a new auditor is responsible for
 future denominations. So this must be read with a keen eye on the
 business situation.
 
 .. http:get:: /monitoring/denominations-without-sigs
 
   Get a list of denominations without signatures stored by the auditor.
 
   The following query parameters are optional, and can be used to customise the response:
 
   **Request:**
 
   :query limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
   :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
   :query return_suppressed: A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.
 
 
   With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The auditor responds with a top level array of :ts:type:`DenominationsWithoutSigs` objects.
 
 
 
   **Details:**
 
   .. ts:def:: DenominationsWithoutSigs
 
     interface DenominationsWithoutSigs {
 
       // Unique row identifier
       row_id : Integer;
 
       // Hash of the denomination public key
       denompub_h : HashCode;
 
       // Value of each coin of the denomination that lacks
       // the auditor's signature.
       value : Amount;
 
       // From when the denomination key in question is valid
       start_time : Timestamp;
 
       // When the denomination key in question expires
       end_time : Timestamp;
 
       // True if this diagnostic was suppressed.
       suppressed : boolean;
 
     }
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 
 .. http:patch:: /monitoring/denominations-without-sigs/$SERIAL_ID
 
   This endpoint is used to suppress select elements of denominations without sigs.
   Update the 'suppressed' field of a denominations without signatures element
   with row ID ``$SERIAL_ID``, according to
   :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
 
   **Response:**
 
   :http:statuscode:`204 No Content`:
     The element has been updated.
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 .. _misattribution-in-inconsistency-list:
 
 Misattribution In Inconsistencies
 ---------------------------------
 
 This section lists cases where the sender account record of an incoming wire
 transfer differs between the exchange and the bank.  This may cause funds to
 be sent to the wrong account should the reserve be closed with a remaining
 balance, as that balance would be credited to the original account.
 
 .. http:get:: /monitoring/misattribution-in-inconsistency
 
   Get a list of misattribution in inconsistencies stored by the auditor.
 
   The following query parameters are optional, and can be used to customise the response:
 
   **Request:**
 
   :query limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
   :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
   :query return_suppressed: A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.
 
 
   With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The auditor responds with a top level array of :ts:type:`MisattributionInInconsistency` objects.
 
 
 
   **Details:**
 
   .. ts:def:: MisattributionInInconsistency
 
     interface MisattributionInInconsistency {
 
       // Unique row identifier in the exchange database.
       row_id : Integer;
 
       // Amount of money sent to the wrong account
       amount : Amount;
 
       // Row of the transaction in the bank database as
       // returned by the bank revenue API.
       bank_row : Integer;
 
       // Public key of the affected reserve
       reserve_pub : EddsaPublicKey;
 
       // True if this diagnostic was suppressed.
       suppressed : boolean;
 
     }
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 
 .. http:patch:: /monitoring/misattribution-in-inconsistency/$SERIAL_ID
 
   This endpoint is used to suppress select elements of misattribution in
   inconsistencies.  Update the 'suppressed' field of an misattribution in
   inconsistency element with row ID ``$SERIAL_ID``, according to
   :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
 
   **Response:**
 
   :http:statuscode:`204 No Content`:
     The element has been updated.
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 
 .. _deposit-confirmations-list:
 
 Deposit Confirmations
 ---------------------
 
 This section contains a list of deposits confirmations that an exchange
 provided to merchants but *failed* to store in its own database.  This is
 indicative of potential fraud by the exchange operator, as the exchange should
 only issue deposit confirmations after storing the respective deposit records
 in its database.  Not storing the deposit data means that the exchange would
 not pay the merchant (pocketing the money) or allow the customer to
 double-spend the money (which is naturally also not good).
 
 Note that entries could appear in this list also because the exchange database
 replication is delayed. Hence, entries that are only a few seconds old might
 not be indicative of an actual problem. If entries in this list are more than
 a few seconds old, the first thing to check is whether or not the database
 replication from the exchange is working properly.
 
 .. http:get:: /monitoring/deposit-confirmations
 
   Get a list of deposit confirmations stored by the auditor.
 
   The following query parameters are optional, and can be used to customise the response:
 
   **Request:**
 
   :query limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
   :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
   :query return_suppressed: A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.
 
   With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The auditor responds with a top level array of :ts:type:`DepositConfirmations` objects.
 
   **Details:**
 
   .. ts:def:: DepositConfirmations
 
     interface DepositConfirmations {
 
       // Row id in the exchange database
       deposit_confirmation_serial_id : Integer;
 
       // Hash over the contract for which this deposit is made.
       h_contract_terms : HashCode;
 
       // Hash over the policy concerning this deposit
       h_policy : HashCode;
 
       // Hash over the wiring information of the merchant.
       h_wire : HashCode;
 
       // Time when the deposit confirmation confirmation was generated.
       exchange_timestamp : Timestamp;
 
       // How much time does the merchant have to issue a refund
       // request?  Zero if refunds are not allowed.
       refund_deadline : Timestamp;
 
       // By what time does the exchange have to wire the funds?
       wire_deadline : Timestamp;
 
       // Amount to be deposited, excluding fee.  Calculated from the
       // amount with fee and the fee from the deposit request.
       total_without_fee : Amount;
 
       // Array of public keys of the deposited coins.
       coin_pubs : EddsaPublicKey[];
 
       // Array of deposit signatures of the deposited coins.
       // Must have the same length as coin_pubs.
       coin_sigs : EddsaSignature[];
 
       // The Merchant's public key.  Allows the merchant to later refund
       // the transaction or to inquire about the wire transfer identifier.
       merchant_pub : EddsaPublicKey;
 
       // Signature from the exchange of type
       // TALER_SIGNATURE_EXCHANGE_CONFIRM_DEPOSIT.
       exchange_sig : EddsaSignature;
 
       // Public signing key from the exchange matching exchange_sig.
       exchange_pub : EddsaPublicKey;
 
       // Exchange master signature over exchange_sig.
       master_sig : EddsaSignature;
 
       // True if this diagnostic was suppressed.
       suppressed : boolean;
 
     }
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 .. http:patch:: /monitoring/deposit-confirmations/$SERIAL_ID
 
   This endpoint is used to suppress select elements of deposit confirmations.
   Update the 'suppressed' field of an deposit confirmations element with
   row ID ``$SERIAL_ID``, according to
   :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
 
   **Response:**
 
   :http:statuscode:`204 No Content`:
     The element has been updated.
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 .. _denomination-key-validity-withdraw-inconsistency-list:
 
 Denomination Key Validity Withdraw Inconsistencies
 --------------------------------------------------
 
 This section highlights cases, where denomination keys were used to sign coins
 withdrawn from a reserve before the denomination was valid or after it was
 already expired for signing.  This doesn't exactly imply any financial loss
 for anyone, it is mostly weird and may have affected the fees the customer
 paid.
 
 .. http:get:: /monitoring/denomination-key-validity-withdraw-inconsistency
 
   Get a list of denomination key validity withdraw inconsistencies stored by the auditor.
   The following query parameters are optional, and can be used to customise the response:
 
   **Request:**
 
   :query limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
   :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
   :query return_suppressed: A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.
 
   With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The auditor responds with a top level array of :ts:type:`DenominationKeyValidityWithdrawInconsistency` objects. If no elements could be found, an empty array is returned
 
 
   **Details:**
 
   .. ts:def:: DenominationKeyValidityWithdrawInconsistency
 
     interface DenominationKeyValidityWithdrawInconsistency {
 
       // Unique row identifier
       row_id : Integer;
 
       // When the withdrawal took place
       execution_date : Timestamp;
 
       // Public key of the reserve affected
       reserve_pub : EddsaPublicKey;
 
       // Hash of the denomination public key involved in the withdrawal
       denompub_h : HashCode;
 
       // True if this diagnostic was suppressed.
       suppressed : boolean;
 
     }
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 .. http:patch:: /monitoring/denomination-key-validity-withdraw-inconsistency/$SERIAL_ID
 
   This endpoint is used to suppress select elements of denomination key validity withdraw inconsistencies.
   Update the 'suppressed' field of a denomination key validity withdraw inconsistency element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
 
   **Response:**
 
   :http:statuscode:`204 No Content`:
     The element has been updated.
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 .. _amount-arithmetic-inconsistency-list:
 
 Amount Arithmetic Inconsistencies
 ---------------------------------
 
 This endpoint is used to obtain a list of amount arithmetic inconsistencies.
 
 This section lists cases where the arithmetic of the exchange involving
 amounts disagrees with the arithmetic of the auditor.  Disagreements imply
 that either the exchange made a loss (sending out too much money), or screwed
 a customer (and thus at least needs to fix the financial damage done to the
 customer).  The profitable column is set to true if the arithmetic problem was
 be determined to be profitable for the exchange, false if the problem resulted
 in a net loss for the exchange.
 
 
 .. http:get:: /monitoring/amount-arithmetic-inconsistency
 
   Get a list of amount arithmetic inconsistencies stored by the auditor.
 
   The following query parameters are optional, and can be used to customise the response:
 
   **Request:**
 
   :query limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
   :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
   :query return_suppressed: A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.
 
 
   With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The auditor responds with a top level array of :ts:type:`AmountArithmeticInconsistency` objects. If no elements could be found, an empty array is returned
 
 
 
   **Details:**
 
   .. ts:def:: AmountArithmeticInconsistency
 
     interface AmountArithmeticInconsistency {
 
       // Unique row identifier
       row_id : Integer;
 
       // Name of the arithmetic operation performed
       operation : string;
 
       // Amount according to the exchange
       exchange_amount : Amount;
 
       // Amount according to the auditor
       auditor_amount : Amount;
 
       // Whether the miscalculation is profitable for the exchange
       profitable : boolean;
 
       // True if this diagnostic was suppressed.
       suppressed : boolean;
 
     }
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 .. http:patch:: /monitoring/amount-arithmetic-inconsistency/$SERIAL_ID
 
   This endpoint is used to suppress select elements of amount arithmetic inconsistencies. Update the 'suppressed' field of an amount arithmetic inconsistency element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
 
   **Response:**
 
   :http:statuscode:`204 No Content`:
     The element has been updated.
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 .. _wire-format-inconsistency-list:
 
 Wire Format Inconsistencies
 ---------------------------
 
 This section highlights cases where the wire transfer subject
 was used more than once and is thus not unique.  This indicates
 a problem with the bank's implementation of the revenue API, as
 the bank is supposed to warrant uniqueness of wire transfer
 subjects exposed via the revenue API (and bounce non-unique
 transfers).
 
 .. http:get:: /monitoring/wire-format-inconsistency
 
   Get a list of wire format inconsistencies stored by the auditor.
 
   The following query parameters are optional, and can be used to customise the response:
 
   **Request:**
 
   :query limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
   :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
   :query return_suppressed: A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.
 
   With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The auditor responds with a top level array of :ts:type:`WireFormatInconsistency` objects. If no elements could be found, an empty array is returned
 
 
   **Details:**
 
   .. ts:def:: WireFormatInconsistency
 
     interface WireFormatInconsistency {
 
       // Unique row identifier
       row_id : Integer;
 
       // Amount that was part of the wire
       amount : Amount;
 
       // Offset of the duplicate wire transfer subject
       // in the bank database according to the revenue API.
       wire_offset : Integer;
 
       // True if this diagnostic was suppressed.
       diagnostic : string;
 
       // True if this diagnostic was suppressed.
       suppressed : boolean;
 
 
     }
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 
 
 .. http:patch:: /monitoring/wire-format-inconsistency/$SERIAL_ID
 
   This endpoint is used to suppress select elements of wire format inconsistencies.
   Update the 'suppressed' field of a wire format inconsistency element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
 
   **Response:**
 
   :http:statuscode:`204 No Content`:
     The element has been updated.
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 .. _closure-lags-list:
 
 Closure Lags
 ------------
 
 This endpoint is used to obtain a list of closure lags.
 
 A closure lag happens if a reserve should have closed a reserve and
 wired (remaining) funds back to the originating account, but did not
 do so on time.  Significant lag may be indicative of fraud, while
 moderate lag is indicative that the systems may be too slow to handle the
 load. Small amounts of lag can occur in normal operation.
 
 If closure lag is experienced, the administrator should check that
 the **taler-exchange-closer** component is operating correctly.
 
 
 .. http:get:: /monitoring/closure-lags
 
   Get a list of closure lags stored by the auditor.
 
   The following query parameters are optional, and can be used to customise the response:
 
   **Request:**
 
   :query limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
   :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
   :query return_suppressed: A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.
 
 
   With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The auditor responds with a top level array of :ts:type:`ClosureLags` objects. If no elements could be found, an empty array is returned
 
 
 
   **Details:**
 
   .. ts:def:: ClosureLags
 
     interface ClosureLags {
 
       // Unique row identifier
       row_id : Integer;
 
       // Amount of money left in the reserve
       amount : Amount;
 
       // When should the reserve have been closed
       deadline : Timestamp;
 
       // The wire transfer identifier
       wtid : HashCode;
 
       // Full payto:// URI (RFC 8905) of the account that
       // should have been credited.
       account : string;
 
       // True if this diagnostic was suppressed.
       suppressed : boolean;
 
     }
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 .. http:patch:: /monitoring/closure-lags/$SERIAL_ID
 
   This endpoint is used to suppress select elements of closure lags.
   Update the 'suppressed' field of a closure lags element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
 
   **Response:**
 
   :http:statuscode:`204 No Content`:
     The element has been updated.
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 
 
 .. _wire-out-inconsistency-list:
 
 Wire Out Inconsistencies
 ------------------------
 
 This section highlights cases where the exchange wired a different amount to a
 destimation account than the auditor expected.
 
 .. http:get:: /monitoring/wire-out-inconsistency
 
   Get a list of wire out inconsistencies stored by the auditor.
 
   The following query parameters are optional, and can be used to customise the response:
 
   **Request:**
 
   :query limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
   :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
   :query return_suppressed: A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.
 
 
   With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The auditor responds with a top level array of :ts:type:`WireOutInconsistency` objects. If no elements could be found, an empty array is returned
 
 
 
   **Details:**
 
   .. ts:def:: WireOutInconsistency
 
     interface WireOutInconsistency {
 
       // Unique row identifier
       row_id : Integer;
 
       // Account money was wired to
       destination_account : string;
 
       // How much was suppossed to be wired according to the auditor.
       expected : Amount;
 
       // The amount the exchange claims to have wired.
       claimed : Amount;
 
       // True if this diagnostic was suppressed.
       suppressed : boolean;
 
     }
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 
 
 
 .. http:patch:: /monitoring/wire-out-inconsistency/$SERIAL_ID
 
   This endpoint is used to suppress select elements of wire out inconsistencies.
   Update the 'suppressed' field of a wire out inconsistency element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
 
   **Response:**
 
   :http:statuscode:`204 No Content`:
     The element has been updated.
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 .. _reserve-balance-summary-wrong-inconsistency-list:
 
 Reserve Balance Summary Wrong Inconsistencies
 ---------------------------------------------
 
 This section highlights cases, where the exchange's and auditors'
 expectation of the amount of money left in a reserve differs.
 
 .. http:get:: /monitoring/reserve-balance-summary-wrong-inconsistency
 
   Get a list of reserve balance summary wrong inconsistencies stored by the auditor.
 
   The following query parameters are optional, and can be used to customise the response:
 
   **Request:**
 
   :query limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
   :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
   :query return_suppressed: A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.
 
   With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The auditor responds with a top level array of :ts:type:`ReserveBalanceSummaryWrongInconsistency` objects. If no elements could be found, an empty array is returned
 
   **Details:**
 
   .. ts:def:: ReserveBalanceSummaryWrongInconsistency
 
     interface ReserveBalanceSummaryWrongInconsistency {
 
       // Unique row identifier
       row_id : Integer;
 
       // Public key of the reserve affected
       reserve_pub : EddsaPublicKey;
 
       // Amount of summary the exchange calculated
       exchange_amount : Amount;
 
       // Amount of summary the auditor calculated
       auditor_amount : Amount;
 
       // True if this diagnostic was suppressed.
       suppressed : boolean;
 
     }
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 .. http:patch:: /monitoring/reserve-balance-summary-wrong-inconsistency/$SERIAL_ID
 
   This endpoint is used to suppress select elements of reserve balance summary wrong inconsistencies.
   Update the 'suppressed' field of a reserve balance summary wrong inconsistency element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
 
   **Response:**
 
   :http:statuscode:`204 No Content`:
     The element has been updated.
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 .. _row-minor-inconsistencies-list:
 
 Row Minor Inconsistencies
 -------------------------
 
 The section highlights inconsistencies where a row in an exchange table has a
 value that is does not satisfy expectations (such as a malformed
 signature). These are cause for concern, but not necessarily point to a
 monetary loss (yet).
 
 .. http:get:: /monitoring/row-minor-inconsistencies
 
   Get a list of row minor inconsistencies stored by the auditor.
 
   The following query parameters are optional, and can be used to customise the response:
 
   **Request:**
 
   :query limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
   :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
   :query return_suppressed: A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.
 
   With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The auditor responds with a top level array of :ts:type:`RowMinorInconsistencies` objects. If no elements could be found, an empty array is returned
 
   **Details:**
 
   .. ts:def:: RowMinorInconsistencies
 
     interface RowMinorInconsistencies {
 
       // Number of the row in the affected table
       row_id : Integer;
 
       // The row number in the affected table
       row_table : Integer;
 
       // Human readable string describing the problem
       diagnostic : string;
 
       // True if this diagnostic was suppressed.
       suppressed : boolean;
 
     }
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 .. http:patch:: /monitoring/row-minor-inconsistencies/$SERIAL_ID
 
   This endpoint is used to suppress select elements of row minor inconsistencies.
   Update the 'suppressed' field of a row minor inconsistencies element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
 
   **Response:**
 
   :http:statuscode:`204 No Content`:
     The element has been updated.
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 -------------------------
 Monitoring Auditor Status
 -------------------------
 
 The following entries specify how to access information the auditor keeps to
 properly perform audits.  These tables do not contain inconsistencies, instead
 they store information about balances, reserves, purses etc.  Values in these
 tables should not differ from their respective exchanges' version.
 
 .. _balances-list:
 
 Balances
 --------
 
 Returns the various balances the auditor tracks for the exchange, such as
 coins in circulation, fees earned, losses experienced, etc.
 
 .. http:get:: /monitoring/balances
 
   Get a list of balances stored by the auditor.
 
   The following query parameters are optional, and can be used to customise the response:
 
   **Request:**
 
   :query balance_key: a string identifying a balance. If specified, only returns the balance with this exact key. The default value is NULL.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The auditor responds with a top level array of :ts:type:`Balances` objects. If no elements could be found, an empty array is returned
 
   **Details:**
 
   .. ts:def:: Balances
 
     interface Balances {
 
       // String identifying a balance
       balance_key : string;
 
       // Amount of the balance
       balance_value : Amount;
 
     }
 
 
 .. _historic-denomination-revenue-list:
 
 Historic Denomination Revenue
 -----------------------------
 
 This endpoint is used to obtain a list of historic denomination revenue, that
 is the profits and losses an exchange has made from coins of a particular
 denomination where the denomination is past its (deposit) expiration and thus
 all values are final.
 
 .. http:get:: /monitoring/historic-denomination-revenue
 
   Get a list of historic denomination revenue stored by the auditor.
 
   The following query parameters are optional, and can be used to customise the response:
 
   **Request:**
 
   :query limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
   :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
 
   With the default settings, the endpoint returns at most the 20 latest elements.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The auditor responds with a top level array of :ts:type:`HistoricDenominationRevenue` objects. If no elements could be found, an empty array is returned
 
   **Details:**
 
   .. ts:def:: HistoricDenominationRevenue
 
     interface HistoricDenominationRevenue {
 
       // Unique row identifier
       row_id : Integer;
 
       // Hash code of the denomination public key involved
       denom_pub_hash : HashCode;
 
       // Time when the denomination expired and thus the revenue
       // was computed.
       revenue_timestamp : Timestamp;
 
       // Total fee revenue the exchange earned from coins of this
       // denomination.
       revenue_balance : Amount;
 
       // Total losses the exchange experienced from this denomination
       // (this basically only happens if someone was able to forge
       // denomination signatures). So non-zero values are indicative
       // of a serious problem.
       loss_balance : Amount;
 
     }
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 .. _denomination-pending-list:
 
 Denomination Pending
 --------------------
 
 This endpoint is used to obtain a list of balances for denominations that are still
 active, that is coins may still be deposited (or possibly even withdrawn) and thus
 the amounts given are not final.
 
 .. http:get:: /monitoring/denomination-pending
 
   Get a list of denomination pending stored by the auditor.
 
   The following query parameters are optional, and can be used to customise the response:
 
   **Request:**
 
   :query limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
   :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
 
   With the default settings, the endpoint returns at most the 20 latest elements.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The auditor responds with a top level array of :ts:type:`DenominationPending` objects. If no elements could be found, an empty array is returned
 
   **Details:**
 
   .. ts:def:: DenominationPending
 
     interface DenominationPending {
 
       // Unique row identifier
       row_id : Integer;
 
       // Hash of the denomination public key
       denom_pub_hash : HashCode;
 
       // Total value of coins remaining in circulation (excluding
       // the value of coins that were recouped, those are always
       // just under recoup_loss).
       denom_balance : Amount;
 
       // Total value of coins redeemed that exceeds the amount we
       // put into circulation. Basically, this value grows if we
       // wanted to reduce denom_balance (because a coin was deposited)
       // but we could not because the denom_balance was already zero.
       denom_loss : Amount;
 
       // Total number of coins of this denomination that were
       // put into circulation.
       num_issued : Integer;
 
       // Total value of the coins put into circulation.
       denom_risk : Amount;
 
       // Losses the exchange had from this denomination due to coins
       // that were recouped (after the denomination was revoked).
       recoup_loss : Amount;
 
     }
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 .. _historic-reserve-summary-list:
 
 Historic Reserve Summary
 ------------------------
 
 This section summarizes historic profits an exchange
 made from reserves and associated reserve-specific
 fees.
 
 .. http:get:: /monitoring/historic-reserve-summary
 
   Get a list of historic reserve summary stored by the auditor.
 
   The following query parameters are optional, and can be used to customise the response:
 
   **Request:**
 
   :query limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
   :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
 
   With the default settings, the endpoint returns at most the 20 latest elements.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The auditor responds with a top level array of :ts:type:`HistoricReserveSummary` objects. If no elements could be found, an empty array is returned
 
   **Details:**
 
   .. ts:def:: HistoricReserveSummary
 
     interface HistoricReserveSummary {
 
       // Unique row identifier
       row_id : Integer;
 
       // From when the summary starts
       start_date : Timestamp;
 
       // When the summary ends
       end_date : Timestamp;
 
       // Profits the exchange charged for the reserve
       reserve_profits : Amount;
 
     }
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 .. _reserves-list:
 
 
 Reserves
 --------
 
 This endpoint is used to obtain a list of open reserves that the auditor is
 currently tracking balances for.
 
 .. http:get:: /monitoring/reserves
 
   Get a list of reserves stored by the auditor.
 
   The following query parameters are optional, and can be used to customise the response:
 
   **Request:**
 
   :query limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
   :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
 
 
   With the default settings, the endpoint returns at most the 20 latest elements.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The auditor responds with a top level array of :ts:type:`Reserves` objects. If no elements could be found, an empty array is returned
 
 
   **Details:**
 
   .. ts:def:: Reserves
 
     interface Reserves {
 
       // Unique row identifier
       auditor_reserves_rowid : Integer;
 
       // Public key of the reserve
       reserve_pub : EddsaPublicKey;
 
       // Amount in the balance
       reserve_balance : Amount;
 
       // Reserve losses are incurred if (a) a reserve is
       // incorrectly credited from a recoup for a non-revoked
       // coin, or (b) if the exchange allowed more digital cash
       // to be withdrawn from a reserve than the balance of the
       // reserve should have permitted.  FIXME: We may want to
       // distinguish these two cases in the future.
       reserve_loss : Amount;
 
       // Amount earned by charging withdraw fees
       withdraw_fee_balance : Amount;
 
       // Amount earned by charging a closing fee on the reserve
       close_fee_balance : Amount;
 
       // Total purse fees earned from this reserve
       purse_fee_balance : Amount;
 
       // Total reserve open fees earned from the reserve
       open_fee_balance : Amount;
 
       // Total reserve history fees earned from this reserve
       history_fee_balance : Amount;
 
       // When the purse expires
       expiration_date : Timestamp;
 
       // Who created the account
       origin_account : string;
 
     }
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
 
 .. _purses-list:
 
 Purses
 ------
 
 This endpoint is used to obtain information about open purses.
 
 .. http:get:: /monitoring/purses
 
   Get a list of purses stored by the auditor.
 
   The following query parameters are optional, and can be used to customise the response:
 
   **Request:**
 
   :query limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
   :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
 
   With the default settings, the endpoint returns at most the 20 latest elements.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The auditor responds with a top level array of :ts:type:`Purses` objects. If no elements could be found, an empty array is returned
 
   **Details:**
 
   .. ts:def:: Purses
 
     interface Purses {
 
       // Unique row identifier
       auditor_purses_rowid : Integer;
 
       // Public key of the purse
       purse_pub : EddsaPublicKey;
 
       // Amount currently stored in the purse
       balance : Amount;
 
       // Amount the purse is intended for / the maximum amount that can be in the purse
       target : Amount;
 
       // When the purse expires
       expiration_date : Timestamp;
 
     }
 
   .. note::
 
     This endpoint is still experimental. The endpoint will be further developed as needed.
 
   .. _progress-list:
 
 Progress
 --------
 
 This section contains information about the auditing progress an auditor has made.
 
 .. http:get:: /monitoring/progress
 
   Get the progress stored by the auditor.
 
   **Request:**
 
   :query progress_key: a string identifying a progress point. If specified, only returns the element with this exact key. The default value is NULL.
 
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The auditor responds with a top level array of :ts:type:`Progress` objects. If no elements could be found, an empty array is returned
 
   **Details:**
 
   .. ts:def:: Progress
 
     interface Progress {
 
       // Key associated with a given progress point
       progress_key: string;
 
       // How much of the exchanges data has been processed so far
       progress_offset: Integer;
 
     }
 
 ----------
 Complaints
 ----------
 
 This endpoint is used by the wallet or merchants to submit proof of
 misbehavior of an exchange to the auditor.
 
 .. note::
 
    To be designed and implemented.
 
 .. http:put:: /complain
 
 Complain about misbehavior to the auditor.