npm package: @frontiercompute/x402-zec
Description: x402 facilitator for Zcash shielded payments
Author: Zk-nd3r
Latest version: 0.1.0

# @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

```bash
npm install @frontiercompute/x402-zec
```

## Server (middleware)

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

```typescript
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:

```json
{
  "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.

```typescript
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:

```json
{
  "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

```typescript
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