Assign BIP 171: Currency/exchange rate information API

1 files changed, 191 insertions, 0 deletions

diff --git a/bip-0171.mediawiki b/bip-0171.mediawiki
new file mode 100644
index 0000000..237d233
--- /dev/null
+++ b/bip-0171.mediawiki
@@ -0,0 +1,191 @@
+<pre>
+  BIP: 171
+  Layer: Applications
+  Title: Currency/exchange rate information API
+  Author: Luke Dashjr <luke+bip@dashjr.org>
+  Comments-Summary: No comments yet.
+  Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0171
+  Status: Draft
+  Type: Standards Track
+  Created: 2017-03-04
+  License: BSD-2-Clause
+</pre>
+
+==Abstract==
+
+A common interface for requesting currency exchange rate information from a server.
+
+==Copyright==
+
+This BIP is licensed under the BSD 2-clause license.
+
+==Specification==
+
+Four requests are defined, which are all made by a GET request to a common URI with parameters encoded in application/x-www-form-urlencoded format.
+All matching parameters may be specified with multiple comma-separated values, which are to be interpreted as "any of these".
+Each result is always in JSON format, with a line-feed (never a carriage-return) separating multiple results.
+
+Authentication for subscription-based services MAY be supported using standard HTTP authentication.
+It is recommended to use TLS (HTTPS), so that MITM attackers cannot deceive the client.
+
+To be BIP 171 compatible, servers MUST support at least one currency-pair compared to XBT.
+All inquiries for bitcoin amounts MUST be specified in XBT, even if the presentation to the end user is in another unit.
+(FIXME: or should this be satoshis?)
+
+Currency-pair tokens are arbitrary Strings no longer than 255 characters, which may include any ASCII [https://tools.ietf.org/html/rfc3986#section-2.3 RFC 3986 unreserved characters] (ie, alphanumerics and the hyphen, underscore, period, and tilde symbols).
+
+Currency code(s) used herein are defined as such:
+
+* All ISO 4217 codes are valid currency codes.
+* XBT is defined as 100000000 satoshis (commonly known as 1 BTC).
+* Strings longer than 3 characters may be used for currencies without an applicable code. (If a shorter code is desired despite this, it may be padded with space(s) to the left until it is 4 characters. Software MAY strip these spaces.)
+
+Rate is defined as the amount of quote-currency to be exchanged for one unit of the base-currency.
+In other words, <code>1 baseCurrency = rate quoteCurrency</code>.
+
+===Enumerating supported currency-pair tokens===
+
+Parameters:
+
+* ''mode'' - Always "list" for this request.
+* ''quote'' - If provided, the server MAY limit the results to only currency-pairs describing a currency with the given currency code(s).
+* ''base'' - If provided, the server MAY limit the results to only currency-pairs describing currency rates compared to the given currency code(s).
+* ''locale'' - If provided, the server MAY limit the results to only currency-pairs supporting the given Unicode CLDR locale(s).
+
+Each currency-pair will receive a separate result, a JSON Object, with the following information:
+
+* ''cp'' - The currency-pair token.
+* ''quote'' - The currency code for the quote currency.
+* ''base'' - The currency code for the base currency.
+* ''locale'' - If provided, a String with the applicable Unicode CLDR locale.
+* ''desc'' - Optional description. For example, it could be "Based on Florida BTM prices." or any other short String that provides information useful to the user. SHOULD be shorter than 45 characters.
+
+Example:
+
+    Request: http://api.example.tld/?mode=list&quote=USD&base=XBT&locale=en_US,en_GB
+    Result:
+      {"cp":"XBTUSD-ver4", "quote":"USD", "base": "XBT", "locale": "en_US", "desc": "Smoothed averages"}
+      {"cp":"2", "quote":"USD", "base": "XBT", "locale": "en_US", "desc": "Updated per-trade"}
+      {"cp":"XBTUSD-european", "quote":"USD", "base": "XBT", "locale": "en_GB"}
+
+===Currency-pair information===
+
+Parameters:
+
+* ''mode'' - Always "info" for this request.
+* ''cp'' - Currency pair(s) for which information is requested.
+
+Each currency-pair will receive a separate result, a JSON Object, with the following information:
+
+* ''cp'' - The currency-pair token.
+* ''quote'' - The currency code for the quote currency.
+* ''base'' - The currency code for the base currency.
+* ''locale'' - If provided, a String with the applicable Unicode CLDR locale.
+* ''desc'' - Optional description. For example, it could be "Based on Florida BTM prices." or any other short String that provides information useful to the user. SHOULD be shorter than 45 characters.
+* ''longdesc'' - Optional description, but may be longer and include newlines.
+* ''symbol'' - An Array of prefix and suffix for the quote currency. Each may be either a fixed String, an Array of two Strings (negative and positive), or null. Any positive or negative symbols must be included in this prefix/suffix; it MUST NOT be implied otherwise.
+* ''digits'' - The type of digits to use for the quote currency's numbers. "arabic" should be used for common 0-9 digits.
+* ''grouping'' - An Array alternating between Numbers representing a series of digits, and Strings used as delimiters. If terminated by a zero, the final grouping is to be repeated continually. For example, the common US locale thousands grouping would be <code>[3, ",", 0]</code>
+* ''fraction_sep'' - A String to be placed between whole numbers and a fractional amount.
+* ''fraction_digits'' - Array of absolute minimum (even for whole numbers) number of fractional digits, minimum fractional digits when a fraction exists, and maximum number of fractional digits when absolute precision is not demanded (below which is to be rounded in an implementation-dependent manner).
+* ''minpoll'' - A Number of seconds indicating a minimum time between polls to the server. Clients should be prudent about not polling too often, even if this number is low.
+* ''longpoll'' - If provided and true, indicates longpolling is supported by the server.
+* ''history'' - If provided, indicates the server has historical records going back no earlier than the POSIX timestamp provided as a value.
+* ''archive'' - If provided, indicates the server no longer has current rates, and has no historical rates more recent than the POSIX timestamp provided as a value.
+
+Example:
+
+    Request: http://api.example.tld/?mode=info&cp=XBTUSD-ver4,2
+    Result:
+      {"cp":"XBTUSD-ver4", "quote":"USD", "base": "XBT", "locale": "en_US", "desc": "Smoothed averages", "longdesc": "USD price quotes as compared to Bitcoin value\n\nRecommended for casual usage", "symbol": [["-$", "$"], null], "digits": "arabic", "grouping": [3, ",", 0], "fraction_sep": ".", "fraction_digits": [0, 2, 2], "minpoll": 300, "longpoll": true, "history": 1457231416}
+      {"cp":"2", "quote":"USD", "base": "XBT", "locale": "en_US", "desc": "Updated per-trade", "longdesc": "Maximum precision USD price quotes as compared to Bitcoin value", "symbol": [["-$", "$"], null], "digits": "arabic", "grouping": [3, ",", 0], "fraction_sep": ".", "fraction_digits": [0, 2, 2], "minpoll": 3600, "longpoll": false, "history": 1467458333.1225}
+
+===Current exchange rate===
+
+Parameters:
+
+* ''mode'' - Always "rate" for this request.
+* ''cp'' - Currency pair(s) for which rate is requested.
+* ''type'' - Type of exchange rate data being requested. May be "high", "low", "average", "typical", or any other arbitrary name. If omitted, the server may provide any rates it deems appropriate.
+* ''minrate'', ''maxrate'' - If specified, indicates this request is a longpoll. The server should not send a response until the rate(s) fall below or above (respectively) the provided value.
+
+Each currency-pair receives a separate result (a JSON Object) with all requested rate types:
+
+* ''cp'' - The currency-pair token.
+* ''time'' - The time (as a POSIX timestamp) the rate information is applicable to (should be approximately the request time).
+* ''rates'' - A JSON Object with each rate type provided as a key, and a Number as the value specifying the rate.
+
+Example:
+
+    Request: http://api.example.tld/?mode=rate&cp=XBTUSD-ver4,2&type=typical,high
+    Result:
+      {"cp":"XBTUSD-ver4", "time": 1488767410.5463133, "rates": {"typical": 1349.332215, "high": 1351.2}}
+      {"cp":"2", "time": 1488767410, "rates": {"typical": 1350.111332}}
+
+===Historical exchange rates===
+
+Parameters:
+
+* ''mode'' - Always "history" for this request.
+* ''cp'' - Currency pair(s) for which rate is requested.
+* ''type'' - Type of exchange rate data being requested. May be "high", "low", "average", "typical", or any other arbitrary name. If omitted, the server may provide any rates it deems appropriate.
+* ''from'' - POSIX timestamp the results should begin with.
+* ''to'' - POSIX timestamp the results should end with. If omitted, the present time shall be used.
+* ''nearest'' - If provided and true, indicates that only the nearest timestamp to "from" must be returned, and a range is not desired. ("to" should be omitted in this case.)
+* ''ratedelta'', ''timedelta'' - If specified, the server may omit data where the rate or time has not changed since the last provided rate and time. If both are provided, either a significant rate change OR time change should trigger a new record in the results.
+
+A result is provided for each currency-pair and timestamp record, in the same format as the current exchange rate request.
+Records MUST be provided in chronological order, but only within the scope of the applicable currency-pair (ie, it is okay to send the full history for one currency-pair, and then the full history for the next; or to intermix them out of any given order).
+
+If there is no exact record for the times specified by "from" and/or "to", a single record before "from" and/or after "to" should also be included.
+This is not necessary when only the nearest record is requested, or when "to" is omitted (ie, ending at the most recent record).
+
+Example:
+
+    Request: http://api.example.tld/?mode=history&cp=XBTUSD-ver4,2&type=typical&ratedelta=0.1&timedelta=10&from=1488759998&to=1488760090
+    Result:
+      {"cp":"XBTUSD-ver4", "time": 1488760000, "rates": {"typical": 1300}}
+      {"cp":"XBTUSD-ver4", "time": 1488760010, "rates": {"typical": 1301.1}}
+      {"cp":"XBTUSD-ver4", "time": 1488760020, "rates": {"typical": 1320}}
+      {"cp":"XBTUSD-ver4", "time": 1488760030, "rates": {"typical": 1305}}
+      {"cp":"2", "time": 1488760000.1, "rates": {"typical": 1300}}
+      {"cp":"2", "time": 1488760010.2, "rates": {"typical": 1301.1}}
+      {"cp":"2", "time": 1488760020.2, "rates": {"typical": 1320.111332}}
+      {"cp":"2", "time": 1488760031, "rates": {"typical": 1305.222311}}
+      {"cp":"XBTUSD-ver4", "time": 1488760040, "rates": {"typical": 1303.33}}
+      {"cp":"2", "time": 1488760042, "rates": {"typical": 1303.33}}
+      {"cp":"XBTUSD-ver4", "time": 1488760050, "rates": {"typical": 1305}}
+      {"cp":"2", "time": 1488760052, "rates": {"typical": 1307}}
+      {"cp":"XBTUSD-ver4", "time": 1488760060, "rates": {"typical": 1309}}
+      {"cp":"XBTUSD-ver4", "time": 1488760072, "rates": {"typical": 1308}}
+      {"cp":"2", "time": 1488760062, "rates": {"typical": 1309.55555555}}
+      {"cp":"2", "time": 1488760072, "rates": {"typical": 1308}}
+      {"cp":"XBTUSD-ver4", "time": 1488760082, "rates": {"typical": 1309}}
+      {"cp":"2", "time": 1488760082, "rates": {"typical": 1309.1}}
+
+==Motivation==
+
+End users often desire to see fiat currency information in their Bitcoin wallet software.
+Due to the nature of Bitcoin, there is inherently no authoritative source for exchange rates.
+There are many independent providers of such information, but they all use different formats for providing it, so wallet software is currently forced to implement dedicated code for each provider.
+
+By providing a standard interface for retrieving this information, wallets (and other software) and service providers can implement it once, and become immediately interoperable with all other compatible implementations.
+
+==Rationale==
+
+Why are multiple results separated by a line-feed rather than using a JSON Array?
+
+* Clients ought to cache historical data, and using a line-feed format allows them to simply append to a cache file.
+* Parsing JSON typically requires the entire data parsed together as a single memory object. Using simple lines to separate results, however, allows parsing a single result at a time.
+
+What if long descriptions require line and paragraph breaks?
+
+* Clients should word-wrap long lines, and JSON escapes newlines as "\n" which can be used doubly ("\n\n") for paragraph breaks.
+
+==Backwards compatibility==
+
+While this new standard is adopted, software and providers can continue to use and provide their current formats until they are no longer needed.
+
+==Reference implementation==
+
+TODO