@z402-net/client

@z402-net/client is the paying side of z402. Its main export, PrepaidVoucherScheme, plugs into the stock x402 client. For each provider it makes the deposits, signs a voucher for every call, and reads the outcome of each call to decide what to do next. Pay from an agent shows it at work. This page lists everything the package exports.

Install and import

npm install --save-exact @z402-net/client @z402-net/lightwalletd @x402/fetch@2.28.0 @x402/core@2.28.0

@z402-net/client is an ES module. It depends on @z402-net/protocol, which is installed with it, and it takes @x402/core as a peer dependency at exactly 2.28.0, so you install that yourself. It has no dependency on @x402/fetch: install that yourself for x402Client and wrapFetchWithPayment. The package needs no gRPC or wallet library. It reaches the chain through an object you give it, such as the client from @z402-net/lightwalletd, and Zallet through fetch. It also re-exports the seams that a wallet or a chain source of your own implements, so you need no @z402-net/protocol import for them.

import {
  LightwalletdTxStatus,
  PrepaidVoucherScheme,
  ZalletRpcWallet,
} from "@z402-net/client";

// For a wallet or a chain source of your own
import { ChainUnavailableError, type TxStatus, type TxStatusSource, type ZcashWallet } from "@z402-net/client";

At a glance

PrepaidVoucherScheme

class PrepaidVoucherScheme implements SchemeNetworkClient {
  readonly scheme: "prepaid-voucher";
  readonly schemeHooks: { onPaymentResponse(ctx: PaymentResponseContext): Promise<void | { recovered: true }> };
  constructor(opts: PrepaidVoucherSchemeOptions);
  findDefaultAsset(asset: string, network: Network): DefaultAsset | undefined;
  createPaymentPayload(x402Version: number, req: PaymentRequirements, ctx?: PaymentPayloadContext): Promise<PaymentPayloadResult>;
  session(payTo: string, network?: string): SessionView | undefined;
  sessions(): SessionView[];
  close(): Promise<void>;
}

The scheme keeps one session for each network and payTo pair it pays. A session is created on the first offer from that pair: a new random Ed25519 key, a running total of 0, and no deposits. Sessions live in memory only.

Scheme options

The constructor throws a RangeError for a seed that is not 32 bytes, for a pollIntervalMs that is not above 0, and for a negative or NaN safetyReleaseMs, maxDeposits, confirmationWaitMs or facilitatorLagMs. The message names the option.

Members

createPaymentPayload returns { x402Version, payload }, where x402Version is the one it was given and payload is { sessionKey, cumulativeZat, sig, depositTxid? }. The cumulativeZat is the session's running total plus the price of this call. sig is the Ed25519 signature of the voucher message, and depositTxid is the newest deposit in the state sent, until a settle acknowledges it. The fields are in Protocol.

What createPaymentPayload checks

It checks the offer before it takes any lock or calls the wallet, and every error message names its field. The rules run in this order, and the first one that fails throws.

After the checks, it throws session halted by <code> on deposit <txid> when the session was halted, before and after waiting for the lock. A session halts when the provider rejected a deposit, when the provider asked for another deposit while the one this call presented was pending or not listed, which the scheme treats as a fault on the provider's side, or when the wallet threw DepositStatusUnknownError. A halted session never deposits or signs again, and its halted field says why.

When the scheme deposits

The scheme decides before each voucher. The first rule that matches wins.

The headroom is the limit in the last snapshot minus the running total. A background deposit runs at most one at a time for a session, and a failed one is reported as deposit_failed and tried again at the next trigger. Its txid is attached to the first voucher signed after it returns.

With the stock client

• Registration. new x402Client().register(network, scheme) is the whole setup. The scheme pays only offers on the network you register.
• Spend controls. findDefaultAsset makes ZEC a default asset with 8 decimals. The stock client's default cap of one dollar per payment is then 100,000,000 zat. The scheme gets that cap as maxAmountPerPayment and refuses a window above it. Set a cap in zat with client.setSpendControls({ allowedAssets: [{ network, asset: "ZEC", maxAmountPerPayment: "..." }] }).
• One call at a time per provider. createPaymentPayload takes the session's lock, and the outcome hook releases it. Calls to other providers do not wait. If the hook never runs, for example because the request threw, the lock is released after safetyReleaseMs and the call counts as ambiguous.
• One retry. The stock wrapper retries once when the hook returns { recovered: true }. The scheme knows the retry is the final attempt because the wrapper reuses the same offer object. On a final attempt it never waits and never deposits inline, though it may start a background deposit for the next call.

SessionView

session() and sessions() return copies, so changing one changes nothing in the scheme.

interface SessionView {
  readonly network: string;
  readonly payTo: string;
  readonly sessionKey: string;
  readonly cumulativeZat: bigint;
  readonly snapshot: SessionSnapshot | undefined;
  readonly deposits: readonly Readonly<LocalDeposit>[];
  readonly nextIndex: number;
  readonly depositsMade: number;
  readonly halted: { readonly code: string; readonly txid: string | undefined } | undefined;
}

const view = scheme.session("uregtest1...", "zcash:regtest");
console.log(view?.cumulativeZat, view?.snapshot?.limitZat, view?.deposits.map((d) => d.state));
if (view?.halted !== undefined) console.warn(`halted by ${view.halted.code} on ${view.halted.txid ?? "no txid"}`);

halted says whether a session is halted, and why. The fatal event and the session halted by error from paidFetch report it too.

Deposit states

interface LocalDeposit {
  index: number;
  memo: string; // "<sessionKey>:<index>"
  txid?: string;
  state: "sending" | "sent" | "acked" | "dead" | "rejected" | "failed" | "uncertain";
}

Only a successful settle acknowledges a deposit. A snapshot that a refusal carries is a projection: the scheme resyncs the running total from it and copies dead statuses, but never acknowledges a deposit from it. An uncertain deposit with a txid is checked at most once every 10 seconds, when the next payload is created. It becomes sent once the chain shows it, and dead after a not-found streak of 120 seconds and 2 blocks, or at its expiry.

ClientEvent

onEvent receives one of these. All amounts are zat strings.

type ClientEvent =
  | { type: "session"; network: string; payTo: string; sessionKey: string }
  | { type: "deposit_started"; index: number; inline: boolean }
  | { type: "deposit_broadcast"; index: number; txid: string; ms: number }
  | { type: "deposit_failed"; index: number; error: Error }
  | { type: "deposit_acked"; txid: string }
  | { type: "deposit_confirmed"; txid: string; index?: number; height?: number; snapshot?: SessionSnapshot }
  | { type: "deposit_dead"; txid: string }
  | { type: "voucher"; cumulativeZat: string; depositTxid?: string }
  | { type: "paid"; cumulativeZat: string; snapshot?: SessionSnapshot }
  | { type: "refused"; code: string; snapshot?: SessionSnapshot; recovering: boolean }
  | { type: "waiting"; txid: string }
  | { type: "ambiguous"; attemptedZat: string }
  | { type: "fatal"; code: string; message: string };

Fatal codes

The code of a fatal event is a refusal code, or one of four codes of the client's own:

Order of events

Refusal codes

A provider's refusal reaches the scheme as a code in settleResponse.errorReason or in paymentRequired.error, and the code carries the action. A refusal's snapshot is applied first, if it is this session's. recovered means the scheme returns { recovered: true }, and the stock wrapper then retries once with a new voucher. On the final attempt the scheme never waits and never deposits inline.

Where a step needs a txid or a snapshot and there is none, the scheme gives up on that call. Errors and reason codes lists the meaning of all 19 codes.

When the response to a paid request carries neither a PAYMENT-RESPONSE nor a PAYMENT-REQUIRED header, the outcome is unknown. The scheme moves the running total up to the attempted value, emits ambiguous, and does not recover. The next voucher then pays for that call too.

ZalletRpcWallet

class ZalletRpcWallet implements ZcashWallet {
  constructor(o: ZalletRpcWalletOptions);
  sendDeposit(req: DepositRequest): Promise<{ txid: string }>;
  findSentByMemo(memo: string): Promise<SentTransaction | undefined>;
  spendableBalance(): Promise<bigint>;
}

interface SentTransaction {
  txid: string;
  minedHeight: number | null; // null while it is in the mempool
  expired: boolean; // it expired before it was mined
}

It is a regtest wallet for an agent: it talks JSON-RPC 2.0 to Zallet with HTTP Basic credentials. It has no close method.

Wallet options

sendDeposit

It sends amountZat to to with memo as a text memo, and resolves with the txid. The request is one z_sendmany from the sending address, with these parameters: the recipient with its amount as a ZEC string and its memo as hex, a minimum of 1 confirmation, the default fee, and the FullPrivacy policy. One send runs at a time, and the lock is held from the request until its operation settles, so deposits to two providers never pick the same notes.

The lookup is what stops a window from being paid twice after an error.

Zallet methods it calls

findSentByMemo and spendableBalance

findSentByMemo(memo) returns the transaction in the account's list that has an output with exactly this memo, as text or as hex, or undefined. When several match, a pending one ranks above any mined one, a mined one ranks by its height, and an expired one ranks below every live one.

spendableBalance() returns the zat the account can spend: the orchard and ironwood pools with at least 1 confirmation. Transparent funds do not count, which keeps an immature coinbase out.

zatToZecString

function zatToZecString(zat: bigint): string;

An exact conversion with no floating point, trimmed of trailing zeros. A negative amount throws a RangeError.

LightwalletdTxStatus

class LightwalletdTxStatus implements TxStatusSource {
  constructor(lwd: LightwalletdLike);
  tip(): Promise<number>;
  status(txid: string): Promise<TxStatus>;
}

interface LightwalletdLike {
  getTip(): Promise<number>;
  getTransaction(txid: string): Promise<RawTx>;
}

type RawTx =
  | { found: false }
  | { found: true; raw: Uint8Array; location: "mempool" | "mined" | "orphaned"; height: number | null };

It adapts a lightwalletd client, for example the one from createLightwalletdClient in @z402-net/lightwalletd, to the TxStatusSource the scheme reads. It is typed against the two methods above, so the package depends on neither @z402-net/lightwalletd nor gRPC.

Every failure becomes a ChainUnavailableError, an outage as opposed to a definitive answer. That includes a raw transaction it cannot read. The scheme treats such an error as no answer: it neither counts nor resets a not-found streak.

Errors

The constructors are new DepositUncertainError(txid, { message?, cause? }), new ZalletRpcError(message, { code?, cause? }), new DepositStatusUnknownError(memo, { cause? }) and new InsufficientFundsError(message, { cause? }). Each sets name to its class name. When a payment cannot be built, the stock wrapper throws a plain Error whose message starts Failed to create payment payload:, with no cause. On its one recovery retry the wrapper does not wrap, so the original error (an InsufficientFundsError, or session halted by ...) is thrown as it is. Check the prefix and instanceof both. The deposit_failed event always carries the original error.

ZcashWallet and TxStatusSource

These are the two seams the scheme needs. They are defined in @z402-net/protocol, and @z402-net/client re-exports them, with DepositRequest, TxStatus and ChainUnavailableError: the very same objects, not copies. A wallet or a chain source of your own needs no other import:

import { ChainUnavailableError, type DepositRequest, type TxStatus, type TxStatusSource, type ZcashWallet } from "@z402-net/client";

interface DepositRequest {
  to: string; // the provider's payTo
  amountZat: bigint; // exactly one window
  memo: string; // "<sessionKey>:<index>", sent as a text memo
}

interface ZcashWallet {
  sendDeposit(req: DepositRequest): Promise<{ txid: string }>;
  close?(): Promise<void>;
}

type TxStatus =
  | { found: false }
  | { found: true; location: "mempool" | "mined" | "orphaned"; minedHeight: number | null; expiryHeight: number };

interface TxStatusSource {
  tip(): Promise<number>;
  status(txid: string): Promise<TxStatus>; // throws ChainUnavailableError on a transport error
}

A wallet must send exactly amountZat to to, shielded, with the memo as a text memo, and resolve with the txid in display order. It must not send twice for one memo. A chain source must throw ChainUnavailableError for any answer that is not definitive, and { found: false } only for a definitive not-found. The scheme treats a ChainUnavailableError as no answer: it neither counts nor resets a not-found streak.

Lower-level exports

These are the parts the scheme is built from. They are exported for tests and for people who write a scheme of their own, and an ordinary agent does not need them.

waitForConfirmation

interface WaitOptions {
  timeoutMs: number;
  pollMs: number; // must be above 0, or it throws a RangeError
  clock: Clock;
}

function waitForConfirmation(chain: TxStatusSource, txid: string, o: WaitOptions): Promise<"mined" | "dead" | "timeout">;

It polls chain.status(txid) every pollMs until the transaction is mined, dead or the time is up, with the last poll on the deadline. A transaction is dead when it is unmined and the tip has reached its expiry height, or when every definitive not-found answer since the first spans 120 seconds and 2 blocks. Any found answer resets that streak, and a ChainUnavailableError neither counts nor resets it.

Clock and systemClock

interface Clock {
  now(): number;
  sleep(ms: number): Promise<void>;
  setTimer(ms: number, fn: () => void): () => void; // returns the cancel function
}

const systemClock: Clock;

systemClock uses Date.now() and setTimeout. The timers from its setTimer are unreferenced, so a lone safety timer never keeps the process alive.

Mutex

class Mutex {
  acquire(): Promise<() => void>;
}

A first-in, first-out async lock. acquire() resolves with a release function that works only once.

Reading an outcome

type Outcome =
  | { kind: "paid"; snapshot?: SessionSnapshot; transaction: string }
  | { kind: "refused"; code: string; snapshot?: SessionSnapshot; via: "verify" | "settle" }
  | { kind: "ambiguous" };

type Action =
  | "wait_confirmation"
  | "deposit"
  | "resync"
  | "redeposit"
  | "check_deposit"
  | "backoff"
  | "reject_txid"
  | "fatal"
  | "stop";

function classifyOutcome(ctx: PaymentResponseContext): Outcome;
function actionFor(code: string, o: { isFinal: boolean; canDeposit: boolean }): Action;
function snapshotFromExtra(extra: unknown): SessionSnapshot | undefined;

classifyOutcome reads what a paid call came to. A settleResponse wins over a paymentRequired. A successful settle is paid. A failed one is refused with its errorReason (or unexpected_settle_error when it has none) and via: "settle". A paymentRequired is refused with its error (or unknown) and via: "verify", and its snapshot is the extra.session of the accepts entry that has the same scheme, network and payTo. With neither, the outcome is ambiguous.

actionFor maps a refusal code to what the scheme does. On a final attempt every action except reject_txid and fatal becomes stop, and canDeposit is false once maxDeposits is reached. The mapping is the table in Refusal codes.

snapshotFromExtra returns the validated extra.session of a verify or settle answer, or undefined.

Session

class Session {
  constructor(i: { payTo: string; network: string; seed: Uint8Array });
  readonly payTo: string;
  readonly network: string;
  readonly sessionKey: string;
  cumulative: bigint;
  snapshot?: SessionSnapshot;
  readonly deposits: LocalDeposit[];
  nextIndex: number;
  depositsMade: number;
  // methods below
}

Session is pure state: no I/O and no timers. The scheme holds one for each provider.

References

• packages/client/src/index.ts: the list of exports.
• packages/client/src/scheme.ts: PrepaidVoucherScheme, its options, the offer checks, the lock and the safety release.
• packages/client/src/respond.ts: what the scheme does with an outcome and with each refusal code.
• packages/client/src/outcome.ts: classifyOutcome, actionFor and snapshotFromExtra.
• packages/client/src/session.ts: Session, LocalDeposit and the deposit decision.
• packages/client/src/events.ts: ClientEvent.
• packages/client/src/wait.ts: waitForConfirmation and the dead rules.
• packages/client/src/wallet/zallet-rpc.ts: ZalletRpcWallet, its options, its Zallet calls and its recovery after an error.
• packages/client/src/chain/lightwalletd.ts: LightwalletdTxStatus.
• packages/client/src/errors.ts: the error classes.
• packages/client/src/clock.ts: Clock and systemClock.
• packages/client/src/mutex.ts: Mutex.
• packages/protocol/src/seams.ts: ZcashWallet, DepositRequest, TxStatus and TxStatusSource.
• packages/protocol/src/snapshot.ts: SessionSnapshot and its parser.
• packages/protocol/src/reasons.ts: the closed list of reason codes.
• docs/superpowers/specs/2026-10-27-z402-client-design.md: the client's design, including the outcome and recovery tables.
• docs/spec/protocol.md: the wire contract. Section 8 lists the codes and the client's actions, and section 9 the client rules.
• apps/agent/src/zcash.ts: how the demo agent builds the wallet, the chain reader and the scheme.
• x402 repository: x402Client, SchemeNetworkClient and the spend controls in @x402/core 2.28.0.
• Zallet: the wallet that ZalletRpcWallet talks to.