taler-docs

get-balances.rst (5754B)

---

 .. ts:op:: getBalances
   :read-only:
 
   Get current wallet balance.
 
   Balances are reported per *scope* (`ScopeInfo`): funds held globally
   for a currency, at a particular exchange, under a particular auditor
   or under a superseded exchange master key are reported as separate
   balances.
 
   **Request:**
 
   This operation takes no arguments (an empty object).
 
   **Response:**
 
   On success, the result is a `BalancesResponse` object.
 
   **Details:**
 
   Each balance distinguishes three amounts.  ``available`` is the
   balance available for spending from transactions in their final state,
   plus amounts expected to become available from pending refreshes.
   ``pendingIncoming`` is the expected positive delta to the available
   balance once pending operations (such as withdrawals or incoming peer
   payments) reach the "done" state.  ``pendingOutgoing`` is the amount
   currently allocated to spend operations that could still be aborted,
   in which case part of the amount may be recovered.
 
 .. ts:def:: BalancesResponse
 
   interface BalancesResponse {
     // Electronic cash balances, per currency scope.
     balances: WalletBalance[];
 
     // Does the user have money from an exchange other than demo or test?
     haveProdBalance: boolean;
 
     // Summary of donations, per donau/year/currency.
     donauSummary?: DonauSummaryItem[];
   }
 
 .. ts:def:: WalletBalance
 
   interface WalletBalance {
     // DD71 expiry information and conditional
     // cost of keeping this balance.
     refreshInfo?: WalletRefreshInfo;
 
     // Scope of the funds covered by this balance.
     scopeInfo: ScopeInfo;
 
     // Balance available for spending, including amounts
     // expected from pending refreshes.
     available: AmountString;
 
     // Expected positive delta to the available balance
     // from pending operations.
     pendingIncoming: AmountString;
 
     // Amount allocated to spend operations that could still be aborted.
     pendingOutgoing: AmountString;
 
     // Pending KYC or confirmation steps affecting this balance.
     flags: BalanceFlag[];
 
     // Available URLs for pages that list
     // where money in this scope can be spent.
     shoppingUrls?: string[];
 
     // Are p2p payments disabled for this scope?
     disablePeerPayments?: boolean;
 
     // Are wallet deposits disabled for this scope?
     disableDirectDeposits?: boolean;
   }
 
 .. ts:def:: WalletRefreshInfo
 
   interface WalletRefreshInfo {
     risks: CashExpirationRisk[];
     recoveries: CashRenewalNotice[];
     annualCostBound: AnnualRefreshCostBound;
   }
 
 .. ts:def:: CashExpirationRisk
 
   interface CashExpirationRisk {
     exchangeBaseUrl: string;
     exchangeMasterPub: string;
     amount: AmountString;
     earliestDepositExpiration: TalerProtocolTimestamp;
     reason:
       | "pending"
       | "connectivity"
       | "exchange-error"
       | "no-replacement"
       | "checking"
       | "invalid-lifetime";
   }
 
 .. ts:def:: CashRenewalNotice
 
   interface CashRenewalNotice {
     warningId: string;
     exchangeBaseUrl: string;
     exchangeMasterPub: string;
     amount: AmountString;
     oldDepositExpiration: TalerProtocolTimestamp;
     newDepositExpiration: TalerProtocolTimestamp;
     // Earliest emergency threshold of the renewed coins.
     nextRelevantDate: TalerProtocolTimestamp;
   }
 
 .. ts:def:: AnnualRefreshCostBound
 
   // Conditional on stable, continuously available compatible
   // offerings and timely reveal.
   type AnnualRefreshCostBound = {
     horizonDays: 365;
     projection: "stable-current-offerings";
   } & (
     | {
         status: "available";
         amount: AmountString;
       }
     | {
         status: "unavailable";
         reasons: string[];
       }
   );
 
 .. ts:def:: ScopeInfo
 
   // Scope of a balance; identifies the trust domain
   // the funds belong to.
   type ScopeInfo =
     | ScopeInfoGlobal
     | ScopeInfoExchange
     | ScopeInfoAuditor
     | ScopeInfoExchangeLegacyKeys;
 
 .. ts:def:: ScopeInfoGlobal
 
   // Funds held with an exchange that is globally
   // trusted for the currency.
   type ScopeInfoGlobal = {
     type: "global";
     currency: string;
   };
 
 .. ts:def:: ScopeInfoExchange
 
   // Funds held at one particular exchange.
   type ScopeInfoExchange = {
     type: "exchange";
     currency: string;
     url: string;
   };
 
 .. ts:def:: ScopeInfoAuditor
 
   // Funds whose denominations are audited by a globally
   // trusted auditor.
   type ScopeInfoAuditor = {
     type: "auditor";
     currency: string;
     url: string;
   };
 
 .. ts:def:: ScopeInfoExchangeLegacyKeys
 
   // Funds issued under a master public key that the exchange has
   // since replaced; never pooled with funds under the current key.
   type ScopeInfoExchangeLegacyKeys = {
     type: "exchange-legacy-keys";
     currency: string;
     url: string;
     // The superseded key the funds were issued under.
     masterPub: string;
   };
 
 .. ts:def:: BalanceFlag
 
   // Flag marking a pending KYC, AML or confirmation step for
   // the incoming or outgoing funds of a balance.
   type BalanceFlag =
     | "incoming-kyc"
     | "incoming-aml"
     | "incoming-confirmation"
     | "outgoing-kyc";
 
 .. ts:def:: DonauSummaryItem
 
   interface DonauSummaryItem {
     // Base URL of the donau service.
     donauBaseUrl: string;
 
     // Legal domain of the donau service (if available).
     legalDomain?: string;
 
     // Year of the donation(s).
     year: number;
 
     // Sum of donation receipts received from merchants
     // in the applicable year.
     amountReceiptsAvailable: AmountString;
 
     // Sum of donation receipts already submitted to the
     // donau in the applicable year.
     amountReceiptsSubmitted: AmountString;
 
     // Amount of the latest available statement.  Missing
     // if no statement was requested yet.
     amountStatement?: AmountString;
   }