@z402-net/service-kit

@z402-net/service-kit builds a paid HTTP service from a list of routes. It wires the stock x402 Express middleware with the z402 scheme, checks the provider's API key and the facilitator's terms at start-up, lists the routes in the facilitator's Bazaar, and serves GET /health. The guide builds a service with it. This page lists every export, option, variable and limit.

npm install --save-exact @z402-net/service-kit
npm install --save-dev --save-exact @types/express@5.0.6

The package has no peer dependencies. It depends on @x402/core, @x402/express and @x402/extensions, all pinned to exactly 2.28.0, on express 5.3.0, and on @z402-net/protocol and @z402-net/server, so the one install brings them all. @types/express is for TypeScript, because the package's declarations name Express's types. The testing entry point is available inside the z402 repository only, and it also needs @x402/fetch, @z402-net/client, @z402/facilitator and @z402/testkit.

Entry points

createPaidService

function createPaidService(o: PaidServiceOptions): Promise<PaidService>;

Checks the definition and the settings, loads the facilitator's terms, and returns the Express app with /health and the payment middleware mounted. Nothing listens yet: the app is the caller's to serve and to add handlers to.

PaidServiceOptions

interface PaidServiceOptions {
  env: ServiceEnv;
  service: ServiceDefinition;
  ready?: () => boolean | Promise<boolean>;
  before?: RequestHandler[];
  facilitatorWaitMs?: number;
  declareIntervalMs?: number;
  log?: (message: string) => void;
}

PaidService

interface PaidService {
  app: Express;
  stats: CallStats;
  http: x402HTTPResourceServer;
  close(): Promise<void>;
}

Start-up order

Everything below runs before createPaidService returns, so before anything listens. Every failure names the setting at fault.

1. The definition and the public URL. The service definition and PUBLIC_URL are checked. See the errors.
2. The key. checkProvider calls GET /providers/me with a 5 s timeout and proves that the API key and Z402_PAY_TO belong together.
3. The terms. The kit reads GET /supported with a 5 s timeout and lets the x402 server load the rail's terms. A facilitator that offers no prepaid-voucher on the network, or terms the scheme cannot use, fails here.
4. The wait. Steps 2 and 3 repeat every 2 s while the failure may be temporary (a facilitator that is starting, unreachable or slow), until facilitatorWaitMs has passed. The first retry logs <message>; waiting for it. A refused key, another address, another network or a service that is not a facilitator fails at once.
5. The prices. Every route's price must be from 1 to the terms' windowZat.
6. The items. The kit builds each route's catalog item once, from the 402 of an unpaid request to it, and checks its size.
7. The app. The middleware is mounted, and the declaration heartbeat starts unless declareIntervalMs is 0.

Requests the app handles

In the order they run for a request:

1. The path is made canonical. A spelling that the payment middleware treats as a paid path but Express would not route (//v1/notes, a percent-encoded letter, a trailing slash) is rewritten to the route's one spelling. No spelling skips a route's checks or its payment.
2. GET /health answers at once. See GET /health.
3. The counter notes each response that is a 2xx and carries PAYMENT-RESPONSE.
4. Your before handlers run.
5. Each paid route's gate. A method the route does not take gets 405 with Allow, and {"error":"method_not_allowed"}. A GET route also takes HEAD. A service that is not ready gets 503 and {"error":"not_ready"}.
6. The route's prepare handlers run in order, unless the request is a probe.
7. The payment middleware answers 402, or verifies the voucher, runs your handler and settles. If the routes and the middleware disagree about whether a path is paid, the kit answers 404 and {"error":"not_found"}. A second request that carries a voucher that is already being verified or handled gets 409 and {"error":"payment_in_flight"}. One payment therefore runs your handler once.

A probe is a request with the X-Z402-Probe header and no PAYMENT-SIGNATURE or X-PAYMENT header. It skips prepare, so a placeholder id or an empty body is not refused, and it gets the route's 402. It is for tools that want a route's offer, and paymentRequiredOf in the testing helpers sends one. A request that carries a payment never skips prepare.

The facilitator client the kit builds sends the API key as a bearer token on verify, settle and supported. It allows 60 s for verify and settle, which covers the facilitator's 30 s wait for a deposit it has not seen yet, and 5 s for supported.

Every 402 carries one accepts entry for the route:

{
  "scheme": "prepaid-voucher",
  "network": "zcash:regtest",
  "amount": "100",
  "asset": "ZEC",
  "payTo": "uregtest1...",
  "maxTimeoutSeconds": 60,
  "extra": { "windowZat": "100000", "creditRatioBps": 2500, "creditCapZat": "200000", "zeroConfMinExpiryBlocks": 20, "termsVersion": "<16 hex characters>" }
}

Its resource is PUBLIC_URL and the route's path. The extensions are the route's bazaar extension and a z402 extension, { "unit": "...", "note": "..." }.

ServiceDefinition

interface ServiceDefinition {
  serviceName: string;
  tags?: string[];
  routes: PaidRoute[];
}

PaidRoute

type PaidMethod = "GET" | "POST" | "PUT" | "DELETE";

interface PaidRoute {
  method: PaidMethod;
  path: string;
  probePath?: string;
  description: string;
  unit: string;
  note?: string;
  mimeType?: string;
  priceZat?: bigint;
  discovery: DeclareDiscoveryExtensionInput;
  prepare?: RequestHandler[];
}

A refusal in prepare reaches the client on its unpaid first attempt, before any voucher exists. A failure after the voucher is sent is ambiguous to the client, which counts the call and pays for it with its next voucher. So every check that can run in prepare must.

Discovery config

discovery is the input of declareDiscoveryExtension from @x402/extensions/bazaar, without method, which the kit fills in from the route. It describes the route for agents, and it becomes the bazaar extension of the route's 402 and of its listing.

A route that reads a query string:

const search: PaidRoute = {
  method: "GET",
  path: "/v1/search",
  description: "Searches the index and returns the number of hits.",
  unit: "search",
  discovery: {
    input: { q: "zcash" },
    inputSchema: { properties: { q: { type: "string" } }, required: ["q"] },
    output: { example: { hits: 3 } },
  },
};

A route that takes a JSON body has bodyType: "json" and a body in input. A route with parameters adds pathParams. The guide's example has both.

Constants

const Z402_EXTENSION = "z402";
const PROBE_HEADER = "x-z402-probe";

Z402_EXTENSION is the key of the extension that rides next to bazaar in every 402: { unit, note? }. PROBE_HEADER is the header of a probe.

GET /health

{
  "ok": true,
  "service": "Short notes",
  "ready": true,
  "network": "zcash:regtest",
  "priceZat": "100",
  "callsToday": 0,
  "routes": [
    { "method": "POST", "path": "/v1/notes", "unit": "note-hour", "priceZat": "100" },
    {
      "method": "POST",
      "path": "/v1/notes/:id/extend",
      "probePath": "/v1/notes/example/extend",
      "unit": "note-hour",
      "priceZat": "100"
    }
  ]
}

The Bazaar declaration

While the service is ready, the kit lists its routes in the facilitator's Bazaar with POST /discovery/resources. The facilitator's Bazaar rules decide what it accepts.

What it sends. Each item is built once at start from the 402 of an unpaid request to the route, so the catalog offers exactly what the route asks for: resource (PUBLIC_URL plus the route's path), type: "http", x402Version, accepts, description, mimeType, serviceName, tags and extensions (bazaar, with the method and, for a route with parameters, its routeTemplate, and z402). The request carries content-type: application/json and authorization: Bearer <key>. It is not redirected.

When. At once when the service is ready, then declareIntervalMs after each declaration ends, so two never overlap. Each request has 10 s. A service that is not ready asks again after 5 s or the interval, whichever is shorter, so that its first declaration follows soon after it is ready. A beat that is due never keeps the process alive.

How. The items go in order, 32 items and 60 KiB at most per request, one request at a time.

What it logs. One line each time the outcome changes, on log (stderr by default), never the key:

A failed declaration never stops the service.

loadServiceEnv

function loadServiceEnv(env: Env, o: { port: number; priceZat: bigint }): ServiceEnv;

Reads and checks the variables every paid service shares, and throws a ConfigError that names the one at fault. o.port is the service's own port and o.priceZat its default price for one call. An empty variable counts as unset.

A _FILE variable that points at a file that cannot be read throws <NAME>_FILE: cannot read <path> (<code>), and one that points at an empty file throws <NAME>_FILE: <path> is empty.

ServiceEnv

interface ServiceEnv {
  network: ZcashNetwork;
  facilitatorUrl: string;
  facilitatorToken: string | undefined;
  payTo: string;
  priceZat: bigint;
  publicUrl: string;
  host: string;
  port: number;
  facilitatorWaitMs?: number;
  declareIntervalMs?: number;
}

Reading settings

Your own settings use the same helpers.

type Env = Record<string, string | undefined>;

function read(env: Env, name: string): string | undefined;
function readOrFile(env: Env, name: string): string | undefined;
function readInt(env: Env, name: string, fallback: number, min?: number, max?: number): number;
function readUrl(env: Env, name: string, fallback?: string): string;

class ConfigError extends Error {}
function loadDotEnv(file: URL): void;

loadDotEnv(new URL("../.env", import.meta.url)) in a service's src/main.ts reads services/<name>/.env.

onDelivered

interface DeliveryHandlers {
  ok?: () => void;
  failed?: () => void;
}

function onDelivered(res: Response, h: DeliveryHandlers): void;

Runs exactly one of the handlers, once, when the response is over. The x402 middleware settles after your handler and turns a refused settlement into a 402, so a 2xx at the end is the only sign that the call was paid and delivered.

A handler that throws is logged as delivery handler failed and does not stop the other work. A response that is already over when you call onDelivered runs its handler at once.

serve and runMain

interface Listening {
  url: string;
  server: Server;
  close(): Promise<void>;
}

function serve(app: Express, o: { host: string; port: number }): Promise<Listening>;

function runMain(
  name: string,
  start: () => Promise<{ readyLine: string; close(): Promise<void> }>,
): void;

serve listens on host and port, where port 0 picks a free one. url is http://<host>:<port>, with an IPv6 host in brackets. It allows 15 s for a request's headers and 30 s for the whole request, instead of Node's 5 minutes, so one slow client cannot hold a buffered body before payment. close() stops listening, closes idle connections at once and the others as their calls end. A failure to listen rejects with PORT: cannot listen on <host>:<port> (<code>) for EADDRINUSE and EACCES, and HOST: ... for any other.

runMain is the process wrapper every service main uses. When start resolves it prints <name> <readyLine> on stdout. Logs and errors go to stderr. A failure in start prints <name>: <message> and exits 1. SIGINT or SIGTERM calls close() and exits 0, or exits 1 if the close fails or takes more than 5 s. A second signal gets the default and ends the process at once.

CallStats

class CallStats {
  constructor(now?: () => Date);
  record(): void;
  today(): number;
}

Counts paid calls delivered since 00:00 UTC. It keeps an aggregate only: nothing per session or per client. The kit calls record() for each response that is a 2xx and carries PAYMENT-RESPONSE, so only a settled, delivered call counts. today() starts at 0 each UTC day. now replaces the clock, for tests.

The testing entry point

@z402-net/service-kit/testing starts an in-process stack for service tests. It is available inside the z402 repository only. It runs the repository's own facilitator and fake chain, @z402/facilitator and @z402/testkit, which are not published, so the package leaves this entry point out when it is published. A call made with paidFetch is a real paid call: a deposit, a voucher, verification, your handler and settlement. It needs no Docker and no network.

startTestStack

function startTestStack(o: TestStackOptions): Promise<TestStack>;

It starts, in order:

1. A FakeChain with an expiry delta of 40 blocks.
2. The real facilitator on an in-memory ledger, polling every 50 ms, with the demo terms and the token TEST_TOKEN, paid at TEST_PAY_TO.
3. With catalog, a stub Bazaar in front of the facilitator.
4. Your service, built by build(env), on 127.0.0.1 and a free port.
5. A paying client: PrepaidVoucherScheme with a MockWallet, in the stock x402 fetch wrapper.

If a later step fails, it closes what already started.

TestStackOptions

interface TestStackOptions {
  build: (env: ServiceEnv) => Promise<Built>;
  priceZat?: bigint;
  env?: Partial<ServiceEnv>;
  catalog?: boolean;
}

type Built = Express | { app: Express; close?(): Promise<void> };

The env that build receives is: network TEST_NETWORK, facilitatorUrl the stack's facilitator (or the stub, with catalog), facilitatorToken TEST_TOKEN, payTo TEST_PAY_TO, priceZat, publicUrl TEST_PUBLIC_URL, host 127.0.0.1, port 0, declareIntervalMs 0 unless the stack has a catalog, and your overrides on top. The 402s therefore name http://service.test as their resource, while the service listens at stack.url.

TestStack

interface PayingClient {
  paidFetch: typeof fetch;
  scheme: PrepaidVoucherScheme;
}

interface TestStack extends PayingClient {
  chain: FakeChain;
  facilitator: FacilitatorHandle;
  url: string;
  env: ServiceEnv;
  catalog?: CatalogStub;
  client(): PayingClient;
  close(): Promise<void>;
}

The catalog stub

With catalog, the service declares to a stub that records each declaration. It answers POST /discovery/resources itself and passes every other request to the facilitator.

interface CatalogStub {
  readonly declarations: Declaration[];
  readonly mostAtOnce: number;
  delayMs: number;
  answer(how: number | "drop", body?: unknown): void;
}

interface Declaration {
  authorization: string | undefined;
  body: unknown;
  bytes: number;
  at: number;
}

Test helpers

function paymentRequiredOf(url: string, method: string): Promise<PaymentRequired>;

interface Rail {
  network: string;
  payTo: string;
  extra: Record<string, unknown>;
}

function railOf(stack: TestStack): Promise<Rail>;
function declarationRefusal(d: Declaration, rail: Rail): string | undefined;

const TEST_NETWORK: ZcashNetwork; // zcash:regtest
const TEST_PAY_TO: string; // uregtest1 and 60 times q
const TEST_TOKEN: string;
const TEST_PUBLIC_URL: string; // http://service.test

• paymentRequiredOf(url, method) sends a probe, so that no check of the route refuses it first, and returns the decoded 402. It throws when the answer is not a 402 with a PAYMENT-REQUIRED header.
• railOf(stack) reads the facilitator's /supported for the stack's own payTo and returns the rail a declared item must name: the network, the address, and the extra that holds the terms and termsVersion.
• declarationRefusal(d, rail) says why the facilitator's catalog would refuse a declaration, or returns undefined when it would take every item. It is written from the design of the catalog and not from the kit, so it checks what the kit sends. It checks that:
  • the body is at most 64 KB and holds 1 to 32 items;
  • an item has no field beyond resource, type, x402Version, accepts, description, mimeType, serviceName, tags, iconUrl and extensions;
  • resource is an absolute http(s) URL of at most 2,048 characters with no user or password, type is http and x402Version is 2;
  • accepts holds 1 to 4 entries, each prepaid-voucher on the rail's network, asset ZEC, the rail's payTo, an amount from 1 to windowZat, and the rail's terms and termsVersion;
  • description is at most 512 characters, mimeType at most 128, serviceName 1 to 32 printable ASCII characters, and tags at most 5, each 1 to 32 printable ASCII characters (the stub also refuses a repeat that differs only in case, where the real catalog drops it and takes the item);
  • extensions is an object of at most 8 KB, and extensions.bazaar.info.input.method, when present, is one of GET, POST, PUT, PATCH, DELETE or HEAD.

Limits and timings

Start-up errors

createPaidService and loadServiceEnv fail with a message that names the variable, option or route at fault. runMain prints it as <name>: <message> and exits 1.

References

• packages/service-kit/src/index.ts: the exports of the main entry point.
• packages/service-kit/src/service.ts: createPaidService, the route and service types, the start-up order and the refusals.
• packages/service-kit/src/declare.ts: the declaration heartbeat, the item limits and the log lines.
• packages/service-kit/src/env.ts: loadServiceEnv, ServiceEnv, the readers and ConfigError.
• packages/service-kit/src/dotenv.ts: loadDotEnv.
• packages/service-kit/src/delivery.ts: onDelivered.
• packages/service-kit/src/run.ts: serve and runMain.
• packages/service-kit/src/stats.ts: CallStats.
• packages/service-kit/src/testing.ts: the test stack, the catalog stub and declarationRefusal.
• packages/server/src/provider.ts: checkProvider, which the start-up calls.
• services/embeddings/src/service.ts, services/dropbox/src/service.ts, services/llm/src/service.ts and services/markdown/src/service.ts: the four services built with the kit.
• docs/superpowers/specs/2026-10-27-z402-services-design.md: section 3, the kit's design.
• docs/superpowers/specs/2026-10-28-z402-multi-provider-design.md: sections 4.4 and 4.6, the Bazaar and the provider check.
• x402: the SDK the kit wires, and the Bazaar extension.