@zentpay/x402-pay

ZentPay is a small x402 payment SDK for turning an existing HTTP route into a paid route. The shortest path is: install the package, protect one route, keep your existing login/order system, and read the settled payment from res.locals.zentpayPayment.

You do not need to clone this repository, run the SDK test suite, export the 7days demo, or deploy your own Worker just to integrate ZentPay. Those flows are for SDK maintainers, demo validation, or advanced facilitator operations.

5 Minute Express Quickstart

npm install @zentpay/x402-pay express

import express from "express";
import { zentpayExpress, type PaymentSettledEvent } from "@zentpay/x402-pay/server";

const app = express();
app.use(express.json());

// Keep your own auth/order checks before payment when possible.
app.use((_req, res, next) => {
  res.locals.userId = "demo-user";
  next();
});

app.use(zentpayExpress({
  payTo: process.env.PAY_TO_ADDRESS!,
  facilitatorUrl: process.env.FACILITATOR_URL || "https://zentpay.app/facilitator",
  items: [
    {
      id: "sword",
      path: "/api/pay/sword",
      price: "$0.10",
      description: "Buy sword",
    },
  ],
  onSettled: async (event) => {
    // Best-effort audit hook only. Do not put required fulfillment here.
    console.log("settled", event.itemId, event.txHash);
  },
}));

app.post("/api/pay/sword", async (_req, res) => {
  const payment = res.locals.zentpayPayment as PaymentSettledEvent;

  // Fulfill with your own business user/order model here.
  res.json({
    success: true,
    userId: res.locals.userId,
    itemId: payment.itemId,
    txHash: payment.txHash,
  });
});

app.listen(3000);

That is the M0 integration. zentpayExpress() handles the x402 402 -> verify -> settle path; your app still owns authentication, order locking, inventory, and idempotent fulfillment.

Browser Payment Session

If your frontend already has an EVM signer, use the client helper to retry a paid route after receiving the x402 challenge:

npm install @zentpay/x402-pay @coinbase/wallet-sdk

import { createQuickSession } from "@zentpay/x402-pay/client";

const session = createQuickSession(signer);

const response = await session.purchase("https://api.example.com/api/pay/sword", {
	method: "POST",
	headers: {
		"Content-Type": "application/json",
		Authorization: `Bearer ${gameSessionToken}`,
	},
	body: JSON.stringify({ orderId: "order-123" }),
});

createQuickSession() and createPaymentSession() default to Base Sepolia exact payments. Pass enableUpto: true only when you are ready to expose Permit2 / upto flows.

For games and H5 apps, keep the main flow to one wallet confirmation: create the order on click, lock the button, start purchase(), then poll your order until it is fulfilled or marked pending. See docs/sdk-game-h5-integration.md.

If you use the Privy embedded wallet adapter, also add:

npm install @privy-io/js-sdk-core

Non-Node Backends

For Go, Nakama, Java, or another non-Node backend, keep x402 in a small Node/Express payment microservice and call your main backend after settlement. The main backend should own business auth, catalog checks, idempotency, inventory, and retry recovery.

Use createNakamaFulfillmentClient() when your main backend is Nakama. It signs and sends the fulfillment callback; it does not replace your durable outbox or Nakama-side idempotency table.

Optional Worker

Self-hosting the facilitator Worker is optional. Use the hosted endpoint first:

https://zentpay.app/facilitator

Deploy your own @zentpay/x402-pay/worker only when you need custom upstream routing, recovery normalization, ledger queries, fee policy, or operating controls.

The hosted Worker handles facilitator CORS preflight for H5 clients, but your own payment-service still needs to expose x402 payment headers to the browser.

Runtime Dependencies

• @x402/core, @x402/evm, @x402/fetch, and viem are normal runtime dependencies and install automatically.
• @coinbase/wallet-sdk and @privy-io/js-sdk-core are optional peer dependencies for browser wallet adapter subpaths only.
• Server-side payment collection does not require installing browser wallet SDKs.

Wallet adapter imports are split so exact-only client usage does not load optional peers:

import { createInjectedWalletAdapter } from "@zentpay/x402-pay/wallet";
import { createCoinbaseSmartWalletAdapter } from "@zentpay/x402-pay/wallet/coinbase";
import { createPrivyEmbeddedWalletAdapter } from "@zentpay/x402-pay/wallet/privy";

More Docs

• External integration guide: docs/sdk-developer-integration.md
• Game / H5 integration guide: docs/sdk-game-h5-integration.md
• Nakama fulfillment contract: docs/sdk-nakama-integration.md
• Internal ops and Worker maintenance: docs/sdk-ops-maintenance.md
• Minimal Express example: examples/express-minimal