npm package: @shulam/sdk
Description: Shulam SDK — compliance screening, trust scoring, and x402 payment facilitation
Author: Shulam, Inc.
Latest version: 0.1.0

# @shulam/sdk

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

## Install

```bash
npm install @shulam/sdk
```

## Quick Start — Paywall an Express Endpoint

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

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

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

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