For Providers: adopt alongside x402
This page is for a Provider that already sells an HTTP API through x402 and wants to add SubEtha v2 next to it. It describes the documented integration and the hosted testnet as the product repository records them. What the public chain shows, and to whom, is summarised in Who sees what.
What stays, what changes
Section titled “What stays, what changes”What stays. The standard x402 exact flow. The unmodified official client on the buyer side.
The official Express middleware on your side. SubEtha v2 is added next to your existing x402
routes rather than replacing them.
What changes.
- Customers need zUSDC (wrapped USDC) instead of the asset your ordinary routes take.
- The facilitator supplies a per-order
payTo; there is no fixed receiving address to configure for the SubEtha routes. - The integration holds your handler’s response until the mined receipt has been re-validated, then releases it.
- In the hosted configuration, your POS key determines the intended wallet destination of each order’s address.
A mined payer-to-burn-address transfer and body delivery do not establish merchant-side private mint or spendability; see Limits. Whether your pricing changes is not established by the records.
Requirements
Section titled “Requirements”The documented integration is Express on Node >= 22.12 (verified with v22.23.4) and pnpm 10.15.1.
Compiled entry points run with plain node, not tsx. The records do not establish integration
with other server frameworks. Provider and facilitator processes are not designed for browser
embedding.
The Provider mounts @subetha/provider/x402 around an existing Express handler: createSubetha
returns guard, paymentMiddleware (the official @x402/express 2.28.0 middleware, built for
you), observer, handlers and start(). The existing handler runs before settlement; its output
is held and released only after settlement.
Rules that follow from the design:
- Handlers run before settlement, and their side effects are not rolled back if settlement or release fails. Keep paid handlers idempotent or read-only.
- Use the supported response API. A handler that writes to the raw socket bypasses the response guard.
- A 202 is not delivery. Only status 200 is sold, and there is one order per 402.
- The sample’s result-size limit defaults to 1 MiB and is configurable. That is a sample default, not a hosted-service limit.
Delivery on the hosted testnet
Section titled “Delivery on the hosted testnet”On the hosted testnet, delivery follows the mined receipt without a finality gate. The facilitator
re-validates the mined receipt (one AuthorizationUsed, one transfer of the order amount to the
order’s address, on time by block time) and then grants the release. A reorg or an ASP rejection
can occur after delivery, so body delivery does not guarantee merchant credit or spendability.
Provider-only rage exit is unverified and is not a verified remedy. A slower finalized policy
exists in the source; it is not available on the hosted testnet’s receipt-only path.
Settlement on the hosted testnet is relayed to a delegated x402 facilitator, which broadcasts and pays gas. The relay is unguaranteed, and its terms and mainnet availability are unknown.
Registering on the hosted testnet
Section titled “Registering on the hosted testnet”Registration is testnet only, and there are two ways in.
By application. You apply by email to contact@subethalabs.com; the operator reviews the
application and, if it is approved, sends an invite code. Approval is not guaranteed and capacity
is limited. With the code, you make a POS key, register, pay a one-time probe and activate from
your own machine, signed by your own EOA. What to put in the application, the full procedure, its
exit codes and its recovery rules are in
Register and run a Provider (by application). The Provider tools and the
extension are installed from the npm registry at the exact versions listed on that page, each
checked against its integrity value; the tarballs in the invite packet are the alternative.
You set your prices per route in your own Provider, up to the facilitator’s price cap; see
Prices.
Through the operator. This path stays open:
- Make a POS key in your own wallet. Send the operator the POS key file and your Provider address. Never send a seed or a view key.
- The operator registers you and issues a Provider token and a one-time probe address.
- Pay the probe from your own EOA as the operator instructs (the operator does not pay it or send you funds), confirm the payment in your own wallet, and notify the operator. Orders become available only after operator activation.
- Run the official middleware with the SubEtha extension pointed at your own lane of the hosted facilitator, with your Provider token.
Connection details, the probe amount and the token values are given privately (with the invite code, or by the operator at registration) and are not published here.
Audit and withdraw
Section titled “Audit and withdraw”- Keep every generation’s probe address. Supply all of them, with your own view key, to each audit.
- Audit regularly. The audit compares the facilitator’s orders with your wallet and reports disagreement.
- Withdrawals are public, journaled, and not repeated automatically.
Trust boundary
Section titled “Trust boundary”Hosted testnet. The facilitator operator sees, per order, the payer address, amount,
transaction, digest and Provider. It holds only each Provider’s POS key: it can derive addresses,
write that Provider’s lane, and know which addresses are the Provider’s. It cannot spend. It holds
no seed and no view key. You trust the payTo the facilitator hands out at 402 time and audit
afterwards with your own view key. The operator could still withhold orders, attribute an order to
another Provider, or hand out an address that is not yours; the audit finds this after the fact.
Self-run facilitator. The operator holds the merchant and broadcaster keys, funds the broadcaster, and sees the merchant wallet’s whole activity. Running your own facilitator is possible from the same source; it is a different configuration from the hosted testnet and is not covered by the hosted records.
Limits
Section titled “Limits”The hosted testnet promises no availability or retention. Capacity is limited and the service may be paused or reset.
Verification limits of the documented records:
- The Sepolia sample does not cover several payers, more orders, budget refills, monitoring or hosting.
- Browser wallet signing and browser purchase-to-recovery are not verified.
- Multi-instance deployment, Router integration, mainnet and a latency SLA are outside the sample’s verification scope; the sample states Router and SVM are out of its scope.
- Real reorgs and sustained latency are not proven.
- The hosted record adds one purchase at switchover, not sustained-operation or scale evidence.
- Provider-only rage exit is unverified.
- Merchant private-state mint and spendability were not observed in the documented Sepolia runs T9 and T10-H. The hosted-testnet record of 2026-11-09 confirms relay, delivery and recovery 200, and does not establish merchant private-state mint or spendability.
The dated records themselves are on the status page.
Source access and licence
Section titled “Source access and licence”The v2 Provider extension is the ./x402 entry of @subetha/provider 0.2.0. That version, with
@subetha/x402-scheme 0.2.0 and the Provider tools @subetha/provider-tools 0.1.0, is installed
from the npm registry at exactly those versions; @subetha/provider 0.1.0 is the V1 package and
has no ./x402 subpath. The v2 facilitator and adapter are private workspace packages; source
access is an authorized checkout of the private repository, provided to design partners on request.
The three versions carry no npm provenance attestation. Approved applicants also receive them as
package tarballs with the invite code, and every copy is checked against an integrity value on the
registration guide.
SubEtha-authored code is Apache-2.0. The zERC20 v2 SDKs are installed from npm under their own terms. The repository grants no commercial-use rights, public-hosting rights or official status for any zERC20 component. Production-use permission is not established by the evidence. This offering is framed as testnet design-partner work.
Contact
Section titled “Contact”- Email:
contact@subethalabs.com(applications and testnet registration requests go to the same address) - X:
@subethalabs - Landing page: for Providers, contact
No demo, delivery date or SLA is promised. What is offered is a conversation and testnet registration, by application or on request.
Reviewed 2026-11-16 against the product repository at e972064; re-read on 2026-11-18 against 68e061b, which changes only the quickstart’s and the operations notes’ funding and probe text. Evidence is the product
repository’s own records; this site made no payment for this page.