@shulam/sdk

The official SDK for the Shulam x402 payment facilitator. Compliance screening, trust scoring, agent passports, and payment settlement — one package.

Install

npm install @shulam/sdk

Quick Start — Paywall an Express Endpoint

import express from "express";
import { requirePayment } from "@shulam/sdk/express";

const app = express();

// One line to paywall any route
app.get("/premium",
  requirePayment({ amount: "1000000", payTo: "0xYourWallet" }),
  (req, res) => {
    res.json({ content: "premium data", paidBy: req.payment?.payer });
  }
);

app.listen(8080);

Set SHULAM_API_KEY in your environment (or pass apiKey in the config).

Full SDK Client

For compliance screening, trust scoring, agent passports, and more:

import { Shulam } from "@shulam/sdk";

const shulam = new Shulam({ apiKey: process.env.SHULAM_API_KEY! });

// OFAC compliance screening
const screen = await shulam.compliance.screen("0xAddress...");
console.log(screen.status); // "clear" | "held" | "blocked"

// Trust scoring
const trust = await shulam.trust.getScore("0xAddress...");
console.log(trust.tier); // "unknown" | "new" | "established" | "trusted" | "exemplary"

// Agent Passport
const passport = await shulam.passport.get("0xAddress...");

// Merchant discovery
const merchants = await shulam.discovery.searchCompliant({ category: "api" });

// Manual verify + settle
const verified = await shulam.payments.verify(paymentPayload, requirements);
const settled = await shulam.payments.settle(paymentPayload, requirements);

Subpath Imports

| Import | Purpose | |--------|---------| | @shulam/sdk | Full SDK client (Shulam class) | | @shulam/sdk/express | requirePayment() Express middleware | | @shulam/sdk/compliance | Compliance screening only | | @shulam/sdk/trust | Trust scoring only | | @shulam/sdk/passport | Agent Passport API | | @shulam/sdk/discovery | Merchant discovery |

Configuration

const shulam = new Shulam({
  apiKey: "sk_test_...",               // Required
  baseUrl: "https://api.shulam.io",    // Optional (default)
  timeout: 10_000,                     // Optional, ms
  retry: { maxRetries: 2, baseDelay: 500 }, // Optional
});

Environment Variables

| Variable | Purpose | Default | |----------|---------|---------| | SHULAM_API_KEY | API key for requirePayment() | — | | SHULAM_FACILITATOR_URL | Facilitator base URL | https://api.shulam.io |

Error Handling

import { ApiError, ComplianceHoldError, RateLimitError, NetworkError } from "@shulam/sdk";

try {
  await shulam.compliance.screen("0x...");
} catch (err) {
  if (err instanceof ComplianceHoldError) {
    console.log("Address held for review:", err.holdId);
  } else if (err instanceof RateLimitError) {
    console.log("Rate limited, retry after:", err.retryAfterMs, "ms");
  } else if (err instanceof NetworkError) {
    console.log("Network error:", err.message);
  } else if (err instanceof ApiError) {
    console.log("API error:", err.status, err.code);
  }
}

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.

License

MIT — Shulam, Inc.