@circuit-llm/x402 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Circuit LLM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,34 @@
+# @circuit-llm/x402
+
+> The payment spine of the Circuit network: pay any x402-gated endpoint in CIRC (client) and verify on-chain CIRC payments (server). **Zero runtime dependencies.**
+
+Part of the **[Circuit SDK](https://github.com/Circuit-LLM/circuit-sdk)** — every paid call in the ecosystem (inference, data) runs on this. [Full guide →](https://github.com/Circuit-LLM/circuit-sdk/blob/main/docs/x402.md)
+
+## Install
+
+```bash
+npm install @circuit-llm/x402
+```
+
+## Pay (client)
+
+```ts
+import { X402Client } from '@circuit-llm/x402';
+
+const client = new X402Client({ wallet });   // wallet: a PaymentWallet — see @circuit-llm/wallet
+const res = await client.fetch('https://gateway.circuitllm.xyz/v1/chat/completions', {
+  method: 'POST',
+  body: JSON.stringify({ messages: [{ role: 'user', content: 'hi' }] }),
+});
+// On HTTP 402 it reads the CIRC price, pays on-chain, and retries with the tx signature — transparently.
+```
+
+## Verify (server)
+
+```ts
+import { verifyPaymentTx } from '@circuit-llm/x402';
+
+const ok = await verifyPaymentTx(signature, { expectRaw, recipient, rpcUrl });
+```
+
+Built-in spend caps (`maxSpendRaw`, `maxTotalSpendRaw`), replay protection, and a CIRC/USD oracle. CIRC is a Token-2022 mint (`8fQ…pump`, 6 decimals).

package/dist/index.d.ts

@@ -0,0 +1,203 @@
+declare const CIRC_MINT = "8fQgfsRnRkKSeNUhevT7wp8mhNvMSJdLn1fJi4oVpump";
+declare const CIRC_TOKEN_PROGRAM = "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb";
+declare const CIRC_DECIMALS = 6;
+/** A payment signature is single-use and expires this long after the tx timestamp. */
+declare const MAX_TX_AGE_MS: number;
+declare const JUPITER_PRICE_URL = "https://api.jup.ag/price/v3";
+/** Deep fallback CIRC/USD only when the oracle is down AND no last-known price is fresh. */
+declare const FALLBACK_CIRC_USD = 0.0001;
+
+/** Format raw CIRC base units as a human string, e.g. 300000000n → "300.00". */
+declare function formatCirc(raw: bigint): string;
+/** Raw CIRC base units required for a USD price at a given CIRC/USD rate. Rounds UP in RAW units (NOT to
+ *  a whole CIRC token) so a request is charged its fair value, never bumped to the next token boundary —
+ *  byte-identical to the server (circuit-data-api/lib/pricing.js) + circuit-py. Pure + deterministic. */
+declare function circRawFromUsd(usdPrice: number, circUsd: number): bigint;
+interface PaymentQuote {
+    recipient: string;
+    amountRaw: bigint;
+    amountDisplay: string;
+    token: string;
+    tokenDecimals: number;
+    usdEquivalent?: number;
+    network?: string;
+    /** The endpoint path, if known (for logging / approval hooks). */
+    path?: string;
+    /** The raw `payment` block as received. */
+    raw: unknown;
+}
+/** Parse a 402 response body's `payment` block into a typed quote, or null if it
+ *  lacks usable requirements (no recipient / amountRaw). */
+declare function parse402(body: unknown, path?: string): PaymentQuote | null;
+interface OracleOptions {
+    fetchImpl?: typeof fetch;
+    jupiterKey?: string;
+    /** Injectable clock (ms) for deterministic tests. */
+    now?: () => number;
+    cacheTtlMs?: number;
+    lastKnownTtlMs?: number;
+}
+/** Live CIRC/USD price with the same 60s cache + 15-min last-known-good fallback
+ *  as the server, so a single Jupiter hiccup never over-charges. Injectable for tests. */
+declare class CircPriceOracle {
+    private cached;
+    private cachedAt;
+    private lastKnown;
+    private lastKnownAt;
+    private readonly fetchImpl;
+    private readonly jupiterKey;
+    private readonly now;
+    private readonly cacheTtlMs;
+    private readonly lastKnownTtlMs;
+    constructor(opts?: OracleOptions);
+    /** Current CIRC/USD, or null if the oracle is down and no fresh last-known exists. */
+    get(): Promise<number | null>;
+    /** Raw CIRC required for a USD price, using the live (or last-known/fallback) rate. */
+    requiredRaw(usdPrice: number): Promise<bigint>;
+}
+
+/** The only thing the payment spine needs from a wallet. @circuit-llm/wallet (Phase 1)
+ *  is one implementation; any object with this shape works (structural typing). */
+interface PaymentWallet {
+    /** Send `amountRaw` base units of CIRC to `recipient`; resolve to the tx signature. */
+    sendCirc(recipient: string, amountRaw: bigint): Promise<string>;
+    /** Optional payer address, for logging / spend tracking (null when read-only). */
+    readonly address?: string | null;
+}
+declare class PaymentRequiredError extends Error {
+    readonly quote: PaymentQuote | null;
+    constructor(quote: PaymentQuote | null);
+}
+declare class SpendCapError extends Error {
+    readonly quote: PaymentQuote;
+    readonly capRaw: bigint;
+    constructor(quote: PaymentQuote, capRaw: bigint);
+}
+declare class RecipientNotAllowedError extends Error {
+    readonly quote: PaymentQuote;
+    constructor(quote: PaymentQuote);
+}
+declare class BudgetExceededError extends Error {
+    readonly quote: PaymentQuote;
+    constructor(quote: PaymentQuote, spentRaw: bigint, budgetRaw: bigint);
+}
+declare class X402RequestError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown, url: string);
+}
+interface X402JsonResult<T> {
+    data: T;
+    status: number;
+    paymentTx: string | null;
+    quote: PaymentQuote | null;
+}
+interface X402Options {
+    wallet?: PaymentWallet;
+    /** Hard ceiling (raw CIRC base units) per call — refuse to pay a higher quote. */
+    maxSpendRaw?: bigint;
+    /** Pin the payment recipient: refuse any 402 whose recipient isn't in this set (the Circuit
+     *  treasury / known payee). Without it, a malicious endpoint dictates where your CIRC goes. */
+    allowedRecipients?: string[];
+    /** Cumulative ceiling (raw CIRC base units) across ALL calls this client makes — the real drain
+     *  guard, since maxSpendRaw alone lets a hostile endpoint take the cap on every request. */
+    maxTotalSpendRaw?: bigint;
+    /** Approval/notification hook; may be async. Throw inside it to abort the payment. */
+    onPay?: (quote: PaymentQuote) => void | Promise<void>;
+    fetchImpl?: typeof fetch;
+    /** ms before the single transient-error retry (after the CIRC was already spent). */
+    retryDelayMs?: number;
+}
+interface X402Result {
+    resp: Response;
+    paymentTx: string | null;
+    quote: PaymentQuote | null;
+}
+declare class X402Client {
+    private readonly wallet?;
+    private readonly maxSpendRaw?;
+    private readonly allowedRecipients?;
+    private readonly maxTotalSpendRaw?;
+    private readonly onPay?;
+    private readonly fetchImpl;
+    private readonly retryDelayMs;
+    private spentRaw;
+    constructor(opts?: X402Options);
+    /** Total CIRC (raw base units) this client has paid so far. */
+    get totalSpentRaw(): bigint;
+    /** Generic pay-and-retry. `requestFn(extraHeaders)` performs one request; on 402 it
+     *  is called a second time with the X-Payment-Signature header. */
+    request(requestFn: (extraHeaders: Record<string, string>) => Promise<Response>): Promise<X402Result>;
+    /** Convenience around a URL + RequestInit (merges the X-Payment-Signature header). */
+    fetch(url: string | URL, init?: RequestInit): Promise<Response>;
+    /** Pay-and-parse-JSON: like fetch() but parses the body and throws X402RequestError
+     *  on a non-2xx final response. NOT for streaming responses — use request() for those. */
+    json<T = unknown>(url: string | URL, init?: RequestInit): Promise<X402JsonResult<T>>;
+}
+
+/** Minimal shape of a parsed token balance (subset of @solana/web3.js). */
+interface TokenBalance {
+    accountIndex: number;
+    mint: string;
+    owner?: string;
+    programId?: string;
+    uiTokenAmount?: {
+        amount?: string;
+    };
+}
+/** Minimal shape of a parsed transaction. */
+interface ParsedTx {
+    blockTime?: number | null;
+    meta?: {
+        err?: unknown;
+        preTokenBalances?: TokenBalance[] | null;
+        postTokenBalances?: TokenBalance[] | null;
+    } | null;
+}
+/** Just the method verifyPaymentTx needs — satisfied by a @solana/web3.js Connection. */
+interface ParsedTxConnection {
+    getParsedTransaction(signature: string, opts: {
+        commitment: string;
+        maxSupportedTransactionVersion?: number;
+    }): Promise<ParsedTx | null>;
+}
+/** Replay guard — each signature is single-use. In-memory default; pass your own
+ *  (e.g. disk- or Redis-backed) for multi-process services. */
+interface ReplayStore {
+    has(sig: string): boolean;
+    add(sig: string): void;
+}
+declare class MemoryReplayStore implements ReplayStore {
+    private readonly seen;
+    has(sig: string): boolean;
+    add(sig: string): void;
+}
+declare class FileReplayStore implements ReplayStore {
+    private readonly dir;
+    constructor(dir: string);
+    private p;
+    has(sig: string): boolean;
+    add(sig: string): void;
+}
+/** Sum CIRC base units that landed in `treasury` within a parsed tx (post − pre). Pure. */
+declare function circReceived(tx: ParsedTx, treasury: string, mint?: string): bigint;
+interface VerifyOptions {
+    connection: ParsedTxConnection;
+    /** The wallet that must have received the CIRC. */
+    treasury: string;
+    replay?: ReplayStore;
+    maxAgeMs?: number;
+    now?: () => number;
+    /** RPC fetch retries (for propagation lag). */
+    retries?: number;
+    retryDelayMs?: number;
+}
+interface VerifyResult {
+    received: bigint;
+    required: bigint;
+}
+/** Verify that `txSignature` is a confirmed, recent CIRC payment to `treasury`
+ *  covering `requiredRaw`. Throws on any failure; marks the signature used on success. */
+declare function verifyPaymentTx(txSignature: string, requiredRaw: bigint, opts: VerifyOptions): Promise<VerifyResult>;
+
+export { BudgetExceededError, CIRC_DECIMALS, CIRC_MINT, CIRC_TOKEN_PROGRAM, CircPriceOracle, FALLBACK_CIRC_USD, FileReplayStore, JUPITER_PRICE_URL, MAX_TX_AGE_MS, MemoryReplayStore, type OracleOptions, type ParsedTx, type ParsedTxConnection, type PaymentQuote, PaymentRequiredError, type PaymentWallet, RecipientNotAllowedError, type ReplayStore, SpendCapError, type TokenBalance, type VerifyOptions, type VerifyResult, X402Client, type X402JsonResult, type X402Options, X402RequestError, type X402Result, circRawFromUsd, circReceived, formatCirc, parse402, verifyPaymentTx };

package/dist/index.js

@@ -0,0 +1,317 @@
+// src/constants.ts
+var CIRC_MINT = "8fQgfsRnRkKSeNUhevT7wp8mhNvMSJdLn1fJi4oVpump";
+var CIRC_TOKEN_PROGRAM = "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb";
+var CIRC_DECIMALS = 6;
+var MAX_TX_AGE_MS = 5 * 6e4;
+var JUPITER_PRICE_URL = "https://api.jup.ag/price/v3";
+var FALLBACK_CIRC_USD = 1e-4;
+
+// src/quote.ts
+function formatCirc(raw) {
+  return (Number(raw) / 10 ** CIRC_DECIMALS).toFixed(2);
+}
+function circRawFromUsd(usdPrice, circUsd) {
+  const rate = circUsd > 0 ? circUsd : FALLBACK_CIRC_USD;
+  return BigInt(Math.ceil(usdPrice / rate * 10 ** CIRC_DECIMALS));
+}
+function parse402(body, path) {
+  const pay = body?.payment;
+  if (!pay || !pay.recipient || pay.amountRaw == null) return null;
+  let amountRaw;
+  try {
+    amountRaw = BigInt(pay.amountRaw);
+  } catch {
+    return null;
+  }
+  return {
+    recipient: String(pay.recipient),
+    amountRaw,
+    amountDisplay: pay.amountDisplay ?? `${formatCirc(amountRaw)} CIRC`,
+    token: pay.token ?? CIRC_MINT,
+    tokenDecimals: pay.tokenDecimals ?? CIRC_DECIMALS,
+    usdEquivalent: pay.usdEquivalent,
+    network: pay.network,
+    path,
+    raw: pay
+  };
+}
+var CircPriceOracle = class {
+  cached = null;
+  cachedAt = 0;
+  lastKnown = null;
+  lastKnownAt = 0;
+  fetchImpl;
+  jupiterKey;
+  now;
+  cacheTtlMs;
+  lastKnownTtlMs;
+  constructor(opts = {}) {
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+    this.jupiterKey = opts.jupiterKey ?? "";
+    this.now = opts.now ?? Date.now;
+    this.cacheTtlMs = opts.cacheTtlMs ?? 6e4;
+    this.lastKnownTtlMs = opts.lastKnownTtlMs ?? 15 * 6e4;
+  }
+  /** Current CIRC/USD, or null if the oracle is down and no fresh last-known exists. */
+  async get() {
+    const t = this.now();
+    if (this.cached !== null && t - this.cachedAt < this.cacheTtlMs) return this.cached;
+    try {
+      const headers = this.jupiterKey ? { "x-api-key": this.jupiterKey } : void 0;
+      const resp = await this.fetchImpl(`${JUPITER_PRICE_URL}?ids=${CIRC_MINT}`, {
+        headers,
+        signal: AbortSignal.timeout(5e3)
+      });
+      if (!resp.ok) throw new Error(`Jupiter ${resp.status}`);
+      const data = await resp.json();
+      const price = data[CIRC_MINT]?.usdPrice ?? null;
+      if (price && price > 0) {
+        this.cached = price;
+        this.cachedAt = t;
+        this.lastKnown = price;
+        this.lastKnownAt = t;
+        return price;
+      }
+    } catch {
+    }
+    if (this.lastKnown && this.now() - this.lastKnownAt < this.lastKnownTtlMs) return this.lastKnown;
+    return null;
+  }
+  /** Raw CIRC required for a USD price, using the live (or last-known/fallback) rate. */
+  async requiredRaw(usdPrice) {
+    const circUsd = await this.get();
+    return circRawFromUsd(usdPrice, circUsd && circUsd > 0 ? circUsd : FALLBACK_CIRC_USD);
+  }
+};
+
+// src/client.ts
+var PaymentRequiredError = class extends Error {
+  quote;
+  constructor(quote) {
+    super(`Payment required: ${quote?.amountDisplay ?? "?"} (no wallet configured)`);
+    this.name = "PaymentRequiredError";
+    this.quote = quote;
+  }
+};
+var SpendCapError = class extends Error {
+  quote;
+  capRaw;
+  constructor(quote, capRaw) {
+    super(`Quoted ${quote.amountDisplay} (${quote.amountRaw} raw) exceeds the spend cap of ${capRaw} raw CIRC`);
+    this.name = "SpendCapError";
+    this.quote = quote;
+    this.capRaw = capRaw;
+  }
+};
+var RecipientNotAllowedError = class extends Error {
+  quote;
+  constructor(quote) {
+    super(`402 recipient ${quote.recipient} is not in the allowed treasury set \u2014 refusing to pay`);
+    this.name = "RecipientNotAllowedError";
+    this.quote = quote;
+  }
+};
+var BudgetExceededError = class extends Error {
+  quote;
+  constructor(quote, spentRaw, budgetRaw) {
+    super(`Paying ${quote.amountRaw} would exceed the session budget (${spentRaw}/${budgetRaw} raw CIRC spent)`);
+    this.name = "BudgetExceededError";
+    this.quote = quote;
+  }
+};
+var X402RequestError = class extends Error {
+  status;
+  body;
+  constructor(status, body, url) {
+    super(`HTTP ${status} on ${url}`);
+    this.name = "X402RequestError";
+    this.status = status;
+    this.body = body;
+  }
+};
+var TRANSIENT = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
+var X402Client = class {
+  wallet;
+  maxSpendRaw;
+  allowedRecipients;
+  maxTotalSpendRaw;
+  onPay;
+  fetchImpl;
+  retryDelayMs;
+  spentRaw = 0n;
+  // cumulative CIRC paid by this client
+  constructor(opts = {}) {
+    this.wallet = opts.wallet;
+    this.maxSpendRaw = opts.maxSpendRaw;
+    this.allowedRecipients = opts.allowedRecipients ? new Set(opts.allowedRecipients) : void 0;
+    this.maxTotalSpendRaw = opts.maxTotalSpendRaw;
+    this.onPay = opts.onPay;
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+    this.retryDelayMs = opts.retryDelayMs ?? 2e3;
+  }
+  /** Total CIRC (raw base units) this client has paid so far. */
+  get totalSpentRaw() {
+    return this.spentRaw;
+  }
+  /** Generic pay-and-retry. `requestFn(extraHeaders)` performs one request; on 402 it
+   *  is called a second time with the X-Payment-Signature header. */
+  async request(requestFn) {
+    let resp = await requestFn({});
+    if (resp.ok || resp.status !== 402) return { resp, paymentTx: null, quote: null };
+    const body = await resp.clone().json().catch(() => ({}));
+    const quote = parse402(body);
+    if (!quote) throw new Error("Endpoint returned 402 without usable payment requirements");
+    if (!this.wallet) throw new PaymentRequiredError(quote);
+    if (this.maxSpendRaw != null && quote.amountRaw > this.maxSpendRaw) {
+      throw new SpendCapError(quote, this.maxSpendRaw);
+    }
+    if (this.allowedRecipients && !this.allowedRecipients.has(quote.recipient)) {
+      throw new RecipientNotAllowedError(quote);
+    }
+    if (this.maxTotalSpendRaw != null && this.spentRaw + quote.amountRaw > this.maxTotalSpendRaw) {
+      throw new BudgetExceededError(quote, this.spentRaw, this.maxTotalSpendRaw);
+    }
+    await this.onPay?.(quote);
+    const txSig = await this.wallet.sendCirc(quote.recipient, quote.amountRaw);
+    this.spentRaw += quote.amountRaw;
+    resp = await requestFn({ "X-Payment-Signature": txSig });
+    if (!resp.ok && TRANSIENT.has(resp.status)) {
+      await new Promise((r) => setTimeout(r, this.retryDelayMs));
+      resp = await requestFn({ "X-Payment-Signature": txSig });
+    }
+    return { resp, paymentTx: txSig, quote };
+  }
+  /** Convenience around a URL + RequestInit (merges the X-Payment-Signature header). */
+  async fetch(url, init = {}) {
+    const baseHeaders = init.headers ?? {};
+    const { resp } = await this.request(
+      (extra) => this.fetchImpl(url, { ...init, headers: { ...baseHeaders, ...extra } })
+    );
+    return resp;
+  }
+  /** Pay-and-parse-JSON: like fetch() but parses the body and throws X402RequestError
+   *  on a non-2xx final response. NOT for streaming responses — use request() for those. */
+  async json(url, init = {}) {
+    const baseHeaders = init.headers ?? {};
+    const { resp, paymentTx, quote } = await this.request(
+      (extra) => this.fetchImpl(url, { ...init, headers: { ...baseHeaders, ...extra } })
+    );
+    const text = await resp.text();
+    let body;
+    try {
+      body = text ? JSON.parse(text) : null;
+    } catch {
+      body = text;
+    }
+    if (!resp.ok) throw new X402RequestError(resp.status, body, String(url));
+    return { data: body, status: resp.status, paymentTx, quote };
+  }
+};
+
+// src/verify.ts
+import { mkdirSync, existsSync, writeFileSync } from "fs";
+import { join } from "path";
+var MemoryReplayStore = class {
+  seen = /* @__PURE__ */ new Set();
+  has(sig) {
+    return this.seen.has(sig);
+  }
+  add(sig) {
+    this.seen.add(sig);
+  }
+};
+var FileReplayStore = class {
+  dir;
+  constructor(dir) {
+    this.dir = dir;
+    mkdirSync(dir, { recursive: true });
+  }
+  p(sig) {
+    return join(this.dir, sig.replace(/[^A-Za-z0-9_-]/g, "_"));
+  }
+  has(sig) {
+    return existsSync(this.p(sig));
+  }
+  add(sig) {
+    try {
+      writeFileSync(this.p(sig), "", { flag: "wx" });
+    } catch {
+    }
+  }
+};
+function circReceived(tx, treasury, mint = CIRC_MINT) {
+  const pre = tx.meta?.preTokenBalances ?? [];
+  const post = tx.meta?.postTokenBalances ?? [];
+  let received = 0n;
+  for (const p of post) {
+    if (p.mint !== mint) continue;
+    if (p.owner !== treasury) continue;
+    const preBal = pre.find((b) => b.accountIndex === p.accountIndex);
+    const preAmt = BigInt(preBal?.uiTokenAmount?.amount ?? "0");
+    const postAmt = BigInt(p.uiTokenAmount?.amount ?? "0");
+    if (postAmt > preAmt) received += postAmt - preAmt;
+  }
+  return received;
+}
+async function verifyPaymentTx(txSignature, requiredRaw, opts) {
+  const { connection, treasury, replay } = opts;
+  const maxAgeMs = opts.maxAgeMs ?? MAX_TX_AGE_MS;
+  const now = opts.now ?? Date.now;
+  const retries = opts.retries ?? 4;
+  const retryDelayMs = opts.retryDelayMs ?? 2500;
+  if (replay?.has(txSignature)) {
+    throw new Error("Transaction signature already used \u2014 each signature is single-use");
+  }
+  let tx = null;
+  let lastErr = new Error("Transaction not found on chain");
+  for (let attempt = 0; attempt < retries; attempt++) {
+    if (attempt > 0) await new Promise((r) => setTimeout(r, retryDelayMs));
+    try {
+      tx = await connection.getParsedTransaction(txSignature, {
+        commitment: "confirmed",
+        maxSupportedTransactionVersion: 0
+      });
+      if (tx) break;
+      lastErr = new Error("Transaction not found on chain (may not be confirmed yet)");
+    } catch (e) {
+      lastErr = new Error(`RPC error: ${e.message}`);
+    }
+  }
+  if (!tx) throw lastErr;
+  if (tx.meta?.err) throw new Error(`Transaction failed on chain: ${JSON.stringify(tx.meta.err)}`);
+  if (tx.blockTime != null) {
+    if (now() - tx.blockTime * 1e3 > maxAgeMs) throw new Error("Transaction is too old (outside the max age window)");
+  } else if (!replay) {
+    throw new Error("Payment tx has no blockTime and no replay store is configured \u2014 refusing (use a durable ReplayStore)");
+  }
+  const received = circReceived(tx, treasury);
+  if (received < requiredRaw) {
+    throw new Error(
+      `Insufficient payment: received ${formatCirc(received)} CIRC, required ${formatCirc(requiredRaw)} CIRC`
+    );
+  }
+  replay?.add(txSignature);
+  return { received, required: requiredRaw };
+}
+export {
+  BudgetExceededError,
+  CIRC_DECIMALS,
+  CIRC_MINT,
+  CIRC_TOKEN_PROGRAM,
+  CircPriceOracle,
+  FALLBACK_CIRC_USD,
+  FileReplayStore,
+  JUPITER_PRICE_URL,
+  MAX_TX_AGE_MS,
+  MemoryReplayStore,
+  PaymentRequiredError,
+  RecipientNotAllowedError,
+  SpendCapError,
+  X402Client,
+  X402RequestError,
+  circRawFromUsd,
+  circReceived,
+  formatCirc,
+  parse402,
+  verifyPaymentTx
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@circuit-llm/x402",
+  "version": "0.2.1",
+  "description": "Circuit SDK payment spine — pay any x402 endpoint in CIRC (client) + verify on-chain CIRC payments (server). Zero runtime dependencies.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types --conditions=development --test test/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json",
+    "build": "tsup src/index.ts --format esm --dts --clean --out-dir dist",
+    "prepack": "tsup src/index.ts --format esm --dts --clean --out-dir dist"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Circuit-LLM/circuit-sdk.git",
+    "directory": "packages/x402"
+  },
+  "homepage": "https://github.com/Circuit-LLM/circuit-sdk/tree/main/packages/x402#readme",
+  "bugs": {
+    "url": "https://github.com/Circuit-LLM/circuit-sdk/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}