Project case study · Bitcoin + x402
From fee data to a usable decision.
A Bitcoin fee calculator and API built around a simple requirement: show where the numbers came from, how old they are, and what they mean for a transaction.
TypeScript · Hono · Cloudflare Workers · D1 · x402 v2
01 / The problem
A fee rate is only part of the answer.
A rate in satoshis per virtual byte needs a transaction size to become a cost. It also needs a timestamp: a plausible number from an old snapshot can still be the wrong number to use.
The free tool compares four priority tiers and calculates the total in sats. The API exposes the same source data and freshness fields for applications. Neither requires an account or wallet connection.
02 / The implementation
One snapshot, two ways to use it.
- Fetch and validate. Three fixed mempool.space sources supply fee rates, mempool size, and projected blocks. Requests have deadlines and response-size limits. Invalid data never becomes a displayed estimate.
- Serve the free workflow. A shared cache keeps validated snapshots fresh for 30 seconds, with a clearly marked fallback through age 120 seconds. The calculator renders HTML on the server; the free API returns documented JSON.
- Explore payment separately. An optional x402 route adds a deterministic send-or-wait heuristic. Payment requirements, verification, and confirmed settlement are distinct steps; the evidence store uses D1.
03 / Engineering choices
Make the boundaries visible.
-
Useful without JavaScript
Server-rendered pages, native GET forms, local fonts, keyboard navigation, and mobile layouts keep the main workflow small and inspectable.
-
Freshness survives asynchronous work
Cache age is checked after retrieval and again after a failed refresh. Regression tests cover a concurrent cache fill and data crossing the fallback age limit.
-
Payment evidence has a precise meaning
A 402 response proves that a payment is requested. It does not prove someone paid. Confirmed receipts and operator tests have separate treatment in the evidence method.
-
Small operating footprint
The current deployment uses the Workers and D1 free plans, with a gas-sponsored facilitator. There are no tracking scripts. Infrastructure request totals are not treated as a count of people.
04 / What to inspect
A working tool, an explicit experiment.
Try the calculator, run the JavaScript or curl quickstart, and inspect the OpenAPI contract. The status page reports configuration; it is not an uptime history.
Confirmation times are source targets, not guarantees. The paid heuristic compares current rates; it cannot predict future fees. Source outages can leave the calculator temporarily unavailable.
As of October 4, 2026, the mainnet payment challenge has been checked, but a real mainnet settlement has not been exercised by this project. Sustained external adoption is still unproven.
The public repository currently contains the historical Python implementation. Publication of the current Worker source and signed release artifacts is pending.
2026 timeline
- Building since March 2026. The initial broad Bitcoin API and x402 experiments established the starting point.
- Paused June–August 2026. The paid surface was not continuously live; work stopped while claims, privacy, and settlement behavior were reassessed.
- Rebuilt on x402 v2 in August 2026. The replacement is an isolated one-resource edge lab with fail-closed manifests and contract tests.
- September 8: a useful Bitcoin + x402 home. A free fee calculator, API quickstart, response schemas, and curated framework starters make the site useful without a payment. Explore the resources.
- October 4: maintenance and client migration. Updated the Worker dependencies, removed fee-source work from homepage uptime checks, and added migration guidance for retired API clients. See status for the current payment setting; enabled payments alone do not establish a successful settlement.
- October 4: reliability and portfolio refinement. Corrected cache timing around asynchronous reads and refreshes. The calculator now leads with a transaction cost, and this case study explains how the working pieces fit together.
- Current boundary. The old broad API and facilitator are not live. A local implementation is not a deployment or evidence of demand.
What earns a claim
Source, deterministic behavior, protocol compatibility, a confirmed receipt, privacy-safe evidence, and stable operations are separate gates. None is inferred from requests or challenges.