<!-- Generated raw Markdown for /v2/providers; product pin 68e061b1bfaf91aa831b06cfe9af72fe3a46fe12. -->

# 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](/v2/#who-sees-what).

## 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](#limits). Whether your pricing changes is not established by the
records.

## 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

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

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)](/v2/providers/register/). 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](/v2/providers/register/#prices).

**Through the operator.** This path stays open:

1. 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.**
2. The operator registers you and issues a Provider token and a one-time probe address.
3. 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.
4. 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

- 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

**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

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](/v2/status/).

## 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](/v2/providers/register/#get-the-tools-verify-before-you-run-anything).

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

- Email: `contact@subethalabs.com` (applications and testnet registration requests go to the same address)
- X: `@subethalabs`
- Landing page: [for Providers](https://subethalabs.com/#providers),
  [contact](https://subethalabs.com/#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.
