SubEtha is a **local, non-production proof of concept** for machine payments: an AI agent pays for an HTTP resource with the official **x402 v2** flow, and the payment settles through zERC20's burn → proof-gated mint. What the construction hides is the **correspondence between payer and provider on-chain**; amounts are public. This page orients you — who the site is for, what SubEtha is and is not, the mental model behind every other page, and where each audience should go next. ## Who this site is for - **Payer developers** — you build an AI agent or script that should pay for HTTP resources per request, with no API keys or human checkout in between. - **Provider developers** — you serve an HTTP API and want to charge for it behind a `402 Payment Required` paywall using the official x402 middleware. - **Facilitator operators** — you run the settlement daemon that derives burn addresses, verifies and settles payments, and drives finalization. - **Evaluators** — you want to judge precisely what the construction does and does not guarantee before running any code. Start with [Trust & Limits](/trust/). ## What SubEtha is — and is not SubEtha **is**: - **a bridge, not a new token.** It combines the official x402 v2 protocol with the official zERC20 toolchain. Everything SubEtha-specific rides inside x402 v2's standard extension points under the scheme `subetha-zerc20`; the envelope and headers are unmodified x402 v2. - **a local proof of concept.** The whole flow runs end-to-end against a local development stack (anvil, the deployed zERC20 contracts, an indexer, and a prover). Nothing on this site describes a hosted service. - **a correspondence-hiding construction.** The payer pays a one-time burn address; the provider's treasury is later funded by a proof-gated mint that an on-chain observer cannot link back to any particular burn. SubEtha **is not**: - **production-ready.** The facilitator refuses payment acceptance outside an explicit `local` profile, and commercial or production use of the underlying `@zerc20/sdk` (BUSL-1.1) requires a separate license grant. - **a system without trusted parties.** The facilitator is a trusted intermediary that sees every payment and holds the settlement keys. [Trust & Limits](/trust/) spells out who must trust whom, and for what. - **a cloak over everything.** Amounts are public, the payer's burn transfer is an ordinary-looking on-chain event, and the HTTP layer is untouched. [Privacy: what SubEtha hides — and what stays public](/concepts/privacy/) draws the exact line. ## The five-minute mental model 1. **The payer asks, unpaid.** An agent requests the resource with no payment headers. 2. **The provider answers 402 with an offer.** The offer quotes the price and names a **one-time burn address** as `payTo` — freshly derived for every 402, never the provider's real payout destination. Only the facilitator can derive these addresses, so the provider fetches a fresh challenge from it per 402. 3. **The payer pays the burn address.** Either the payer only signs and the facilitator broadcasts the burn (the gasless permit path), or the payer broadcasts the burn transfer itself (the self-transfer fallback). 4. **Accepted → the resource is served.** Once the burn is confirmed on-chain, the payment is `accepted` and the resource is released. The funds are already burned; the payer cannot reclaim them. If settlement fails, nothing is served. 5. **Finalized → the mint lands, later.** Minutes afterwards and never on the request path, the facilitator's finalize loop proves the right to receive and mints to the provider's treasury. That asynchronous mint is `finalized` — a distinct state that no page on this site conflates with `accepted`. See [Accepted vs finalized](/concepts/accepted-vs-finalized/). ## Terminology | term | meaning | |---|---| | **x402 v2** | the official HTTP payment protocol SubEtha rides on: `402 Payment Required` plus the `PAYMENT-REQUIRED` / `PAYMENT-SIGNATURE` / `PAYMENT-RESPONSE` headers, version 2 envelope | | **scheme** | a named payment method inside x402. SubEtha registers `subetha-zerc20`; clients without a handler for it skip SubEtha offers gracefully | | **offer** | the `PaymentRequirements` carried by a 402 response: scheme, network, token, quoted amount, the one-time burn address as `payTo`, and an expiry | | **accepted** | the synchronous settlement state: the burn transfer to the one-time `payTo` is confirmed on-chain and the resource may be served | | **finalized** | the asynchronous settlement state: the proof-gated mint to the real recipient has landed on-chain — reached minutes later, never on the request path | ## Protocol scope This site documents **x402 v2 only**. MPP framing is deferred in the product at the pinned commit and is not documented here. ## Where to go next - **Payer developers** — read [x402 v2 on SubEtha](/concepts/x402-v2/), then the [TypeScript API](/reference/typescript/) or [Python API](/reference/python/) for the published client packages and the `SUBETHA_*` environment variables in the [configuration reference](/reference/configuration/). - **Provider developers** — read the [architecture](/concepts/architecture/) page for the trust boundaries, then the [wire protocol reference](/reference/protocol/) (middleware integration) and the [TypeScript API](/reference/typescript/). - **Facilitator operators** — read the [configuration reference](/reference/configuration/) and [Security](/trust/security/). The facilitator is source-only (built from the product repository workspace — there is no published package for it); the operator runbook is [`docs/FACILITATOR.md`](https://github.com/peaceandwhisky/SubEtha/blob/638fa1e9ca7face19a442cef43754f0d627c7705/docs/FACILITATOR.md). - **Everyone** — [Trust & Limits](/trust/) before running anything. The [payer, provider, and facilitator quickstarts](/quickstarts/) and the [local-flow tutorial](/tutorial/local-flow/) provide the current hands-on path. All are local, non-production PoC material like everything else here. ## English-first documentation policy English is the canonical published locale. Japanese is planned but is not a published route until a complete translation has passed the same source, privacy, safety, link, and build checks. Do not add placeholder Japanese pages or navigation entries; until a translation is complete, link readers to the English page.