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).
* 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.)
* ''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.
* ''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.
* ''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).
* ''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.
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.
