Add proposal for wallet balances API

1 files changed, 40 insertions, 1 deletions

diff --git a/taler-wallet.rst b/taler-wallet.rst
index e7351fd8..1c27d827 100644
--- a/taler-wallet.rst
+++ b/taler-wallet.rst
@@ -81,12 +81,51 @@ APIs and Data Formats
 
   These APIs are still a work in progress and *not* final.
 
+Balances
+--------
+
+Balances are the amounts of digital cash held by the wallet.
+
+:name: ``"getBalances"``
+:description: Get a list of balances per currency.
+:response:
+  .. ts:def:: BalancesResponse
+
+    interface BalancesResponse {
+      // a list of balances sorted by currency.
+      // (currencies with shorter names first, then lexically ascending).
+      balances: Balance[];
+    }
+
+  .. ts:def:: Balance
+
+    interface Balance {
+      currency?: string;
+
+      // the total Amount that is currently available to be spent
+      available: Amount;
+
+      // the total incoming amount that will be added to the available balance
+      // when all pending transactions succeed
+      pendingIncoming: Amount;
+
+      // the total outgoing amount that will be subtracted from the available balance
+      // when all pending transactions succeed
+      pendingOutgoing: Amount;
+
+      // true if the balance has pending transactions
+      hasPendingTransactions: boolean;
+
+      // true if the balance requires user-interaction, e.g. accepting a tip
+      requiresUserInput: boolean;
+    }
+
 Transactions
 ------------
 
 Transactions are all operations or events that are affecting the balance.
 
-:name: ``"transactions"``
+:name: ``"getTransactions"``
 :description: Get a list of past and pending transactions.
 :request:
   .. ts:def:: TransactionsRequest