@subetha/provider

Provider-side scheme server, payment handler, offer validation, and facilitator HTTP client for the SubEtha x402 payment scheme.

Install

npm install @subetha/provider @x402/core

@x402/core is a peer dependency (type-level integration with the official x402 server interfaces). @subetha/x402-scheme is installed automatically as a regular dependency.

Requires Node.js >= 20 (ESM).

Usage

Mount the SubEtha scheme server and payment handler into your own API, pointing them at an externally reachable SubEtha Facilitator service (this package does not start one):

import {
  SubethaFacilitatorClient,
  SubethaSchemeServer,
  subethaHandler,
} from "@subetha/provider";

// HTTP client for your Facilitator (x402 /verify /settle /supported + SubEtha's
// POST /challenge extension, which mints the one-time burn address per offer).
const facilitator = new SubethaFacilitatorClient("https://facilitator.example.com");

// Scheme server for "subetha-zerc20" — structurally implements the official
// x402 SchemeNetworkServer, so it plugs into @x402/core server middleware.
const schemeServer = new SubethaSchemeServer(facilitator);

// Wrap a return-value resource handler into an Express-compatible route handler.
app.post(
  "/api/complete",
  subethaHandler(async (req) => ({ body: { answer: 42 } })),
);

How the packages relate

• @subetha/x402-scheme — shared scheme types, the client-side payload builder, and fee parsing. It is the leaf of the dependency chain.
• @subetha/provider (this package) — the provider (resource-server) side: scheme server, payment handler, offer validation, and an HTTP client for a SubEtha Facilitator.

The provider talks to a SubEtha Facilitator as an external HTTP service — these packages include no Facilitator runtime or backend and do not enable launching one. The end-to-end private settlement path additionally requires a running Facilitator and the official zERC20 toolchain, which are not part of these packages.

Documentation

• Protocol: https://github.com/peaceandwhisky/SubEtha/blob/main/docs/PROTOCOL.md
• Facilitator: https://github.com/peaceandwhisky/SubEtha/blob/main/docs/FACILITATOR.md
• Fees: https://github.com/peaceandwhisky/SubEtha/blob/main/docs/FEES.md
• Repository README: https://github.com/peaceandwhisky/SubEtha#readme

License

SubEtha's own code (this package) is licensed under Apache-2.0 (see LICENSE, NOTICE).

The end-to-end private-settlement path additionally depends on the official zERC20 toolchain (@zerc20/sdk and the zERC20 contracts), which is licensed under BUSL-1.1 with Additional Use Grant = None and is not included in this package. Production or commercial use of that toolchain requires a commercial license obtained directly from the zERC20 licensor; installing this package grants no such right. This package does not claim any official partnership, certification, or endorsement by the zERC20 team.