From 136d85ea56f4ab1d04c7c3df6b982a76d286e449 Mon Sep 17 00:00:00 2001 From: Luke Dashjr Date: Sat, 4 Mar 2017 08:04:20 +0000 Subject: [PATCH 01/18] bip-xchgrate: Draft of a new BIP for a common format for exchange rate information --- bip-xchgrate.mediawiki | 115 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 bip-xchgrate.mediawiki diff --git a/bip-xchgrate.mediawiki b/bip-xchgrate.mediawiki new file mode 100644 index 00000000..7c78de3c --- /dev/null +++ b/bip-xchgrate.mediawiki @@ -0,0 +1,115 @@ +
+  BIP: ?
+  Layer: Applications
+  Title: Currency/exchange rate information API
+  Author: Luke Dashjr 
+  Comments-Summary: No comments yet.
+  Comments-URI: ?
+  Status: Draft
+  Type: Standards Track
+  Created: 2017-03-04
+  License: BSD-2-Clause
+
+ +==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. + +To be BIP 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 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.) + +===Enumerating supported currency-pair tokens=== + +Parameters: + +* ''mode'' - Always "list" for this request. +* ''cc'' - If provided, the server MAY limit the results to only currency-pairs describing a currency with the given currency code(s). +* ''alt'' - 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 locale(s). + +There is only one result, which is a JSON Array of Strings, each representing a supported currency-pair. +These Strings are arbitrarily decided by the server. + +===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. +* ''cc'' - The currency code for the primary currency, if any. +* ''symbol'' - An Array of prefix and suffix for the primary 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 primary 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 [3, ",", 0] +* ''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). +* ''locale'' - If provided, a String with the applicable ISO 15897 locale. +* ''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. + +===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. + +===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. +* ''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). + +==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. + +==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 From 94a5b5393527a8024d4a96d3eaa0af165c7b342d Mon Sep 17 00:00:00 2001 From: Luke Dashjr Date: Sat, 4 Mar 2017 23:14:10 +0000 Subject: [PATCH 02/18] bip-xchgrate: Provide secondary currency code in response to info request --- bip-xchgrate.mediawiki | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/bip-xchgrate.mediawiki b/bip-xchgrate.mediawiki index 7c78de3c..e3179c89 100644 --- a/bip-xchgrate.mediawiki +++ b/bip-xchgrate.mediawiki @@ -57,7 +57,8 @@ Parameters: Each currency-pair will receive a separate result, a JSON Object, with the following information: * ''cp'' - The currency-pair token. -* ''cc'' - The currency code for the primary currency, if any. +* ''cc'' - The currency code for the primary currency. +* ''alt'' - The currency code for the secondary currency. * ''symbol'' - An Array of prefix and suffix for the primary 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 primary 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 [3, ",", 0] From 125e0cc931e9b8962322a28a045d5d77dcf04313 Mon Sep 17 00:00:00 2001 From: Luke Dashjr Date: Sat, 4 Mar 2017 23:15:02 +0000 Subject: [PATCH 03/18] bip-xchgrate: Define rate --- bip-xchgrate.mediawiki | 2 ++ 1 file changed, 2 insertions(+) diff --git a/bip-xchgrate.mediawiki b/bip-xchgrate.mediawiki index e3179c89..4524f156 100644 --- a/bip-xchgrate.mediawiki +++ b/bip-xchgrate.mediawiki @@ -35,6 +35,8 @@ Currency code(s) used herein are defined as such: * 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: primaryCurrencyValue / rate = secondaryCurrencyValue + ===Enumerating supported currency-pair tokens=== Parameters: From 8eaad1803f85de7ae36bcd287648092c9daf9c2f Mon Sep 17 00:00:00 2001 From: Luke Dashjr Date: Sat, 4 Mar 2017 23:23:17 +0000 Subject: [PATCH 04/18] bip-xchgrate: Allow currency-pairs to have arbitrary descriptions --- bip-xchgrate.mediawiki | 2 ++ 1 file changed, 2 insertions(+) diff --git a/bip-xchgrate.mediawiki b/bip-xchgrate.mediawiki index 4524f156..434f3abf 100644 --- a/bip-xchgrate.mediawiki +++ b/bip-xchgrate.mediawiki @@ -61,6 +61,8 @@ Each currency-pair will receive a separate result, a JSON Object, with the follo * ''cp'' - The currency-pair token. * ''cc'' - The currency code for the primary currency. * ''alt'' - The currency code for the secondary currency. +* ''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. +* ''longdesc'' - Optional description, but may be longer and formatted using HTML. * ''symbol'' - An Array of prefix and suffix for the primary 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 primary 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 [3, ",", 0] From 019d922851260704c460dbe21a312cc52e28d3c2 Mon Sep 17 00:00:00 2001 From: Luke Dashjr Date: Sat, 4 Mar 2017 23:37:59 +0000 Subject: [PATCH 05/18] bip-xchgrate: Limit currency-pair token symbols, and give a little info with enumeration --- bip-xchgrate.mediawiki | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/bip-xchgrate.mediawiki b/bip-xchgrate.mediawiki index 434f3abf..164091d2 100644 --- a/bip-xchgrate.mediawiki +++ b/bip-xchgrate.mediawiki @@ -29,6 +29,8 @@ To be BIP compatible, servers MUST support at least one currency-pair co 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. @@ -46,8 +48,12 @@ Parameters: * ''alt'' - 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 locale(s). -There is only one result, which is a JSON Array of Strings, each representing a supported currency-pair. -These Strings are arbitrarily decided by the server. +Each currency-pair will receive a separate result, a JSON Object, with the following information: + +* ''cp'' - The currency-pair token. +* ''cc'' - The currency code for the primary currency. +* ''alt'' - The currency code for the secondary currency. +* ''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. ===Currency-pair information=== @@ -61,7 +67,7 @@ Each currency-pair will receive a separate result, a JSON Object, with the follo * ''cp'' - The currency-pair token. * ''cc'' - The currency code for the primary currency. * ''alt'' - The currency code for the secondary currency. -* ''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. +* ''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 formatted using HTML. * ''symbol'' - An Array of prefix and suffix for the primary 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 primary currency's numbers. "arabic" should be used for common 0-9 digits. From 3b29e5d3fafa737eb06a49b59dc09d37c096b1d4 Mon Sep 17 00:00:00 2001 From: Luke Dashjr Date: Sat, 4 Mar 2017 23:46:46 +0000 Subject: [PATCH 06/18] bip-xchgrate: Begin Rationale section --- bip-xchgrate.mediawiki | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/bip-xchgrate.mediawiki b/bip-xchgrate.mediawiki index 164091d2..ecfa8cc4 100644 --- a/bip-xchgrate.mediawiki +++ b/bip-xchgrate.mediawiki @@ -117,6 +117,17 @@ There are many independent providers of such information, but they all use diffe 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? + +* Long descriptions support HTML, which has entities for paragraphs and line breaks that do not require literal line-feeds in the data. + ==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. From 651de8120e21ba6c644d0fea4bae1524a71015d5 Mon Sep 17 00:00:00 2001 From: Luke Dashjr Date: Sun, 5 Mar 2017 00:23:26 +0000 Subject: [PATCH 07/18] bip-xchgrate: More sensible rate definition --- bip-xchgrate.mediawiki | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bip-xchgrate.mediawiki b/bip-xchgrate.mediawiki index ecfa8cc4..bc1dfc8d 100644 --- a/bip-xchgrate.mediawiki +++ b/bip-xchgrate.mediawiki @@ -37,7 +37,7 @@ Currency code(s) used herein are defined as such: * 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: primaryCurrencyValue / rate = secondaryCurrencyValue +Rate is defined as: 1 primaryCurrency = 1 secondaryCurrency / rate ===Enumerating supported currency-pair tokens=== From 7a324fb947457164e8ec1414125aaf5ed22a0716 Mon Sep 17 00:00:00 2001 From: Luke Dashjr Date: Sun, 5 Mar 2017 02:16:22 +0000 Subject: [PATCH 08/18] bip-xchgrate: Use standard currency exchange base/quote terminology --- bip-xchgrate.mediawiki | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/bip-xchgrate.mediawiki b/bip-xchgrate.mediawiki index bc1dfc8d..0be070ee 100644 --- a/bip-xchgrate.mediawiki +++ b/bip-xchgrate.mediawiki @@ -37,22 +37,22 @@ Currency code(s) used herein are defined as such: * 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: 1 primaryCurrency = 1 secondaryCurrency / rate +Rate is defined as: 1 quoteCurrency = 1 baseCurrency * rate ===Enumerating supported currency-pair tokens=== Parameters: * ''mode'' - Always "list" for this request. -* ''cc'' - If provided, the server MAY limit the results to only currency-pairs describing a currency with the given currency code(s). -* ''alt'' - If provided, the server MAY limit the results to only currency-pairs describing currency rates compared to the given currency code(s). +* ''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 locale(s). Each currency-pair will receive a separate result, a JSON Object, with the following information: * ''cp'' - The currency-pair token. -* ''cc'' - The currency code for the primary currency. -* ''alt'' - The currency code for the secondary currency. +* ''quote'' - The currency code for the quote currency. +* ''base'' - The currency code for the base currency. * ''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. ===Currency-pair information=== @@ -65,12 +65,12 @@ Parameters: Each currency-pair will receive a separate result, a JSON Object, with the following information: * ''cp'' - The currency-pair token. -* ''cc'' - The currency code for the primary currency. -* ''alt'' - The currency code for the secondary currency. +* ''quote'' - The currency code for the quote currency. +* ''base'' - The currency code for the base currency. * ''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 formatted using HTML. -* ''symbol'' - An Array of prefix and suffix for the primary 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 primary currency's numbers. "arabic" should be used for common 0-9 digits. +* ''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 [3, ",", 0] * ''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). From 253c7f923b87ab4bd0dc4999953617929e6c96e3 Mon Sep 17 00:00:00 2001 From: Luke Dashjr Date: Sun, 5 Mar 2017 03:21:16 +0000 Subject: [PATCH 09/18] bip-xchgrate: Use plain English to define rate --- bip-xchgrate.mediawiki | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/bip-xchgrate.mediawiki b/bip-xchgrate.mediawiki index 0be070ee..96665c8b 100644 --- a/bip-xchgrate.mediawiki +++ b/bip-xchgrate.mediawiki @@ -37,7 +37,8 @@ Currency code(s) used herein are defined as such: * 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: 1 quoteCurrency = 1 baseCurrency * rate +Rate is defined as the amount of base-currency to be exchanged for one unit of the quote-currency. +In other words, 1 quoteCurrency = rate baseCurrency. ===Enumerating supported currency-pair tokens=== From f33738655061a0f4a8949ca018b53994ace1a1c1 Mon Sep 17 00:00:00 2001 From: Luke Dashjr Date: Sun, 5 Mar 2017 04:32:13 +0000 Subject: [PATCH 10/18] bip-xchgrate: Fix --- bip-xchgrate.mediawiki | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/bip-xchgrate.mediawiki b/bip-xchgrate.mediawiki index 96665c8b..86f7cfcf 100644 --- a/bip-xchgrate.mediawiki +++ b/bip-xchgrate.mediawiki @@ -37,8 +37,8 @@ Currency code(s) used herein are defined as such: * 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 base-currency to be exchanged for one unit of the quote-currency. -In other words, 1 quoteCurrency = rate baseCurrency. +Rate is defined as the amount of quote-currency to be exchanged for one unit of the base-currency. +In other words, 1 baseCurrency = rate quoteCurrency. ===Enumerating supported currency-pair tokens=== From ee90b8c525311a354257ef03cd8f5bfa7ed4e751 Mon Sep 17 00:00:00 2001 From: Luke Dashjr Date: Sun, 5 Mar 2017 05:49:02 +0000 Subject: [PATCH 11/18] bip-xchgrate: Drop HTML longdesc --- bip-xchgrate.mediawiki | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/bip-xchgrate.mediawiki b/bip-xchgrate.mediawiki index 86f7cfcf..6d79b4cf 100644 --- a/bip-xchgrate.mediawiki +++ b/bip-xchgrate.mediawiki @@ -69,7 +69,7 @@ Each currency-pair will receive a separate result, a JSON Object, with the follo * ''quote'' - The currency code for the quote currency. * ''base'' - The currency code for the base currency. * ''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 formatted using HTML. +* ''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 [3, ",", 0] @@ -127,7 +127,7 @@ Why are multiple results separated by a line-feed rather than using a JSON Array What if long descriptions require line and paragraph breaks? -* Long descriptions support HTML, which has entities for paragraphs and line breaks that do not require literal line-feeds in the data. +* Clients should word-wrap long lines, and JSON escapes newlines as "\n" which can be used doubly ("\n\n") for paragraph breaks. ==Backwards compatibility== From 00323d1a8f3b873c340b2f74300822ff8a31dbdf Mon Sep 17 00:00:00 2001 From: Luke Dashjr Date: Mon, 6 Mar 2017 02:19:03 +0000 Subject: [PATCH 12/18] bip-xchgrate: Use Unicode CLDR for locales --- bip-xchgrate.mediawiki | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/bip-xchgrate.mediawiki b/bip-xchgrate.mediawiki index 6d79b4cf..9171f24c 100644 --- a/bip-xchgrate.mediawiki +++ b/bip-xchgrate.mediawiki @@ -47,7 +47,7 @@ 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 locale(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: @@ -75,7 +75,7 @@ Each currency-pair will receive a separate result, a JSON Object, with the follo * ''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 [3, ",", 0] * ''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). -* ''locale'' - If provided, a String with the applicable ISO 15897 locale. +* ''locale'' - If provided, a String with the applicable Unicode CLDR locale. * ''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. From 12316e3dec63902529d81bb18f4e19fbee6888ce Mon Sep 17 00:00:00 2001 From: Luke Dashjr Date: Mon, 6 Mar 2017 02:21:22 +0000 Subject: [PATCH 13/18] bip-xchgrate: Include locale with enumeration --- bip-xchgrate.mediawiki | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/bip-xchgrate.mediawiki b/bip-xchgrate.mediawiki index 9171f24c..317d16fc 100644 --- a/bip-xchgrate.mediawiki +++ b/bip-xchgrate.mediawiki @@ -54,6 +54,7 @@ Each currency-pair will receive a separate result, a JSON Object, with the follo * ''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. ===Currency-pair information=== @@ -68,6 +69,7 @@ Each currency-pair will receive a separate result, a JSON Object, with the follo * ''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. @@ -75,7 +77,6 @@ Each currency-pair will receive a separate result, a JSON Object, with the follo * ''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 [3, ",", 0] * ''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). -* ''locale'' - If provided, a String with the applicable Unicode CLDR locale. * ''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. From a361076d49559ea037f685b9a15dd3538f324a60 Mon Sep 17 00:00:00 2001 From: Luke Dashjr Date: Mon, 6 Mar 2017 02:41:09 +0000 Subject: [PATCH 14/18] bip-xchgrate: Add examples --- bip-xchgrate.mediawiki | 45 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/bip-xchgrate.mediawiki b/bip-xchgrate.mediawiki index 317d16fc..68d1f071 100644 --- a/bip-xchgrate.mediawiki +++ b/bip-xchgrate.mediawiki @@ -57,6 +57,14 @@ Each currency-pair will receive a separate result, a JSON Object, with the follo * ''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"e=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: @@ -82,6 +90,13 @@ Each currency-pair will receive a separate result, a JSON Object, with the follo * ''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: @@ -97,6 +112,13 @@ Each currency-pair receives a separate result (a JSON Object) with all requested * ''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: @@ -111,6 +133,29 @@ Parameters: 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). +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. From 43aa6f81901c39db070a685eb28578651c22c7c4 Mon Sep 17 00:00:00 2001 From: Luke Dashjr Date: Mon, 6 Mar 2017 02:42:55 +0000 Subject: [PATCH 15/18] bip-xchgrate: Note authentication --- bip-xchgrate.mediawiki | 2 ++ 1 file changed, 2 insertions(+) diff --git a/bip-xchgrate.mediawiki b/bip-xchgrate.mediawiki index 68d1f071..fbf17cd9 100644 --- a/bip-xchgrate.mediawiki +++ b/bip-xchgrate.mediawiki @@ -25,6 +25,8 @@ Four requests are defined, which are all made by a GET request to a common URI w 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. + To be BIP 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?) From cea6be598d3ad90e1e439ab05f1bfd695e900431 Mon Sep 17 00:00:00 2001 From: Luke Dashjr Date: Mon, 6 Mar 2017 22:08:51 +0000 Subject: [PATCH 16/18] bip-xchgrate: history bounds and "nearest" flag --- bip-xchgrate.mediawiki | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/bip-xchgrate.mediawiki b/bip-xchgrate.mediawiki index fbf17cd9..d0cf7eea 100644 --- a/bip-xchgrate.mediawiki +++ b/bip-xchgrate.mediawiki @@ -130,11 +130,15 @@ Parameters: * ''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 From d5600c5b748289fab53f87dff089a407602e052b Mon Sep 17 00:00:00 2001 From: Luke Dashjr Date: Mon, 6 Mar 2017 22:10:04 +0000 Subject: [PATCH 17/18] bip-xchgrate: Recommend HTTPS --- bip-xchgrate.mediawiki | 1 + 1 file changed, 1 insertion(+) diff --git a/bip-xchgrate.mediawiki b/bip-xchgrate.mediawiki index d0cf7eea..00a96ed9 100644 --- a/bip-xchgrate.mediawiki +++ b/bip-xchgrate.mediawiki @@ -26,6 +26,7 @@ All matching parameters may be specified with multiple comma-separated values, w 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 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. From 29584bb19444948c019ecee855e575b0e76d9cbc Mon Sep 17 00:00:00 2001 From: Luke Dashjr Date: Tue, 14 Mar 2017 23:15:17 +0000 Subject: [PATCH 18/18] Assign BIP 171: Currency/exchange rate information API --- README.mediawiki | 7 +++++++ bip-xchgrate.mediawiki => bip-0171.mediawiki | 6 +++--- 2 files changed, 10 insertions(+), 3 deletions(-) rename bip-xchgrate.mediawiki => bip-0171.mediawiki (98%) diff --git a/README.mediawiki b/README.mediawiki index 1398ca38..f5f0db33 100644 --- a/README.mediawiki +++ b/README.mediawiki @@ -658,6 +658,13 @@ Those proposing changes should consider that ultimately consent may rest with th | Matt Corallo | Standard | Draft +|- +| [[bip-0171.mediawiki|171]] +| Applications +| Currency/exchange rate information API +| Luke Dashjr +| Standard +| Draft |} diff --git a/bip-xchgrate.mediawiki b/bip-0171.mediawiki similarity index 98% rename from bip-xchgrate.mediawiki rename to bip-0171.mediawiki index 00a96ed9..237d233d 100644 --- a/bip-xchgrate.mediawiki +++ b/bip-0171.mediawiki @@ -1,10 +1,10 @@ 
-  BIP: ?
+  BIP: 171
   Layer: Applications
   Title: Currency/exchange rate information API
   Author: Luke Dashjr 
   Comments-Summary: No comments yet.
-  Comments-URI: ?
+  Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0171
   Status: Draft
   Type: Standards Track
   Created: 2017-03-04
@@ -28,7 +28,7 @@ Each result is always in JSON format, with a line-feed (never a carriage-return)
 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  compatible, servers MUST support at least one currency-pair compared to XBT.
+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?)