taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

get-balance-detail.rst (2946B)

      1 .. ts:op:: getBalanceDetail
      2   :read-only:
      3 
      4   Get detailed balance information for one currency.
      5 
      6   Unlike :ts:op:`getBalances`, which reports one balance per scope,
      7   this operation aggregates the wallet's funds in the given currency
      8   across all exchanges known to the wallet and reports how much of the
      9   balance is spendable under progressively stricter criteria.
     10 
     11   **Request:**
     12 
     13   The request ``args`` must be a `GetBalanceDetailRequest` object.
     14 
     15   **Response:**
     16 
     17   On success, the result is a `PaymentBalanceDetails` object.
     18 
     19   **Details:**
     20 
     21   ``balanceAvailable`` covers funds available for spending, including
     22   amounts expected from pending refreshes.  ``balanceMaterial`` is the
     23   balance the wallet believes it could spend right now, without waiting
     24   for any operations to complete.  The remaining balances are subsets
     25   of the material balance: ``balanceAgeAcceptable`` applies an age
     26   restriction (always zero for this operation), the
     27   ``balanceReceiver*Acceptable`` balances restrict to funds that a
     28   receiver accepts based on exchange URL, exchange public key or
     29   auditor URL, and the depositable balances additionally require that
     30   the funds can be deposited via a supported wire method.  Coins signed
     31   by a master key that the exchange has since replaced (and not
     32   re-advertised) are excluded from all of these balances, as coin
     33   selection would never pick them; unlike in :ts:op:`getBalances`, they
     34   are not reported at all here.
     35 
     36 .. ts:def:: GetBalanceDetailRequest
     37 
     38   interface GetBalanceDetailRequest {
     39     // Currency to compute the balance details for.
     40     currency: string;
     41   }
     42 
     43 .. ts:def:: PaymentBalanceDetails
     44 
     45   interface PaymentBalanceDetails {
     46     // Balance of type "available" (see details above).
     47     balanceAvailable: AmountJson;
     48 
     49     // Balance of type "material" (see details above).
     50     balanceMaterial: AmountJson;
     51 
     52     // Balance of type "age-acceptable" (see details above).
     53     balanceAgeAcceptable: AmountJson;
     54 
     55     // Balance of type "receiver-acceptable" (see details above).
     56     // Deprecated, use the balanceReceiver*Acceptable balances instead.
     57     balanceReceiverAcceptable: AmountJson;
     58 
     59     // Balance of type "receiver-exchange-url-acceptable".
     60     balanceReceiverExchangeUrlAcceptable: AmountJson;
     61 
     62     // Balance of type "receiver-exchange-pub-acceptable".
     63     balanceReceiverExchangePubAcceptable: AmountJson;
     64 
     65     // Balance of type "receiver-auditor-url-acceptable".
     66     balanceReceiverAuditorUrlAcceptable: AmountJson;
     67 
     68     // Balance of type "receiver-depositable".
     69     balanceReceiverDepositable: AmountJson;
     70 
     71     // Balance that is depositable with the exchange, reduced by the
     72     // exchange's debit restrictions and wire fee configuration.
     73     balanceExchangeDepositable: AmountJson;
     74 
     75     // Estimated maximum amount that the wallet could pay for,
     76     // under the assumption that the merchant pays absolutely no fees.
     77     maxMerchantEffectiveDepositAmount: AmountJson;
     78   }