@frontiercompute/x402-zec

x402 facilitator for Zcash shielded payments.

x402 is the HTTP payment protocol from the Linux Foundation. When an agent hits a paid endpoint, the server returns HTTP 402 with payment requirements. The agent pays, includes proof in the header, retries. Standard flow.

This package replaces USDC on Base/Solana with shielded ZEC. Every payment is verified on-chain and attested to Zcash via ZAP1.

Privacy by default. No transparent addresses, no on-chain link between payer and API.

Install

npm install @frontiercompute/x402-zec

Server (middleware)

Works with Express or any framework that uses (req, res, next) middleware.

import express from "express";
import { x402ZecMiddleware } from "@frontiercompute/x402-zec";

const app = express();

app.use(
  "/api/premium",
  x402ZecMiddleware({
    address: "u1...", // your shielded payment address
    amount: 1000, // zatoshis per request
    zap1ApiUrl: "https://pay.frontiercompute.io",
    zap1ApiKey: process.env.ZAP1_API_KEY!,
  })
);

app.get("/api/premium/data", (req, res) => {
  res.json({ result: "paid content" });
});

app.listen(3000);

When no payment proof is present, the middleware returns 402:

{
  "protocol": "x402-zec",
  "address": "u1...",
  "amount": 1000,
  "memo": "ZAP1:05:x402:abc123...",
  "paymentUri": "zcash:u1...?amount=0.00001000&memo=...",
  "paymentId": "abc123..."
}

Client

Wraps fetch() with automatic 402 handling.

import { createX402Client } from "@frontiercompute/x402-zec";

const client = createX402Client({
  onPaymentRequired: async (req) => {
    // Your wallet integration here.
    // Pay req.amount zatoshis to req.address with req.memo.
    // Return the proof after broadcast.
    const txid = await myWallet.send(req.address, req.amount, req.memo);
    return {
      txid,
      memo: req.memo,
      address: req.address,
      amount: req.amount,
    };
  },
});

const res = await client.fetch("https://api.example.com/api/premium/data");
const data = await res.json();

Payment proof

Sent as X-Payment-Proof header:

{
  "txid": "abc...",
  "memo": "ZAP1:05:x402:...",
  "address": "u1...",
  "amount": 1000
}

Verification

Payments are verified in two ways:

1. Zebra RPC - if zebraRpcUrl is set, checks getrawtransaction directly
2. ZAP1 API - falls back to /verify/{memo_hex}/check

Attestation

Every verified payment is attested to Zcash via ZAP1 as a HOSTING_PAYMENT event. The response includes X-ZAP1-Leaf header with the Merkle leaf hash.

Set skipAttest: true in config to disable.

Config

interface FacilitatorConfig {
  address: string; // shielded payment address
  amount: number; // zatoshis per request
  zap1ApiUrl: string; // ZAP1 API base URL
  zap1ApiKey: string; // ZAP1 API key
  zebraRpcUrl?: string; // Zebra RPC for direct verification
  memoPrefix?: string; // custom memo prefix (default: "x402")
  skipAttest?: boolean; // skip ZAP1 attestation (default: false)
}

License

MIT