getBalancesread-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.

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[];
}

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;
}

interface WalletRefreshInfo {
  risks: CashExpirationRisk[];
  recoveries: CashRenewalNotice[];
  annualCostBound: AnnualRefreshCostBound;
}

interface CashExpirationRisk {
  exchangeBaseUrl: string;
  exchangeMasterPub: string;
  amount: AmountString;
  earliestDepositExpiration: TalerProtocolTimestamp;
  reason:
    | "pending"
    | "connectivity"
    | "exchange-error"
    | "no-replacement"
    | "checking"
    | "invalid-lifetime";
}

interface CashRenewalNotice {
  warningId: string;
  exchangeBaseUrl: string;
  exchangeMasterPub: string;
  amount: AmountString;
  oldDepositExpiration: TalerProtocolTimestamp;
  newDepositExpiration: TalerProtocolTimestamp;
  // Earliest emergency threshold of the renewed coins.
  nextRelevantDate: TalerProtocolTimestamp;
}

// 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[];
    }
);

// Scope of a balance; identifies the trust domain
// the funds belong to.
type ScopeInfo =
  | ScopeInfoGlobal
  | ScopeInfoExchange
  | ScopeInfoAuditor
  | ScopeInfoExchangeLegacyKeys;

// Funds held with an exchange that is globally
// trusted for the currency.
type ScopeInfoGlobal = {
  type: "global";
  currency: string;
};

// Funds held at one particular exchange.
type ScopeInfoExchange = {
  type: "exchange";
  currency: string;
  url: string;
};

// Funds whose denominations are audited by a globally
// trusted auditor.
type ScopeInfoAuditor = {
  type: "auditor";
  currency: string;
  url: string;
};

// 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;
};

// 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";

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;
}