From 5b41a37da6a413a64909b288732fac64a0c178ab Mon Sep 17 00:00:00 2001
From: Vladyslav Burzakovskyy <vladislav.burzakovskij@satoshilabs.com>
Date: Tue, 21 Jan 2020 19:23:47 +0100
Subject: [PATCH] fiatRates, balanceHistory: update docs

---
 docs/api.md | 52 +++++++++++++++++++++++++++++-----------------------
 1 file changed, 29 insertions(+), 23 deletions(-)

diff --git a/docs/api.md b/docs/api.md
index f7396f8b..7bb20708 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -580,14 +580,14 @@ or in case of error
 
 #### Tickers list
 
-Returns a list of available currency rate tickers for the specified timestamp.
+Returns a list of available currency rate tickers for the specified date, along with an actual data timestamp.
 
 ```
 GET /api/v2/tickers-list/?timestamp=<timestamp>
 ```
 
 The query parameters:
-- *timestamp*: specifies a UNIX timestamp to return available tickers for.
+- *timestamp*: specifies a Unix timestamp to return available tickers for.
 
 Example response:
 
@@ -603,7 +603,7 @@ Example response:
 
 #### Tickers
 
-Returns currency rate for the specified currency and date. If the currency is not available for that specific timestamp, the closest rate will be returned.
+Returns currency rate for the specified currency and date. If the currency is not available for that specific timestamp, the next closest rate will be returned.
 All responses contain an actual rate timestamp.
 
 ```
@@ -612,7 +612,7 @@ GET /api/v2/tickers/[?currency=<currency>&timestamp=<timestamp>]
 
 The optional query parameters:
 - *currency*: specifies a currency of returned rate ("usd", "eur", "eth"...). If not specified, all available currencies will be returned.
-- *timestamp*: a UNIX timestamp that specifies a date to return currency rates for. If not specified, the last available rate will be returned.
+- *timestamp*: a Unix timestamp that specifies a date to return currency rates for. If not specified, the last available rate will be returned.
 
 Example response (no parameters):
 
@@ -652,11 +652,11 @@ GET /api/v2/balancehistory/<XPUB | address>?from=<dateFrom>&to=<dateTo>[&fiatcur
 ```
 
 Query parameters:
-- *from*: specifies a start date, format is YYYY-MM-DD.
-- *to*: specifies an end date, same format. 
+- *from*: specifies a start date as a Unix timestamp
+- *to*: specifies an end date as a Unix timestamp
 
 The optional query parameters:
-- *fiatcurrency*: if specified, the response will contain calculated fiat amounts at the time of transaction.
+- *fiatcurrency*: if specified, the response will contain fiat rate at the time of transaction.
 - *groupBy*: an interval in seconds, to group results by. Default is 3600 seconds.
 
 Example response (fiatcurrency=usd):
@@ -664,32 +664,38 @@ Example response (fiatcurrency=usd):
 ```javascript
 [
   {
-    "time":1397768400,
-    "txs":1,
-    "received":"6169114",
-    "sent":"0",
-    "fiatRate":478.2312
+    "time": 1578391200,
+    "txs": 5,
+    "received": "5000000",
+    "sent": "0",
+    "rates": {
+      "usd": 7855.9
+    }
   },
   {
-    "time":1397772000,
-    "txs":1,
-    "received":"0",
-    "sent":"6169114",
-    "fiatRate":479.1233
+    "time": 1578488400,
+    "txs": 1,
+    "received": "0",
+    "sent": "5000000",
+    "rates": {
+      "usd": 8283.11
+    }
   }
 ]
 ```
 
-Example response (fiatcurrency=usd&groupBy=86400):
+Example response (fiatcurrency=usd&groupBy=172800):
 
 ```javascript
 [
   {
-    "time":1397700000,
-    "txs":2,
-    "received":"6169114",
-    "sent":"6169114",
-    "fiatRate":478.2312
+    "time": 1578355200,
+    "txs": 6,
+    "received": "5000000",
+    "sent": "5000000",
+    "rates": {
+      "usd": 7734.45
+    }
   }
 ]
 ```