Skip to content
SubEthaDocs

Start here

SubEtha enables 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:

  • an integration layer, 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 complete, inspectable flow. Request, 402 offer, payment, acceptance, and asynchronous finalization are all implemented. The end-to-end tutorial runs every component on a local development stack so the whole flow can be inspected.
  • a correspondence-hiding construction. The payer pays a one-time burn address; the provider’s treasury is later funded by a proof-gated mint whose on-chain signals do not identify the corresponding burn. See the Privacy caveats for the limits of this claim.

SubEtha is not:

  • a documented production deployment path yet. The verified, documented path currently runs against a local development stack; production deployment and operational guarantees are outside the current documented scope. Trust & Limits explains what the system does and does not guarantee before you run anything.
  • 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 the payment method named in an x402 offer. subetha-zerc20 tells a compatible payer to use SubEtha’s zERC20 burn-and-mint flow; clients that do not support it can ignore that offer and look for another supported payment method
offer the PaymentRequirements carried by a 402 response: scheme, network, token, quoted amount, the one-time burn address as payTo, and an expiry
zERC20 the token construction SubEtha settles through: tokens are burned to a derived one-time address and later minted to the real recipient behind a proof-gated mint intended to hide the corresponding burn from on-chain observers; see the Privacy caveats
burn address / payTo the one-time address quoted in each offer. Paying it destroys the tokens; it is never the provider’s payout destination
facilitator the trusted settlement daemon that derives burn addresses, verifies and settles payments, and drives finalization
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. The tutorial uses the local stack described in its prerequisites; the package and protocol references apply to deployment and integration work beyond that environment.

English-first documentation policy

Section titled “English-first documentation policy”

English is the only published language for now. A Japanese version is planned and will be published after it has been checked against the same verified product sources.