propose balance API for #6086

1 files changed, 52 insertions, 4 deletions

diff --git a/core/api-wire.rst b/core/api-wire.rst
index 3f2b27d0..1078a2d4 100644
--- a/core/api-wire.rst
+++ b/core/api-wire.rst
@@ -154,7 +154,32 @@ Querying the transaction history
 
   **Response**
 
-  :status 200 OK: JSON object whose field ``incoming_transactions`` is an array of type `IncomingBankTransaction`.
+  :status 200 OK: JSON object of type `IncomingHistory`.
+
+  .. ts:def:: IncomingHistory
+
+    interface IncomingHistory {
+
+      // The incoming transactions
+      incoming_transactions : IncomingBankTransaction;
+
+      // Sum of all incoming transactions (ever) after the most
+      // recent transaction reported in the history.
+      total_incoming_end: Amount;
+
+      // Sum of all incoming transactions before the oldest
+      // transaction reported in the history.
+      total_incoming_start: Amount;
+
+      // Total amount that has been outgoing from this account
+      // from the beginning of time until now. Note that this
+      // number is always the latest value and thus independent
+      // of the time region covered by the history.  If the
+      // history includes the latest incoming transactions, this
+      // value can be used to calculate the balance after that
+      // latest transaction.
+      current_outgoing: Amount;
+    }
 
   .. ts:def:: IncomingBankTransaction
 
@@ -224,9 +249,32 @@ Querying the transaction history
 
   **Response**
 
-  :status 200 OK:
-    JSON object whose field ``outgoing_transactions`` is
-    an array of type `OutgoingBankTransaction`.
+  :status 200 OK: JSON object of type `OutgoingHistory`.
+
+  .. ts:def:: OutgoingHistory
+
+    interface OutgoingHistory {
+
+      // The outgoing transactions
+      outgoing_transactions : OutgoingBankTransaction;
+
+      // Sum of all outgoing transactions (ever) after the most
+      // recent transaction reported in the history.
+      total_outgoing_end: Amount;
+
+      // Sum of all outgoing transactions before the oldest
+      // transaction reported in the history.
+      total_outgoing_start: Amount;
+
+      // Total amount that has been incoming into this account
+      // from the beginning of time until now. Note that this
+      // number is always the latest value and thus independent
+      // of the time region covered by the history.  If the
+      // history includes the latest outgoing transactions, this
+      // value can be used to calculate the balance after that
+      // latest transaction.
+      current_incoming: Amount;
+    }
 
   .. ts:def:: OutgoingBankTransaction