@subetha/x402-scheme

Types, client-side payload builder, and fee parsing for the SubEtha x402 payment scheme (subetha-zerc20).

Install

npm install @subetha/x402-scheme @x402/core

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

Requires Node.js >= 20 (ESM).

Usage

import { SUBETHA_SCHEME, SubethaSchemeClient, parseFee } from "@subetha/x402-scheme";
import { privateKeyToAccount } from "viem/accounts";

console.log(SUBETHA_SCHEME); // "subetha-zerc20"

// x402 v2 scheme handler for the paying side. In the default "permit" mode the
// client only signs — the facilitator broadcasts the burn (gasless for the payer).
const client = new SubethaSchemeClient({
  account: privateKeyToAccount(process.env.PAYER_KEY as `0x${string}`),
  rpcUrl: "https://sepolia.optimism.io",
});

// Inspect the facilitator fee quoted inside a 402 offer's requirements
// (returns undefined when the offer carries no fee).
declare const requirements: import("@x402/core/types").PaymentRequirements;
const fee = parseFee(requirements);

How the packages relate

• @subetha/x402-scheme (this package) — shared scheme types, the client-side payload builder, and fee parsing. It is the leaf of the dependency chain.
• @subetha/provider — 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.