@shulam/x402

The x402 payment SDK for the Shulam facilitator. Server middleware, auto-pay client, React hooks, compliance receipts, and dynamic pricing — all in one package.

Install

npm install @shulam/x402

Quick Start — Paywall an Express Endpoint (Server)

import express from "express";
import { createShulamServer } from "@shulam/x402/server";

const app = express();

const paywall = createShulamServer({
  facilitatorUrl: "https://api.shulam.io",
  sellerAddress: "0xYourWalletAddress",
  apiKey: process.env.SHULAM_API_KEY!,
  endpoints: {
    "GET /api/premium": { price: "0.001", description: "Premium content" },
  },
});

app.use(paywall);

app.get("/api/premium", (req, res) => {
  res.json({ content: "premium data", paidBy: req.payment?.payer });
});

app.listen(8080);

Auto-Pay Client (Browser / Node)

import { createShulamClient } from "@shulam/x402/client";

const client = createShulamClient({
  facilitatorUrl: "https://api.shulam.io",
  signer: yourSignerAdapter,
  walletAddress: "0xYourWallet",
  maxPaymentUSDC: "1.00",
  maxDailyUSDC: "10.00",
});

// Automatically handles 402 responses — signs and pays
const response = await client.fetch("https://api.example.com/premium");
const data = await response.json();

React Hook

import { useShulamPayment } from "@shulam/x402/react";

function PremiumContent() {
  const { pay, paying, lastReceipt, error, dailySpending } = useShulamPayment({
    facilitatorUrl: "https://api.shulam.io",
    signer: adapter,
    walletAddress: "0x...",
    maxDailyUSDC: "10.00",
  });

  return (
    <button onClick={() => pay("https://api.example.com/premium")} disabled={paying}>
      {paying ? "Paying..." : "Access Premium"}
    </button>
  );
}

Subpath Imports

| Import | Purpose | |--------|---------| | @shulam/x402 | Core exports, types, signer adapters | | @shulam/x402/server | createShulamServer() Express middleware | | @shulam/x402/client | createShulamClient() auto-pay fetch client | | @shulam/x402/react | useShulamPayment() React hook | | @shulam/x402/compliance | Compliance receipt parsing + validation | | @shulam/x402/pricing | Dynamic pricing utilities | | @shulam/x402/types | TypeScript type definitions | | @shulam/x402/chains | Chain configuration (Base, Base Sepolia) |

Compliance Headers

Every settled payment includes compliance headers on the response:

| Header | Description | |--------|-------------| | X-Shulam-Compliance-Receipt | Base64url-encoded compliance receipt | | X-Shulam-Trust-Score | Payer's trust score (0–100) | | X-Shulam-Trust-Tier | Payer's trust tier (unknown | new | established | trusted | exemplary) | | X-Shulam-Audit-Hash | SHA-256 hash of the audit trail entry |

What is x402?

x402 is an open protocol for machine-to-machine payments using HTTP status code 402. When a client requests a paid resource without payment, the server returns 402 Payment Required with payment instructions. The client signs a USDC authorization (EIP-3009), attaches it as an X-Payment header, and retries. The facilitator verifies compliance and settles on-chain.

Documentation

Full documentation at docs.shulam.io.

License

MIT — Shulam, Inc.