Docs · z402

z402 is a way for software to pay for API calls in shielded Zcash. An AI agent asks for something, the API answers with a price, the agent pays, and the call goes through. The agent needs no account, no card and no sign-up with the provider, and its payments leave no public trail.

It builds on x402, which puts payment into plain HTTP. z402 adds one payment scheme, prepaid-voucher, that fits Zcash. Agents use the stock x402 client plus one line of code.

The problem

Software that buys from APIs runs into three walls:

Accounts and cards. A person has to sign up, add a card and paste an API key into the agent. An agent cannot do that for itself, and every new provider means a new account.
One transaction per call. Paying on a blockchain for each call is slow, because a Zcash block takes from 25 to 75 seconds. It is also expensive: the fee of one transaction (about 10,000 zat) can be larger than the price of a call (500 zat on the demo API).
A public trail. On a transparent chain every payment shows who paid whom and how much, so anyone can read what an agent is doing.

z402 answers all three. The agent pays with a wallet it controls. One transaction covers many calls (200 at the demo price), and that transaction is shielded.

How it works in four steps

The API names its price. A call without payment gets 402 Payment Required. The answer says what one call costs, where to pay and how much to deposit at a time.
The agent deposits once. It sends one shielded payment to the provider's address: 100,000 zat in the demo, enough for 200 calls at 500 zat. A short memo inside the payment names the agent's session key.
Each call carries a voucher. A voucher is a signed running total, such as "I have used 1,500 zat so far". The agent signs it and sends it with the request. No transaction is needed per call.
The provider checks and serves. The facilitator checks the signature, the deposit and the total, and the API answers. The first call is served before the deposit confirms. As deposits confirm, the limit grows, and the agent sends its next deposit before the money runs out.

An agent pays two providers

What it costs on the demo terms

	Value
Price of one call	500 zat (0.000005 ZEC) on the demo API. Each provider sets its own price per route.
One deposit, the window	100,000 zat (0.001 ZEC), which is 200 calls at 500 zat
Network fee of a deposit	about 10,000 zat
Credit on confirmed deposits	25 percent of them, up to 200,000 zat
Starter services	100 to 1,000 zat per call

A zat is one hundred millionth of a ZEC. The window and the credit are set by the facilitator and are the same for every provider on it.

Who it is for

Agents and their builders

Your agent is the stock x402 client plus one line that registers the Zcash scheme. @z402-net/client makes the deposits, signs the vouchers and recovers when a call is refused.

import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { zcashClientScheme } from "./zcash.js";

const client = new x402Client();
client.register("zcash:regtest", zcashClientScheme); // the one line that adds Zcash
const paidFetch = wrapFetchWithPayment(fetch, client);

const res = await paidFetch("http://localhost:4021/chunk");
console.log(res.status, await res.json());

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

// The endpoints and credentials of the local regtest stack
const lwd = createLightwalletdClient({ url: "http://127.0.0.1:28137" });

export const zcashClientScheme = new PrepaidVoucherScheme({
  wallet: new ZalletRpcWallet({ url: "http://127.0.0.1:50232", user: "zebra", password: "zebra" }),
  chain: new LightwalletdTxStatus(lwd),
});

Pay from an agent

Wire the scheme into your own agent, step by step.

@z402-net/client

Options, events and errors of the client library.

API providers

Put the x402 middleware in front of any route, set a price and a payTo address, and register with a facilitator once to get an API key. You never run payment infrastructure. @z402-net/service-kit builds a whole paid service from data: its routes, their prices and the checks that run before payment.

Sell an API

Charge for a route in a few lines.

Build with the service kit

Describe a paid service as data and let the kit wire it.

Starter services

Four paid services you can run and read.

Operators

The operator runs the facilitator. It verifies vouchers, finds and reads deposits with each provider's view-only key, keeps the ledger and hosts the public catalog of paid APIs. One Docker Compose file starts the whole stack on a private chain.

Run the facilitator

Configure it, register providers, and read its logs.

Deploy with Docker

The one-server deployment, ports and volumes.

Where z402 runs today

Start here

Quickstart

Start the stack and pay every starter service.

How it works

One call from the 402 to the next call, with the numbers.

FAQ

Money, privacy and limits, answered briefly.

References

docs/spec/protocol.md: the wire contract between the client and the merchant side, including the demo terms (section 12).
docs/superpowers/specs/2026-10-28-z402-multi-provider-design.md: the facilitator as one rail for many providers.
docs/deploy.md: the Docker Compose deployment and the regtest limit ("Beyond regtest").
docs/research/live-run.md: the fees and timings measured on the regtest stack.
packages/client/src/scheme.ts: PrepaidVoucherScheme, the client scheme.
apps/agent/src/agent.ts: the demo agent, stock x402 plus one register line.
x402: the open standard and its SDK. z402 pins version 2.28.0.
RFC 9110, 402 Payment Required: the HTTP status code.