Skip to content
SubEthaDocs

Start here

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

Section titled “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.

What SubEtha is — and is not

Section titled “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 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 draws the exact line.

The five-minute mental model

Section titled “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.

Terminology

Section titled “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

Section titled “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

Section titled “Where to go next”

The payer, provider, and facilitator quickstarts and the local-flow tutorial provide the current hands-on path. All are local, non-production PoC material like everything else here.

English-first documentation policy

Section titled “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.