Express + React tutorial

This tutorial wires a minimal x402 paywall on the server and a client that handles non-payment responses. It assumes you already have a facilitator base URL that exposes POST /verify and POST /settle compatible with @tallypay/server (JSON bodies returning { valid } and { settled, txHash }).

Signing from the browser is application-specific (viem, wagmi, etc.). The React package will surface clear errors until you connect a real signer; the goal here is to show where pieces plug in.

1. Install

npm install express @tallypay/server

npm install react react-dom @tallypay/react @tallypay/core

2. Express: protect a route

import express from "express";
import { tallypay } from "@tallypay/server/express";

const app = express();

const paywall = tallypay({
  // Optional: tp_live_… from TallyPay — enables trace collection
  // apiKey: process.env.TALLYPAY_API_KEY,
  facilitatorUrl: process.env.FACILITATOR_URL!,
  payTo: process.env.MERCHANT_ADDRESS!,
  price: "10000", // smallest units — match your facilitator/network
  network: "eip155:8453",
  asset: "USDC",
  description: "Premium data",
});

app.use("/api/premium", paywall);

app.get("/api/premium", (_req, res) => {
  res.json({ message: "This response is only returned after a valid payment." });
});

app.listen(3000);

Unauthenticated calls to /api/premium receive 402 with payment-required and a JSON body. Calls that include a valid payment-signature header pass through to your handler after verify/settle.

3. React: provider and button

import { TallyPayProvider, PaymentButton } from "@tallypay/react";

export function App() {
  return (
    <TallyPayProvider
      network="eip155:8453"
      walletClient={walletClient}
      // apiKey="tp_live_…" // optional — client beacons for TallyPay dashboard
    >
      <PaymentButton url="http://localhost:3000/api/premium" />
    </TallyPayProvider>
  );
}

PaymentButton uses usePayment under the hood: it fetches the URL, handles 402, and will move through statuses until signing is implemented with your wallet stack.

4. Next steps

• Implement wallet signing for the payload your facilitator expects (see their x402 docs).
• Add apiKey on server and client to see correlated traces in the TallyPay dashboard (when the collector is enabled for your project).
• Read Debugging & pitfalls before going to production.