x402-stellar-sdk 1.0.0

package/dist/chunk-6Q22RJI6.js

@@ -0,0 +1,38 @@
+// src/client/index.ts
+function parse402Response(response) {
+  if (response.status !== 402) return null;
+  const amount = response.headers.get("x-402-amount") ?? response.headers.get("X-402-Amount");
+  const assetCode = response.headers.get("x-402-asset-code") ?? response.headers.get("X-402-Asset-Code");
+  const network = response.headers.get("x-402-network") ?? response.headers.get("X-402-Network");
+  const destination = response.headers.get("x-402-destination") ?? response.headers.get("X-402-Destination");
+  const issuer = response.headers.get("x-402-issuer") ?? response.headers.get("X-402-Issuer") ?? void 0;
+  const memo = response.headers.get("x-402-memo") ?? response.headers.get("X-402-Memo") ?? void 0;
+  if (!amount || !assetCode || !network || !destination) return null;
+  return { amount, assetCode, network, destination, ...issuer && { issuer }, ...memo && { memo } };
+}
+function addPaymentHeaders(headers, payment) {
+  const h = new Headers(headers);
+  h.set("X-402-Transaction-Hash", payment.transactionHash);
+  if (payment.timestamp) h.set("X-402-Timestamp", payment.timestamp);
+  return h;
+}
+async function x402Fetch(input, init, options) {
+  const res = await fetch(input, init);
+  const paymentRequest = parse402Response(res);
+  if (!paymentRequest) return res;
+  const payWithStellar = options?.payWithStellar;
+  if (!payWithStellar) {
+    throw new Error(
+      "402 Payment Required. Provide x402Fetch(..., { payWithStellar }) to handle Stellar payments."
+    );
+  }
+  const payment = await payWithStellar(paymentRequest);
+  if (!payment) return res;
+  const newHeaders = addPaymentHeaders(init?.headers ?? {}, payment);
+  const retryInit = { ...init, headers: newHeaders };
+  return fetch(input, retryInit);
+}
+
+export {
+  x402Fetch
+};

package/dist/chunk-CBSQ4354.js

@@ -0,0 +1,38 @@
+// src/server/middleware.ts
+function createPaymentRequiredResponse(options) {
+  const headers = {
+    "Content-Type": "application/json",
+    "X-402-Amount": options.price,
+    "X-402-Asset-Code": options.assetCode,
+    "X-402-Network": options.network,
+    "X-402-Destination": options.destination
+  };
+  if (options.issuer) headers["X-402-Issuer"] = options.issuer;
+  if (options.memo) headers["X-402-Memo"] = options.memo;
+  return {
+    status: 402,
+    headers,
+    body: {
+      error: "Payment Required",
+      amount: options.price,
+      assetCode: options.assetCode,
+      ...options.issuer && { issuer: options.issuer },
+      network: options.network,
+      destination: options.destination,
+      ...options.memo && { memo: options.memo }
+    }
+  };
+}
+async function processPaymentMiddleware(requestHeaders, options) {
+  const txHash = requestHeaders["x-402-transaction-hash"] ?? requestHeaders["X-402-Transaction-Hash"];
+  if (!txHash?.trim()) return { allowed: false };
+  const { verifyPaymentOnChain } = await import("./verify-YIB2KFUK.js");
+  const { valid, error } = await verifyPaymentOnChain(txHash.trim(), options);
+  if (!valid) return { allowed: false };
+  return { allowed: true };
+}
+
+export {
+  createPaymentRequiredResponse,
+  processPaymentMiddleware
+};

package/dist/chunk-FRGC7Q3Z.js

@@ -0,0 +1,50 @@
+// src/server/verify.ts
+var HORIZON = {
+  testnet: "https://horizon-testnet.stellar.org",
+  mainnet: "https://horizon.stellar.org"
+};
+function decodeMemo(memoType, memoValue) {
+  if (memoType !== "text" || !memoValue) return null;
+  try {
+    const base64 = memoValue.replace(/-/g, "+").replace(/_/g, "/");
+    if (typeof Buffer !== "undefined") return Buffer.from(base64, "base64").toString("utf8");
+    return atob(base64);
+  } catch {
+    return null;
+  }
+}
+async function verifyPaymentOnChain(txHash, options) {
+  const base = HORIZON[options.network];
+  let tx;
+  try {
+    const res = await fetch(`${base}/transactions/${txHash}`);
+    if (!res.ok) return { valid: false, error: `Horizon ${res.status}: ${await res.text()}` };
+    tx = await res.json();
+  } catch (e) {
+    return { valid: false, error: e instanceof Error ? e.message : "Failed to fetch transaction" };
+  }
+  if (!tx.successful) return { valid: false, error: "Transaction not successful" };
+  if (options.memo && tx.memo_type && tx.memo) {
+    const decoded = decodeMemo(tx.memo_type, tx.memo);
+    if (decoded !== options.memo) return { valid: false, error: "Memo mismatch" };
+  }
+  const paymentsRes = await fetch(`${base}/transactions/${txHash}/operations?limit=20`);
+  if (!paymentsRes.ok) return { valid: false, error: "Failed to fetch operations" };
+  const opsData = await paymentsRes.json();
+  const records = opsData._embedded?.records ?? [];
+  const paymentOps = records.filter((r) => r.type === "payment");
+  const requiredAmount = parseFloat(options.price);
+  const isNative = !options.issuer && (options.assetCode === "XLM" || !options.assetCode);
+  for (const op of paymentOps) {
+    if (op.to !== options.destination) continue;
+    const amount = parseFloat(op.amount);
+    if (amount < requiredAmount) continue;
+    if (isNative && op.asset_type === "native") return { valid: true };
+    if (!isNative && options.issuer && op.asset_type !== "native" && op.asset_code === options.assetCode && op.asset_issuer === options.issuer) return { valid: true };
+  }
+  return { valid: false, error: "No matching payment to destination with required amount/asset" };
+}
+
+export {
+  verifyPaymentOnChain
+};

package/dist/chunk-UFTMXLKQ.js

@@ -0,0 +1,27 @@
+import {
+  createPaymentRequiredResponse,
+  processPaymentMiddleware
+} from "./chunk-CBSQ4354.js";
+
+// src/server/index.ts
+function x402(options) {
+  if (!options.price || !options.assetCode || !options.destination || !options.network) {
+    throw new Error("x402() requires price, assetCode, destination, and network");
+  }
+  return async (req, res, next) => {
+    const headers = {};
+    if (typeof req.headers === "object") {
+      for (const [k, v] of Object.entries(req.headers)) {
+        if (typeof v === "string") headers[k.toLowerCase()] = v;
+      }
+    }
+    const result = await processPaymentMiddleware(headers, options);
+    if (result.allowed) return next();
+    const payment402 = createPaymentRequiredResponse(options);
+    res.status(402).json(payment402.body);
+  };
+}
+
+export {
+  x402
+};

package/dist/client/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * x402 client – payment request from 402 response.
+ */
+interface X402PaymentRequest {
+    amount: string;
+    assetCode: string;
+    issuer?: string;
+    network: string;
+    destination: string;
+    memo?: string;
+}
+interface X402PaymentResponse {
+    transactionHash: string;
+    timestamp?: string;
+}
+interface X402ClientOptions {
+    /** Retry request after payment (default true) */
+    autoRetry?: boolean;
+    /** Pluggable: perform Stellar payment (e.g. Freighter), return tx hash */
+    payWithStellar?: (req: X402PaymentRequest) => Promise<X402PaymentResponse | null>;
+}
+
+/**
+ * x402 client – fetch with automatic 402 handling and Stellar payment flow.
+ */
+
+/**
+ * Fetch that handles 402: on 402, calls payWithStellar (or throws), then retries with payment headers.
+ */
+declare function x402Fetch(input: RequestInfo | URL, init?: RequestInit, options?: X402ClientOptions): Promise<Response>;
+
+export { type X402ClientOptions, type X402PaymentRequest, type X402PaymentResponse, x402Fetch };

package/dist/client/index.js

@@ -0,0 +1,6 @@
+import {
+  x402Fetch
+} from "../chunk-6Q22RJI6.js";
+export {
+  x402Fetch
+};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createPaymentRequiredResponse, processPaymentMiddleware, x402 } from './server/index.js';
+export { P as PaymentRequiredResponse, X as X402StellarOptions } from './types-CibbvCHY.js';
+export { X402ClientOptions, X402PaymentRequest, X402PaymentResponse, x402Fetch } from './client/index.js';

package/dist/index.js

@@ -0,0 +1,17 @@
+import {
+  x402
+} from "./chunk-UFTMXLKQ.js";
+import {
+  createPaymentRequiredResponse,
+  processPaymentMiddleware
+} from "./chunk-CBSQ4354.js";
+import {
+  x402Fetch
+} from "./chunk-6Q22RJI6.js";
+import "./chunk-FRGC7Q3Z.js";
+export {
+  createPaymentRequiredResponse,
+  processPaymentMiddleware,
+  x402,
+  x402Fetch
+};

package/dist/server/hono.d.ts

@@ -0,0 +1,20 @@
+import { X as X402StellarOptions } from '../types-CibbvCHY.js';
+
+/**
+ * Hono adapter for x402 – use x402Hono(options) as middleware.
+ */
+
+type HonoContext = {
+    req: {
+        header: (name: string) => string | undefined;
+        raw: Request;
+    };
+    json: (body: unknown, status?: number, headers?: Record<string, string>) => Response;
+};
+type HonoNext = () => Promise<void>;
+/**
+ * x402 middleware for Hono. Returns 402 with Stellar payment metadata when payment is missing or invalid.
+ */
+declare function x402Hono(options: X402StellarOptions): (c: HonoContext, next: HonoNext) => Promise<Response | undefined>;
+
+export { x402Hono };

package/dist/server/hono.js

@@ -0,0 +1,27 @@
+import {
+  createPaymentRequiredResponse,
+  processPaymentMiddleware
+} from "../chunk-CBSQ4354.js";
+
+// src/server/hono.ts
+function x402Hono(options) {
+  if (!options.price || !options.assetCode || !options.destination || !options.network) {
+    throw new Error("x402Hono() requires price, assetCode, destination, and network");
+  }
+  return async (c, next) => {
+    const raw = c.req.raw;
+    const headers = {};
+    raw.headers.forEach((v, k) => {
+      headers[k.toLowerCase()] = v;
+    });
+    const result = await processPaymentMiddleware(headers, options);
+    if (!result.allowed) {
+      const payment402 = createPaymentRequiredResponse(options);
+      return c.json(payment402.body, 402, payment402.headers);
+    }
+    await next();
+  };
+}
+export {
+  x402Hono
+};

package/dist/server/index.d.ts

@@ -0,0 +1,57 @@
+import { X as X402StellarOptions, P as PaymentRequiredResponse } from '../types-CibbvCHY.js';
+
+/**
+ * Core x402 middleware – returns 402 with Stellar payment metadata.
+ * Framework-agnostic; Hono/Express adapters call this.
+ */
+
+interface MiddlewareResult {
+    allowed: boolean;
+    paymentRequired?: PaymentRequiredResponse;
+}
+/**
+ * Create 402 response body and headers for Stellar payment.
+ * Client uses: destination, amount, assetCode, issuer, network, memo to create payment.
+ */
+declare function createPaymentRequiredResponse(options: X402StellarOptions): PaymentRequiredResponse;
+/**
+ * Process payment check: extract receipt from headers and verify on Horizon.
+ */
+declare function processPaymentMiddleware(requestHeaders: Record<string, string>, options: X402StellarOptions): Promise<MiddlewareResult>;
+
+/**
+ * Verify Stellar payment on Horizon (transaction hash + destination/amount/asset/memo).
+ */
+
+/**
+ * Verify that the transaction with given hash paid the destination with at least the required amount/asset.
+ */
+declare function verifyPaymentOnChain(txHash: string, options: X402StellarOptions): Promise<{
+    valid: boolean;
+    error?: string;
+}>;
+
+/**
+ * x402 server – Stellar payment-gated middleware.
+ * Same ergonomics as x402-mantle-sdk: x402({ price, assetCode, issuer, network, destination }).
+ */
+
+/** Express-style request (headers) and response (status + json). */
+type X402Request = {
+    headers: Record<string, string | string[] | undefined>;
+};
+type X402Response = {
+    status(n: number): {
+        json(b: unknown): void;
+    };
+    json(b: unknown): void;
+};
+type X402Next = () => void | Promise<void>;
+/**
+ * x402 middleware – use in Express/Hono/Next.
+ * On missing/invalid payment: respond 402 with Stellar payment metadata.
+ * On valid payment: call next().
+ */
+declare function x402(options: X402StellarOptions): (req: X402Request, res: X402Response, next: X402Next) => Promise<void>;
+
+export { PaymentRequiredResponse, type X402Next, type X402Request, type X402Response, X402StellarOptions, createPaymentRequiredResponse, processPaymentMiddleware, verifyPaymentOnChain, x402 };

package/dist/server/index.js

@@ -0,0 +1,16 @@
+import {
+  x402
+} from "../chunk-UFTMXLKQ.js";
+import {
+  createPaymentRequiredResponse,
+  processPaymentMiddleware
+} from "../chunk-CBSQ4354.js";
+import {
+  verifyPaymentOnChain
+} from "../chunk-FRGC7Q3Z.js";
+export {
+  createPaymentRequiredResponse,
+  processPaymentMiddleware,
+  verifyPaymentOnChain,
+  x402
+};

package/dist/server/next.d.ts

@@ -0,0 +1,13 @@
+import { X as X402StellarOptions } from '../types-CibbvCHY.js';
+
+/**
+ * Next.js adapter for x402 – verify payment in API routes and return 402 or continue.
+ */
+
+/**
+ * Use in Next.js API route (App Router or Pages API).
+ * Pass the request headers and your x402 options; returns null if paid, or a NextResponse with 402 if not.
+ */
+declare function withX402(requestHeaders: Headers, options: X402StellarOptions): Promise<Response | null>;
+
+export { X402StellarOptions, withX402 };

package/dist/server/next.js

@@ -0,0 +1,22 @@
+import {
+  createPaymentRequiredResponse,
+  processPaymentMiddleware
+} from "../chunk-CBSQ4354.js";
+
+// src/server/next.ts
+async function withX402(requestHeaders, options) {
+  const headers = {};
+  requestHeaders.forEach((v, k) => {
+    headers[k.toLowerCase()] = v;
+  });
+  const result = await processPaymentMiddleware(headers, options);
+  if (result.allowed) return null;
+  const payment402 = createPaymentRequiredResponse(options);
+  return new Response(JSON.stringify(payment402.body), {
+    status: 402,
+    headers: { "Content-Type": "application/json", ...payment402.headers }
+  });
+}
+export {
+  withX402
+};

package/dist/types-CibbvCHY.d.ts

@@ -0,0 +1,32 @@
+/**
+ * x402 server options – Stellar payment metadata (asset code + issuer, not ERC20).
+ */
+interface X402StellarOptions {
+    /** Price amount (e.g. "10.5") */
+    price: string;
+    /** Asset code (e.g. "XLM", "USDC") */
+    assetCode: string;
+    /** Issuer account ID (G...) for custom assets; omit for native XLM */
+    issuer?: string;
+    /** "mainnet" | "testnet" */
+    network: "mainnet" | "testnet";
+    /** Destination account that receives payment (G...) */
+    destination: string;
+    /** Optional memo (e.g. request id) for payment correlation */
+    memo?: string;
+}
+interface PaymentRequiredResponse {
+    status: 402;
+    headers: Record<string, string>;
+    body: {
+        error: "Payment Required";
+        amount: string;
+        assetCode: string;
+        issuer?: string;
+        network: string;
+        destination: string;
+        memo?: string;
+    };
+}
+
+export type { PaymentRequiredResponse as P, X402StellarOptions as X };

package/dist/verify-YIB2KFUK.js

@@ -0,0 +1,6 @@
+import {
+  verifyPaymentOnChain
+} from "./chunk-FRGC7Q3Z.js";
+export {
+  verifyPaymentOnChain
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "x402-stellar-sdk",
+  "version": "1.0.0",
+  "description": "HTTP 402 payment-gated APIs with Stellar payments",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js"
+    },
+    "./server/hono": {
+      "types": "./dist/server/hono.d.ts",
+      "import": "./dist/server/hono.js"
+    },
+    "./server/next": {
+      "types": "./dist/server/next.d.ts",
+      "import": "./dist/server/next.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "tsup": "^8.5.0",
+    "typescript": "^5.3.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codewmilan/stellar-agent-kit.git"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}