tempoxyz · juandolealt · Jul 9, 2026
diff --git a/src/pages/docs/tools.mdx b/src/pages/docs/tools.mdx
@@ -68,3 +68,28 @@ If you are integrating a product, start with the TypeScript SDKs and hosted serv
     icon="lucide:bot"
   />
 </Cards>
+
+## Web tool methodologies
+
+The calculators at [tempo.xyz/tools](https://tempo.xyz/tools/) estimate fees, corridor costs, and settlement times. These pages document the formulas, data sources, and assumptions behind each one.
+
+<Cards>
+  <Card
+    title="Fee Estimator"
+    description="See how the fee estimator computes USD costs from gas figures and the base fee, plus the /api/fee-estimate JSON contract."
+    to="/docs/tools/fee-estimator"
+    icon="lucide:calculator"
+  />
+  <Card
+    title="Cross-Border Cost"
+    description="Review the corridor math, World Bank data, and assumptions behind the cross-border payment cost calculator."
+    to="/docs/tools/cross-border-cost"
+    icon="lucide:globe"
+  />
+  <Card
+    title="Settlement Time"
+    description="Understand the cutoff, business-day, and holiday rules behind the settlement time estimator."
+    to="/docs/tools/settlement-time"
+    icon="lucide:clock"
+  />
+</Cards>
diff --git a/src/pages/docs/tools/cross-border-cost.mdx b/src/pages/docs/tools/cross-border-cost.mdx
@@ -0,0 +1,91 @@
+---
+title: Cross-border cost calculator methodology
+description: Corridor math, World Bank Remittance Prices Worldwide data, and stated assumptions behind the tempo.xyz cross-border payment cost calculator.
+---
+
+# Cross-border cost calculator methodology
+
+The [cross-border payment cost calculator](https://tempo.xyz/tools/cross-border-cost/) on tempo.xyz compares what it costs to send money on eight major corridors by bank wire, remittance provider, and stablecoin rail. This page documents the corridor math, the World Bank dataset behind it, and the assumptions in each comparison row. A markdown mirror of the tool is available at [tempo.xyz/tools/cross-border-cost.md](https://tempo.xyz/tools/cross-border-cost.md).
+
+## What the cost calculator computes
+
+The calculator takes four inputs: a corridor, an amount in USD (capped at $100,000,000), a frequency (one-time or monthly), and an on/off-ramp assumption (0% to 5%, default 0.75%). For each scenario it renders four cost rows — bank wire, average provider, average digital provider, and stablecoin rail — plus annual totals for monthly scenarios and context lines that compare the scenario against the global average remittance cost (6.36%) and the UN Sustainable Development Goal 10.c target (3%).
+
+Scenarios are shareable by URL, for example `?from=us&to=mx&amount=10000&frequency=monthly&ramp=0.75`.
+
+## Corridor averages from World Bank data
+
+Corridor averages are simple means of the total cost — fee plus exchange rate margin — of all services the World Bank surveyed in the corridor for a $200-equivalent send in the Q3 2025 Remittance Prices Worldwide (RPW) collection. Applied to the full dataset, this method reproduces the World Bank's published global average of 6.36% for the same quarter.
+
+The digital average covers services initiated online or by mobile phone. The World Bank's official global digital average (4.59%) uses a stricter definition that also requires digital payout, so per-corridor digital figures on this page are not directly comparable to that headline number.
+
+The Q3 2025 RPW collection surveys 6,470 services across 348 corridors and is published quarterly under a CC BY 4.0 license.
+
+## How each comparison row is computed
+
+| Row | Formula | Notes |
+| --- | --- | --- |
+| Bank wire | flat wire fee + (amount × median bank FX margin) | $40 flat fee from published US bank schedules; the FX margin is the median of banks surveyed in the corridor. Excludes intermediary and receiving-bank deductions, which can reduce what arrives. |
+| Average provider | amount × corridor average total cost % | Mean total cost of every service the World Bank surveyed in the corridor. |
+| Average digital provider | amount × corridor digital average % | Covers only services initiated online or by mobile phone. |
+| Stablecoin rail | $0.001 on-chain fee + (amount × ramp %) | On-chain fee from Tempo's [transaction fees documentation](/docs/protocol/fees); the ramp percentage is an adjustable assumption, default 0.75%. Not a quote from any provider. |
+
+Monthly scenarios multiply each per-transfer cost by 12 for the annual figure.
+
+## Corridors covered
+
+All percentages are from the Q3 2025 RPW collection, computed on a $200-equivalent send.
+
+| Corridor | Average total cost | Digital average | Services surveyed (digital) | Median bank FX margin |
+| --- | --- | --- | --- | --- |
+| United States → Mexico | 4.54% | 4.38% | 46 (29) | 1.12% |
+| United States → India | 3.68% | 3.44% | 46 (37) | 0.74% |
+| United States → Philippines | 4.52% | 4.56% | 58 (45) | 1.17% |
+| United States → Guatemala | 4.18% | 4.05% | 30 (19) | 0.98% |
+| United Arab Emirates → India | 3.71% | 5.76% | 24 (7) | 2.11% |
+| United States → Honduras | 3.99% | 3.58% | 32 (16) | 1.00% (regional estimate) |
+| United States → Dominican Republic | 5.11% | 5.24% | 27 (11) | 0% |
+| United States → El Salvador | 3.50% | 3.28% | 46 (26) | 0% |
+
+Corridor-specific caveats:
+
+- **United States → Honduras**: no banks were surveyed in this corridor in Q3 2025, so the bank wire FX margin is a regional estimate — the midpoint of median bank FX margins in neighboring US-outbound corridors (Guatemala 0.98%, Mexico 1.12%).
+- **United States → Dominican Republic**: the median bank FX margin was 0% because wires are commonly delivered in USD; receiving-side conversion to Dominican pesos may add cost not captured here. Surveyed bank services averaged 11.25% at the $200 send size, driven by flat fees.
+- **United States → El Salvador**: El Salvador is dollarized, so corridor costs are fees rather than FX margins.
+- **United Arab Emirates → India**: surveyed sends are denominated in UAE dirhams; percentages are applied to a USD amount for comparison. The online sample is small (7 services) and includes one high-cost bank service; the median online service costs 1.59%. The bank wire flat fee uses US bank schedules as a proxy.
+- **United States → Mexico**: surveyed totals ranged from promotional pricing below 0% to 17.5% for the most expensive bank service.
+
+## Cross-border calculator assumptions
+
+- The World Bank surveys consumer-sized sends of $200 and $500. The calculator applies those percentages to the entered amount for comparison. Real pricing at larger amounts usually differs: flat fees matter less and negotiated FX matters more, so treat results for business-sized transfers as directional.
+- The bank wire row uses a $40 flat fee from published US bank schedules (Chase charges $40 for online-initiated USD international wires, Bank of America $30, and Wells Fargo up to $45) plus the median FX margin of banks surveyed in the corridor. Wires sent in USD may be converted by the receiving bank at its own rate, and intermediary banks may deduct additional fees.
+- The stablecoin rail row is never zero-cost. The on-chain fee on Tempo is less than $0.001 per simple transfer, per the [transaction fees documentation](/docs/protocol/fees), and the default 0.75% on/off-ramp assumption is an explicit, adjustable estimate of conversion costs on both ends. Actual ramp pricing varies by provider, country, amount, and payout method.
+- Some surveyed services run promotional pricing, which can produce negative FX margins and totals below 0%. These are real observations in the dataset, not errors.
+- Corridor volume figures are estimates assembled from World Bank Migration and Development Briefs and central bank reporting, and are marked as estimates.
+
+Settlement speed context: Tempo produces blocks roughly every 600 milliseconds and reaches deterministic finality in under a second, per the [consensus documentation](/docs/protocol/blockspace/consensus). End-to-end delivery still depends on how quickly each side converts between stablecoins and local currency.
+
+## Cross-border data refresh cadence
+
+- The World Bank publishes RPW quarterly. Recompute corridor averages, digital averages, surveyed-service counts, and median bank FX margins from each new collection. Current figures come from the Q3 2025 collection, retrieved July 2026.
+- Bank wire flat fees come from published bank fee schedules. Re-check when banks publish new schedules.
+- Corridor volume estimates update with each World Bank Migration and Development Brief and with central bank reporting.
+
+## World Bank attribution
+
+The RPW dataset is licensed CC BY 4.0, which requires attribution when the data is reused. The calculator and this page carry the following attribution verbatim:
+
+> Source: World Bank, Remittance Prices Worldwide. Used under CC BY 4.0. Corridor averages computed by Tempo from the public dataset.
+
+Data collected Q3 2025, retrieved July 2026. License: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+## Cross-border cost sources
+
+- [World Bank, Remittance Prices Worldwide dataset (Q3 2025)](https://datacatalog.worldbank.org/search/dataset/0037898/remittance-prices-worldwide)
+- [World Bank, Remittance Prices Worldwide site](https://remittanceprices.worldbank.org)
+- [UN SDG indicator 10.c.1 metadata](https://unstats.un.org/sdgs/metadata/files/Metadata-10-0C-01.pdf)
+- [Chase, wire transfer fees](https://www.chase.com/personal/banking/education/basics/wire-transfer-fees)
+- [Bankrate, wire transfer fees survey](https://www.bankrate.com/banking/wire-transfer-fees/)
+- [BIS CPMI analysis of Swift gpi data](https://www.bis.org/cpmi/publ/swift_gpi.pdf)
+- [Tempo transaction fees documentation](/docs/protocol/fees)
+- [Tempo consensus documentation](/docs/protocol/blockspace/consensus)
diff --git a/src/pages/docs/tools/fee-estimator.mdx b/src/pages/docs/tools/fee-estimator.mdx
@@ -0,0 +1,131 @@
+---
+title: Fee estimator methodology
+description: How the tempo.xyz transaction fee estimator turns gas figures and the TIP-1010 base fee into USD costs, including the /api/fee-estimate JSON contract.
+---
+
+# Fee estimator methodology
+
+The [transaction fee estimator](https://tempo.xyz/tools/fee-estimator/) on tempo.xyz estimates what a transaction costs on Tempo in USD. This page documents the fee formula, the gas figures and their provenance, the live base fee refresh, and the public `/api/fee-estimate` endpoint. A markdown mirror of the tool is available at [tempo.xyz/tools/fee-estimator.md](https://tempo.xyz/tools/fee-estimator.md).
+
+## What the fee estimator computes
+
+The estimator prices three operations in network fees:
+
+- A single TIP-20 transfer.
+- A TIP-20 transfer with memo.
+- A batch of `N` TIP-20 transfers, with `N` clamped to 1 through 10,000.
+
+It also converts between attodollars, microdollars, and US dollars. Without JavaScript, the page shows figures computed at the documented base fee. With JavaScript, it refreshes the base fee from a live `eth_gasPrice` query against `https://rpc.tempo.xyz` and labels the source and fetch time.
+
+The result is the network fee for including and executing the transaction. Per the [fee specification](/docs/protocol/fees/spec-fee), the protocol deducts the maximum fee up front and refunds unused gas after execution, so the amount shown reflects the gas the transaction actually uses. Fees are paid directly in a supported USD-denominated stablecoin; Tempo has no native token.
+
+## Fee formula and units
+
+The estimator uses the formula from the [fee specification](/docs/protocol/fees/spec-fee):
+
+```
+fee = ceil(base_fee × gas_used ÷ 10^12) microdollars
+```
+
+`base_fee` is denominated in attodollars (10^-18 USD) per gas, and one microdollar (10^-6 USD) equals one TIP-20 token unit.
+
+| Unit | Relationship |
+| --- | --- |
+| 1 microdollar | `10^12` attodollars, or one TIP-20 token unit (TIP-20 tokens have 6 decimal places) |
+| 1 US dollar | 1,000,000 microdollars, or `10^18` attodollars |
+| Fee for one TIP-20 transfer | `10^15` attodollars = 1,000 microdollars = $0.001 |
+
+Tempo quotes per-gas prices in attodollars because they are far smaller than stablecoins can represent: the smallest unit of a 6-decimal TIP-20 token is one microdollar, while the base fee is $0.00000002 per gas. When a transaction settles, the protocol converts the total fee back to token units by dividing by `10^12` and rounding up.
+
+## Base fee provenance
+
+The static base fee is 20 billion attodollars per gas (`2 × 10^10`), from the [TIP-1010](https://github.com/tempoxyz/tempo/blob/main/tips/tip-1010.md) gas parameters listed in the [fee specification](/docs/protocol/fees/spec-fee). Tempo cross-checked this value against a live `eth_gasPrice` query on `rpc.tempo.xyz` (which returned `0x4a817c800`) on July 5, 2026.
+
+Tempo currently uses a fixed base fee rather than a variable base fee as in EIP-1559, so the base cost of a transaction does not float with demand. Approximately 94% of blockspace is reserved for payment transactions, and an optional priority fee lets a transaction bid for faster inclusion during periods of high demand. Priority fees are excluded from the estimate.
+
+:::info[Dynamic base fee in T7]
+The [T7 network upgrade](/docs/protocol/upgrades/t7) introduces a dynamic base fee that can fall when block gas usage is below target. The estimator and the API prefer the live RPC value over the static TIP-1010 fallback, so they track the network as fee parameters change.
+:::
+
+## Gas figures and their provenance
+
+| Operation | Gas used | Provenance |
+| --- | --- | --- |
+| TIP-20 transfer | ~50,000 | Documented. The fee specification states that a standard TIP-20 transfer (~50,000 gas) costs approximately 1,000 microdollars at the base fee. |
+| TIP-20 transfer with memo | ~51,000 | Estimate. `transferWithMemo` emits one additional event carrying a fixed 32-byte memo. Tempo publishes no separate gas figure for it, so the estimator adds a small allowance to the documented transfer cost. |
+| Batch of `N` transfers | `N × 50,000` | Conservative estimate. Batched Tempo Transactions share per-transaction overhead, so actual gas per transfer is typically somewhat lower. Very large payout runs may span multiple transactions; the estimate scales linearly either way. |
+
+## What the fee estimate excludes
+
+The estimate covers Tempo network fees only:
+
+- Optional priority fees.
+- On-ramp and off-ramp costs, which vary by provider.
+- FX costs for currency conversion.
+
+For context, the tool compares the network fee against Chase's published Additional Banking Services and Fees schedule (effective June 14, 2026): $25 for an online domestic wire, $35 banker-assisted domestic, $40 for a consumer online USD international wire, and $50 banker-assisted international. A wire fee is the bank's end-to-end price for the transfer, while the Tempo figure is the on-chain network fee alone.
+
+## Fee estimate API
+
+The same estimate is available as a public JSON endpoint. The endpoint fetches the live base fee (`eth_gasPrice`) from the public Tempo RPC server-side with a 3-second timeout and falls back to the documented TIP-1010 value when the RPC is unreachable.
+
+```bash
+curl "https://tempo.xyz/api/fee-estimate/?operation=batch&count=250"
+```
+
+### Fee estimate request parameters
+
+| Parameter | Values | Behavior |
+| --- | --- | --- |
+| `operation` | `transfer`, `memo`, `batch` | Defaults to `transfer`. Unknown values return HTTP `400` with an `error` field. |
+| `count` | `1` to `10000` | Batch only; ignored for other operations. Clamped into range; defaults to `1`. |
+
+### Fee estimate response fields
+
+```json
+{
+  "operation": "batch",
+  "count": 250,
+  "gasUsed": 12500000,
+  "gasNote": "Conservative estimate at N x 50,000 gas. Batched Tempo Transactions share per-transaction overhead, so actual gas per transfer is typically somewhat lower.",
+  "basefeeAttodollars": "20000000000",
+  "feeMicrodollars": "250000",
+  "feeUsd": 0.25,
+  "formula": "ceil(base_fee_attodollars * gas_used / 10^12) microdollars",
+  "source": "live eth_gasPrice from https://rpc.tempo.xyz",
+  "timestamp": "2026-07-05T00:00:00.000Z",
+  "docs": "https://tempo.xyz/developers/docs/protocol/fees/spec-fee"
+}
+```
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `operation` | string | Operation that was priced. |
+| `count` | number | Effective transfer count after clamping. |
+| `gasUsed` | number | Total gas for the operation. |
+| `gasNote` | string | Provenance note for the gas figure (documented versus estimated). |
+| `basefeeAttodollars` | string | Base fee used, in attodollars per gas. Serialized as a string to preserve integer precision. |
+| `feeMicrodollars` | string | Total fee in microdollars (TIP-20 token units), serialized as a string. |
+| `feeUsd` | number | Total fee in US dollars. |
+| `formula` | string | The fee formula applied. |
+| `source` | string | Either the live `eth_gasPrice` from `https://rpc.tempo.xyz` or the static TIP-1010 value with its check date. |
+| `timestamp` | string | ISO 8601 time the response was generated. |
+| `docs` | string | Link to the fee specification. |
+
+### Fee estimate caching and CORS
+
+Responses set `Cache-Control: public, max-age=60, s-maxage=300`; short caching is safe because the base fee is set at the protocol level. Responses also set `Access-Control-Allow-Origin: *`, so wallets, docs, and tutorials can call the endpoint directly from a browser.
+
+## Fee data refresh cadence
+
+- The page and the API prefer the live `eth_gasPrice` value at request time, so estimates track the network automatically.
+- The static fallback (20 billion attodollars per gas) and the gas figures were checked against TIP-1010, the fee specification, and the live RPC on July 5, 2026. Re-check them quarterly and at each network upgrade; the T7 upgrade changes the base fee model.
+- The bank wire comparison uses Chase's schedule effective June 14, 2026. Re-check when the bank publishes a new schedule.
+
+## Fee estimator sources
+
+- [Tempo fee specification](/docs/protocol/fees/spec-fee) (fee formula, units, gas per TIP-20 transfer, payment lane allocation)
+- [Transaction fees documentation](/docs/protocol/fees) (fee model, supported fee tokens)
+- [TIP-1010](https://github.com/tempoxyz/tempo/blob/main/tips/tip-1010.md) (base fee gas parameters)
+- Tempo public RPC, `https://rpc.tempo.xyz` (live `eth_gasPrice`)
+- [Chase, Additional Banking Services and Fees schedule](https://www.chase.com/content/dam/chase-ux/documents/personal/checking/ABSF-en.pdf) (wire fee comparison, effective June 14, 2026)