npm package: @shulam/x402
Description: @shulam/x402 — x402 payment SDK: server middleware, auto-pay client, compliance receipts, dynamic pricing
Author: Shulam, Inc.
Latest version: 0.1.0

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

```bash
npm install @shulam/x402
```

## Quick Start — Paywall an Express Endpoint (Server)

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

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

```typescript
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](https://docs.shulam.io).

## License

MIT — Shulam, Inc.