get-balances.rst (6568B)
1 .. ts:op:: getBalances 2 :read-only: 3 4 Get current wallet balance. 5 6 Balances are reported per *scope* (`ScopeInfo`): funds held globally 7 for a currency, at a particular exchange, under a particular auditor 8 or under a superseded exchange master key are reported as separate 9 balances. 10 11 **Request:** 12 13 This operation takes no arguments (an empty object). 14 15 **Response:** 16 17 On success, the result is a `BalancesResponse` object. 18 19 **Details:** 20 21 Each balance distinguishes three amounts. ``available`` is the 22 balance available for spending from transactions in their final state, 23 plus amounts expected to become available from pending refreshes. 24 ``pendingIncoming`` is the expected positive delta to the available 25 balance once pending operations (such as withdrawals or incoming peer 26 payments) reach the "done" state. ``pendingOutgoing`` is the amount 27 currently allocated to spend operations that could still be aborted, 28 in which case part of the amount may be recovered. 29 30 .. ts:def:: BalancesResponse 31 32 interface BalancesResponse { 33 // Electronic cash balances, per currency scope. 34 balances: WalletBalance[]; 35 36 // Does the user have money from an exchange other than demo or test? 37 haveProdBalance: boolean; 38 39 // Summary of donations, per donau/year/currency. 40 donauSummary?: DonauSummaryItem[]; 41 } 42 43 .. ts:def:: WalletBalance 44 45 interface WalletBalance { 46 // True when funds in this scope are at risk of expiring. 47 hasExpirationRisk?: boolean; 48 49 // Scope of the funds covered by this balance. 50 scopeInfo: ScopeInfo; 51 52 // Balance available for spending, including amounts 53 // expected from pending refreshes. 54 available: AmountString; 55 56 // Expected positive delta to the available balance 57 // from pending operations. 58 pendingIncoming: AmountString; 59 60 // Amount allocated to spend operations that could still be aborted. 61 pendingOutgoing: AmountString; 62 63 // Pending KYC or confirmation steps affecting this balance. 64 flags: BalanceFlag[]; 65 66 // Available URLs for pages that list 67 // where money in this scope can be spent. 68 shoppingUrls?: string[]; 69 70 // Are p2p payments disabled for this scope? 71 disablePeerPayments?: boolean; 72 73 // Are wallet deposits disabled for this scope? 74 disableDirectDeposits?: boolean; 75 } 76 77 .. ts:op:: getBalanceRefreshInfo 78 :read-only: 79 80 Takes ``{ scopeInfo: ScopeInfo }`` and returns the current 81 `WalletRefreshInfo` for the requested balance, or ``null`` if that balance 82 no longer exists. The request waits for a fresh calculation. The annual 83 cost bound can be unavailable when the wallet lacks sufficient information. 84 85 .. ts:op:: observeBalanceRefreshInfo 86 87 Takes ``{ scopeInfo: ScopeInfo, observationId: string }`` and returns 88 an empty object. Install the notification listener before registering. 89 The ID follows the same uniqueness and lifetime rules as 90 :ts:op:`observeTransaction`. The initial report and subsequent distinct 91 reports arrive as `BalanceRefreshSnapshotNotification` snapshots. A null 92 report ends the observation when the scope is absent. Use 93 :ts:op:`stopObservation` when the view closes. 94 95 .. ts:def:: WalletRefreshInfo 96 97 interface WalletRefreshInfo { 98 risks: CashExpirationRisk[]; 99 recoveries: CashRenewalNotice[]; 100 annualCostBound: AnnualRefreshCostBound; 101 } 102 103 .. ts:def:: CashExpirationRisk 104 105 interface CashExpirationRisk { 106 exchangeBaseUrl: string; 107 exchangeMasterPub: string; 108 amount: AmountString; 109 earliestDepositExpiration: TalerProtocolTimestamp; 110 reason: 111 | "pending" 112 | "connectivity" 113 | "exchange-error" 114 | "no-replacement" 115 | "checking" 116 | "invalid-lifetime"; 117 } 118 119 .. ts:def:: CashRenewalNotice 120 121 interface CashRenewalNotice { 122 warningId: string; 123 exchangeBaseUrl: string; 124 exchangeMasterPub: string; 125 amount: AmountString; 126 oldDepositExpiration: TalerProtocolTimestamp; 127 newDepositExpiration: TalerProtocolTimestamp; 128 // Earliest emergency threshold of the renewed coins. 129 nextRelevantDate: TalerProtocolTimestamp; 130 } 131 132 .. ts:def:: AnnualRefreshCostBound 133 134 // Conditional on stable, continuously available compatible 135 // offerings and timely reveal. 136 type AnnualRefreshCostBound = { 137 horizonDays: 365; 138 projection: "stable-current-offerings"; 139 } & ( 140 | { 141 status: "available"; 142 amount: AmountString; 143 } 144 | { 145 status: "unavailable"; 146 reasons: string[]; 147 } 148 ); 149 150 .. ts:def:: ScopeInfo 151 152 // Scope of a balance; identifies the trust domain 153 // the funds belong to. 154 type ScopeInfo = 155 | ScopeInfoGlobal 156 | ScopeInfoExchange 157 | ScopeInfoAuditor 158 | ScopeInfoExchangeLegacyKeys; 159 160 .. ts:def:: ScopeInfoGlobal 161 162 // Funds held with an exchange that is globally 163 // trusted for the currency. 164 type ScopeInfoGlobal = { 165 type: "global"; 166 currency: string; 167 }; 168 169 .. ts:def:: ScopeInfoExchange 170 171 // Funds held at one particular exchange. 172 type ScopeInfoExchange = { 173 type: "exchange"; 174 currency: string; 175 url: string; 176 }; 177 178 .. ts:def:: ScopeInfoAuditor 179 180 // Funds whose denominations are audited by a globally 181 // trusted auditor. 182 type ScopeInfoAuditor = { 183 type: "auditor"; 184 currency: string; 185 url: string; 186 }; 187 188 .. ts:def:: ScopeInfoExchangeLegacyKeys 189 190 // Funds issued under a master public key that the exchange has 191 // since replaced; never pooled with funds under the current key. 192 type ScopeInfoExchangeLegacyKeys = { 193 type: "exchange-legacy-keys"; 194 currency: string; 195 url: string; 196 // The superseded key the funds were issued under. 197 masterPub: string; 198 }; 199 200 .. ts:def:: BalanceFlag 201 202 // Flag marking a pending KYC, AML or confirmation step for 203 // the incoming or outgoing funds of a balance. 204 type BalanceFlag = 205 | "incoming-kyc" 206 | "incoming-aml" 207 | "incoming-confirmation" 208 | "outgoing-kyc"; 209 210 .. ts:def:: DonauSummaryItem 211 212 interface DonauSummaryItem { 213 // Base URL of the donau service. 214 donauBaseUrl: string; 215 216 // Legal domain of the donau service (if available). 217 legalDomain?: string; 218 219 // Year of the donation(s). 220 year: number; 221 222 // Sum of donation receipts received from merchants 223 // in the applicable year. 224 amountReceiptsAvailable: AmountString; 225 226 // Sum of donation receipts already submitted to the 227 // donau in the applicable year. 228 amountReceiptsSubmitted: AmountString; 229 230 // Amount of the latest available statement. Missing 231 // if no statement was requested yet. 232 amountStatement?: AmountString; 233 }