docs: mi/654/amounts-assets

docs/astro.config.mjs

@@ -102,6 +102,10 @@ export default defineConfig({
                   label: 'Authorization',
                   link: '/concepts/auth/'
                 },
+                {
+                  label: 'Amounts',
+                  link: '/concepts/amounts/'
+                },
                 {
                   label: 'Payment methods',
                   link: '/concepts/payments/'

docs/src/content/docs/concepts/amounts.mdx

@@ -0,0 +1,198 @@
+---
+title: Amounts
+parent: Concepts
+---
+
+import { LinkOut, Tooltip } from '@interledger/docs-design-system'
+
+:::tip[Summary]
+Amounts in Open Payments define monetary values using asset codes, asset scales, and specific amount types. They provide a standardized way to represent money across different currencies and payment scenarios.
+:::
+
+Amounts represent monetary values and are fundamental to all payment operations. Every amount consists of three key components: a numerical value, an asset code, and an asset scale. Understanding these components is crucial for building Open Payments applications.
+
+Amounts are central to every Open Payments operation. Whether you're creating an incoming payment, requesting a quote, or tracking payment progress, all amounts follow the same three-part structure: a value, asset code, and asset scale.
+
+Every amount in Open Payments consists of three components:
+
+```json
+{
+  "value": "1000",
+  "assetCode": "USD",
+  "assetScale": 2
+}
+```
+
+This consistent structure enables multi-currency payments, precise calculations, and seamless integration between different <Tooltip content="Account servicing entity">ASEs</Tooltip>.
+
+## Asset codes
+
+Asset codes identify the type of currency or asset being used in a payment and should follow the <LinkOut href='https://en.wikipedia.org/wiki/ISO_4217'>ISO 4217</LinkOut> standard for currency representation.
+
+### Common currency examples
+
+<table style='width: auto; margin: 1;'>
+  <thead>
+    <tr>
+      <th>Asset Code</th>
+      <th>Currency</th>
+      <th>Symbol</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <code>USD</code>
+      </td>
+      <td>US Dollar</td>
+      <td>$</td>
+    </tr>
+    <tr>
+      <td>
+        <code>EUR</code>
+      </td>
+      <td>Euro</td>
+      <td>€</td>
+    </tr>
+    <tr>
+      <td>
+        <code>GBP</code>
+      </td>
+      <td>British Pound</td>
+      <td>£</td>
+    </tr>
+    <tr>
+      <td>
+        <code>JPY</code>
+      </td>
+      <td>Japanese Yen</td>
+      <td>¥</td>
+    </tr>
+    <tr>
+      <td>
+        <code>MXN</code>
+      </td>
+      <td>Mexican Peso</td>
+      <td>$</td>
+    </tr>
+    <tr>
+      <td>
+        <code>ZAR</code>
+      </td>
+      <td>South African Rand</td>
+      <td>R</td>
+    </tr>
+    <tr>
+      <td>
+        <code>JOD</code>
+      </td>
+      <td>Jordanian Dinar</td>
+      <td>د.ا</td>
+    </tr>
+  </tbody>
+</table>
+
+When building payment applications, you'll specify the asset code to indicate which currency you're working with:
+
+```json
+{
+  "assetCode": "USD",
+  "assetScale": 2,
+  "value": "1000"
+}
+```
+
+## Asset scales
+
+An asset scale defines the decimal precision for monetary amounts by specifying the power of 10 to divide the integer value by to get the display amount.
+
+### Integer representation
+
+Open Payments uses unsigned 64-bit integers for monetary amounts instead of floating-point numbers to maximize precision and avoid rounding errors in financial calculations. The smallest useful unit of each currency maps to 1, with all amounts expressed as multiples of that unit.
+
+### How scales work
+
+Asset scales are integers between 0 and 255 that represent the exponent in the conversion formula:
+
+**Monetary Value = Integer Amount ÷ 10^(Asset Scale)**
+
+For USD with scale 2: $1.00 = 100 cents, so the scale is 2 (10² = 100).
+
+### Examples by currency
+
+<table style='width: auto; margin: 1;'>
+  <thead>
+    <tr>
+      <th>Currency</th>
+      <th>Asset Code</th>
+      <th>Asset Scale</th>
+      <th>Integer Amount</th>
+      <th>Actual Value</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>US Dollar</td>
+      <td>
+        <code>USD</code>
+      </td>
+      <td>2</td>
+      <td>100</td>
+      <td>$1.00</td>
+    </tr>
+    <tr>
+      <td>Euro</td>
+      <td>
+        <code>EUR</code>
+      </td>
+      <td>2</td>
+      <td>2550</td>
+      <td>€25.50</td>
+    </tr>
+    <tr>
+      <td>British Pound</td>
+      <td>
+        <code>GBP</code>
+      </td>
+      <td>2</td>
+      <td>3250</td>
+      <td>£32.50</td>
+    </tr>
+    <tr>
+      <td>Japanese Yen</td>
+      <td>
+        <code>JPY</code>
+      </td>
+      <td>0</td>
+      <td>1000</td>
+      <td>¥1000</td>
+    </tr>
+    <tr>
+      <td>Mexican Peso</td>
+      <td>
+        <code>MXN</code>
+      </td>
+      <td>2</td>
+      <td>18500</td>
+      <td>$185.00</td>
+    </tr>
+    <tr>
+      <td>Jordanian Dinar</td>
+      <td>
+        <code>JOD</code>
+      </td>
+      <td>3</td>
+      <td>1000</td>
+      <td>د.ا1.000</td>
+    </tr>
+    <tr>
+      <td>South African Rand</td>
+      <td>
+        <code>ZAR</code>
+      </td>
+      <td>2</td>
+      <td>1500</td>
+      <td>R15.00</td>
+    </tr>
+  </tbody>
+</table>