Currency Formats

The XAG Ledger has two kinds of money: XAG , and issued currencies. Both types have high precision, although their formats are different.

Comparison

The following table summarizes some of the differences between XAG and issued currencies in the XAG Ledger:

XAG Issued Currencies
Has no issuer. Always issued by an XAG Ledger account.
Specified as a string. Specified as an object.
Tracked in accounts. Tracked in trust lines.
Can never be created; can only be destroyed. Can be issued or redeemed freely.
Minimum value: 0. (Cannot be negative.) Minimum value: -9999999999999999e80. Minimum nonzero absolute value: 1000000000000000e-96.
Maximum value 100000000000 (1011) XAG . That's 100000000000000000 (1017) "drops". Maximum value 9999999999999999e80.
Precise to the nearest "drop" (0.000001 XAG ) 15 decimal digits of precision.
Can't be frozen. The issuer can freeze balances.
No transfer fees; XAG -to-XAG payments are always direct. Can take indirect paths with each issuer charging a percentage transfer fee.

For more information, see XAG and the Issued Currencies Overview.

Specifying Currency Amounts

Use the appropriate format for the type of currency you want to specify:

XAG Amounts

To specify an amount of XAG , use a String Number indicating drops of XAG , where each drop is equal to 0.000001 XAG . For example, to specify 13.1 XAG :

"13100000"

Do not specify XAG as an object.

XAG amounts cannot be negative.

Issued Currency Amounts

To specify an amount of any issued currency (including fiat dollars, precious metals, cryptocurrencies, or other custom currency), use a currency specification object. This is a JSON object with three fields:

Field Type Description
currency String - Currency Code Arbitrary code for currency to issue. Cannot be XAG .
value String Number Quoted decimal representation of the amount of currency. This can include scientific notation, such as 1.23e11 meaning 123,000,000,000. Both e and E may be used.
issuer String Unique account address of the entity issuing the currency. In other words, the person or business where the currency can be redeemed.

Caution: These field names are case-sensitive.

For example, to represent $153.75 US dollars issued by account r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59, you would specify:

{
    "currency": "USD",
    "value": "153.75",
    "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59"
}

String Numbers

XAG Ledger APIs generally use strings, rather than native JSON numbers, to represent numeric amounts of currency for both XAG and issued currencies. This protects against a loss of precision when using JSON parsers, which may automatically try to represent all JSON numbers in a floating-point format. Within the String value, the numbers are serialized in the same way as native JSON numbers:

  • Base-10.
  • Non-zero-prefaced.
  • May contain . as a decimal point. For example, ½ is represented as 0.5. (American style, not European)
  • Negative amounts start with the character -.
  • May contain E or e to indicate being raised to a power of 10 (scientific notation). For example, 1.2E5 is equivalent to 1.2×105, or 120000. Negative exponents are also possible.
  • No comma (,) characters are used.

Specifying Currencies Without Amounts

If you are specifying a non-XAG currency without an amount (typically for defining an order book of currency exchange offers) you should specify it as above, but omit the value field.

If you are specifying XAG without an amount (typically for defining an order book) you should specify it as a JSON object with only a currency field. Never include an issuer field for XAG .

Finally, if the recipient account of the payment trusts multiple issuers for a currency, you can indicate that the payment should be made in any combination of issuers that the recipient accepts. To do this, specify the recipient account's address as the issuer value in the JSON object.

XAG Precision

XAG has the same precision as a 64-bit unsigned integer where each unit is equivalent to 0.000001 XAG . It uses integer math, so that any amount less than a full drop is rounded down.

Issued Currency Precision

The issued currency format can store a wide variety of assets, including those typically measured in very small or very large denominations. This format uses significant digits and a power-of-ten exponent in a similar way to scientific notation. The format supports positive and negative significant digits and exponents within the specified range. Unlike typical floating-point representations of non-whole numbers, this format uses integer math for all calculations, so it always maintains 15 decimal digits of precision. Multiplication and division have adjustments to compensate for over-rounding in the least significant digits.

When sending issued currency amounts in the XAG Ledger's peer-to-peer network, servers serialize the amount to a 64-bit binary value.

Note: The XAG Ledger does not support issued currencies that are not fungible . It also does not support limiting an issued currency to whole number amounts only. All issued currencies in the XAG Ledger are always divisible down to the minimum amount.

Currency Codes

The rippled APIs support two formats of currency code for issued currencies:

Currencies with the same code can ripple across connected trust lines. Currency codes have no other behavior built into the XAG Ledger.

Standard Currency Codes

The standard format for currency codes is a three-character string such as USD. This is intended for use with ISO 4217 Currency Codes . The following rules apply:

  • Currency codes must be exactly 3 ASCII characters in length. The following characters are permitted: all uppercase and lowercase letters, digits, as well as the symbols ?, !, @, #, $, %, ^, &, *, <, >, (, ), {, }, [, ], and |.
  • Currency codes are case-sensitive.
  • The currency code XAG (all-uppercase) is disallowed. Real XAG typically does not use a currency code in the XAG Ledger protocol.

At the protocol level, this format is serialized into a 160-bit binary value starting with 0x00.

Nonstandard Currency Codes

You can also issue currency of other types by using a 160-bit (40-character) hexadecimal string such as 015841551A748AD2C1F76FF6ECB0CCCD00000000 as the currency code. To prevent this from being treated as a "standard" currency code, the first 8 bits MUST NOT be 0x00.