@puga-labs/x402-mantle-sdk 0.1.0 → 0.2.1

package/dist/index.cjs

@@ -20,8 +20,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  MANTLE_DEFAULTS: () => MANTLE_DEFAULTS,
+  createMantleClient: () => createMantleClient,
   createPaymentClient: () => createPaymentClient,
-  createPaymentMiddleware: () => createPaymentMiddleware
+  createPaymentMiddleware: () => createPaymentMiddleware,
+  mantlePaywall: () => mantlePaywall,
+  useMantleX402: () => useMantleX402
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -33,6 +37,15 @@ var MANTLE_MAINNET_USDC = {
   address: "0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9",
   decimals: 6
 };
+var MANTLE_DEFAULTS = {
+  NETWORK: "mantle-mainnet",
+  CHAIN_ID: 5e3,
+  USDC_ADDRESS: "0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9",
+  USDC_DECIMALS: 6,
+  CURRENCY: "USD",
+  SCHEME: "exact",
+  FACILITATOR_URL: (typeof process !== "undefined" ? process.env?.NEXT_PUBLIC_FACILITATOR_URL : void 0) || "http://localhost:8080"
+};
 function getDefaultAssetForNetwork(network) {
   switch (network) {
     case MANTLE_MAINNET_NETWORK_ID:
@@ -58,6 +71,59 @@ function usdCentsToAtomic(cents, decimals) {
   return BigInt(cents) * base;
 }
 
+// src/server/constants.ts
+var DEFAULT_TELEMETRY_ENDPOINT = void 0;
+
+// src/server/telemetry.ts
+function createTelemetryEvent(entry, config) {
+  const assetConfig = getDefaultAssetForNetwork(entry.network);
+  return {
+    event: "payment_verified",
+    ts: entry.timestamp,
+    projectKey: config.projectKey,
+    network: entry.network,
+    buyer: entry.from,
+    payTo: entry.to,
+    amountAtomic: entry.valueAtomic,
+    asset: entry.asset,
+    decimals: assetConfig.decimals,
+    nonce: entry.id,
+    route: entry.route ?? "unknown",
+    // Facilitator metadata
+    facilitatorType: "hosted",
+    // SDK always uses hosted mode
+    facilitatorUrl: entry.facilitatorUrl,
+    // From PaymentLogEntry
+    // facilitatorAddress is undefined for SDK (not available)
+    // Optional metadata
+    txHash: entry.txHash,
+    priceUsd: entry.paymentRequirements?.price
+  };
+}
+async function sendTelemetry(event, endpoint) {
+  const targetEndpoint = endpoint ?? DEFAULT_TELEMETRY_ENDPOINT;
+  if (!targetEndpoint) {
+    return;
+  }
+  try {
+    const response = await fetch(targetEndpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${event.projectKey}`
+      },
+      body: JSON.stringify(event)
+    });
+    if (!response.ok) {
+      console.warn(
+        `[x402-telemetry] Failed to send event: HTTP ${response.status}`
+      );
+    }
+  } catch (err) {
+    console.error("[x402-telemetry] Error sending telemetry:", err);
+  }
+}
+
 // src/server/paymentMiddleware.ts
 function getRouteKey(req) {
   const method = (req.method || "GET").toUpperCase();
@@ -81,7 +147,7 @@ function decodePaymentHeader(paymentHeaderBase64) {
   }
 }
 function createPaymentMiddleware(config) {
-  const { facilitatorUrl, receiverAddress, routes, onPaymentSettled } = config;
+  const { facilitatorUrl, receiverAddress, routes, onPaymentSettled, telemetry } = config;
   if (!facilitatorUrl) {
     throw new Error("facilitatorUrl is required");
   }
@@ -171,9 +237,17 @@ function createPaymentMiddleware(config) {
             asset: assetConfig.address,
             route: routeKey,
             timestamp: Date.now(),
+            facilitatorUrl,
+            // Pass from config closure
             paymentRequirements
           };
           onPaymentSettled(logEntry);
+          if (telemetry) {
+            const event = createTelemetryEvent(logEntry, telemetry);
+            sendTelemetry(event, telemetry.endpoint).catch(
+              (err) => console.error("[x402-telemetry] Async send failed:", err)
+            );
+          }
         } catch (err) {
           console.error(
             "[x402-mantle-sdk] Error calling onPaymentSettled hook:",
@@ -198,6 +272,30 @@ function createPaymentMiddleware(config) {
   };
 }
 
+// src/server/mantlePaywall.ts
+function mantlePaywall(opts) {
+  const { priceUsd, payTo, facilitatorUrl, telemetry, onPaymentSettled } = opts;
+  const priceUsdCents = Math.round(priceUsd * 100);
+  return (req, res, next) => {
+    const method = (req.method || "GET").toUpperCase();
+    const path = req.path || "/";
+    const routeKey = `${method} ${path}`;
+    const middleware = createPaymentMiddleware({
+      facilitatorUrl: facilitatorUrl || MANTLE_DEFAULTS.FACILITATOR_URL,
+      receiverAddress: payTo,
+      routes: {
+        [routeKey]: {
+          priceUsdCents,
+          network: MANTLE_DEFAULTS.NETWORK
+        }
+      },
+      telemetry,
+      onPaymentSettled
+    });
+    return middleware(req, res, next);
+  };
+}
+
 // src/shared/utils.ts
 function encodeJsonToBase64(value) {
   const json = JSON.stringify(value);
@@ -300,7 +398,8 @@ function createPaymentClient(config) {
     resourceUrl,
     facilitatorUrl,
     provider,
-    userAddress: userAddressOverride
+    userAddress: userAddressOverride,
+    projectKey
   } = config;
   if (!resourceUrl) {
     throw new Error("resourceUrl is required");
@@ -387,7 +486,8 @@ function createPaymentClient(config) {
       const settleRes = await fetch(settleUrl, {
         method: "POST",
         headers: {
-          "Content-Type": "application/json"
+          "Content-Type": "application/json",
+          ...projectKey ? { "X-Project-Key": projectKey } : {}
         },
         body: JSON.stringify({
           x402Version: 1,
@@ -439,8 +539,62 @@ function createPaymentClient(config) {
     }
   };
 }
+
+// src/client/createMantleClient.ts
+function createMantleClient(config) {
+  const resourceUrl = config?.resourceUrl ?? (typeof window !== "undefined" ? window.location.origin : "");
+  const facilitatorUrl = config?.facilitatorUrl ?? (typeof process !== "undefined" ? process.env?.NEXT_PUBLIC_FACILITATOR_URL : void 0) ?? "http://localhost:8080";
+  return {
+    async post(url, body) {
+      const account = await config?.getAccount?.();
+      if (!account) {
+        throw new Error(
+          "Wallet not connected. Please connect your wallet first."
+        );
+      }
+      const provider = config?.getProvider?.();
+      if (!provider) {
+        throw new Error("Wallet provider not available");
+      }
+      const client = createPaymentClient({
+        resourceUrl,
+        facilitatorUrl,
+        provider,
+        userAddress: account,
+        projectKey: config?.projectKey
+      });
+      const result = await client.callWithPayment(url, {
+        method: "POST",
+        body
+      });
+      return result.response;
+    }
+  };
+}
+
+// src/client/react/useMantleX402.ts
+var import_wagmi = require("wagmi");
+function useMantleX402(opts) {
+  const { address, isConnected } = (0, import_wagmi.useAccount)();
+  const { data: walletClient } = (0, import_wagmi.useWalletClient)();
+  const client = createMantleClient({
+    facilitatorUrl: opts?.facilitatorUrl,
+    resourceUrl: opts?.resourceUrl,
+    projectKey: opts?.projectKey,
+    getAccount: () => {
+      if (!isConnected || !address) return void 0;
+      return address;
+    },
+    getProvider: () => walletClient
+  });
+  return client;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  MANTLE_DEFAULTS,
+  createMantleClient,
   createPaymentClient,
-  createPaymentMiddleware
+  createPaymentMiddleware,
+  mantlePaywall,
+  useMantleX402
 });

package/dist/index.d.cts

@@ -42,6 +42,20 @@ interface PaymentHeaderObject {
 /** Base64-encoded payment header, sent in X-PAYMENT. */
 type PaymentHeaderBase64 = string;
 
+/**
+ * Default values for Mantle mainnet x402 payments.
+ * These are used by the simplified API (mantlePaywall, createMantleClient).
+ */
+declare const MANTLE_DEFAULTS: {
+    readonly NETWORK: "mantle-mainnet";
+    readonly CHAIN_ID: 5000;
+    readonly USDC_ADDRESS: "0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9";
+    readonly USDC_DECIMALS: 6;
+    readonly CURRENCY: "USD";
+    readonly SCHEME: "exact";
+    readonly FACILITATOR_URL: string;
+};
+
 /** Unique key for a protected route, e.g. "GET /api/protected". */
 type RouteKey = string;
 /** Pricing config for a single route. */
@@ -64,8 +78,39 @@ interface PaymentLogEntry {
     route?: RouteKey;
     txHash?: string;
     timestamp: number;
+    facilitatorUrl?: string;
     paymentRequirements?: PaymentRequirements;
 }
+/** Config for optional telemetry (billing/analytics). */
+interface TelemetryConfig {
+    /** Project key from nosubs.ai dashboard. */
+    projectKey: string;
+    /**
+     * Telemetry endpoint URL.
+     * If not specified, uses DEFAULT_TELEMETRY_ENDPOINT (see server/constants.ts).
+     * If both are undefined, telemetry is not sent.
+     */
+    endpoint?: string;
+}
+/** Telemetry event payload for payment_verified. */
+interface TelemetryEvent {
+    event: "payment_verified";
+    ts: number;
+    projectKey: string;
+    network: string;
+    buyer: string;
+    payTo: string;
+    amountAtomic: string;
+    asset: string;
+    decimals: number;
+    nonce: string;
+    route: string;
+    facilitatorType: "hosted" | "self-hosted";
+    facilitatorUrl?: string;
+    facilitatorAddress?: string;
+    txHash?: string;
+    priceUsd?: string;
+}
 /** Config for createPaymentMiddleware. */
 interface PaymentMiddlewareConfig {
     /** Base URL of facilitator, e.g. https://facilitator.nosubs.ai */
@@ -79,10 +124,43 @@ interface PaymentMiddlewareConfig {
      * You can use this to push logs into your DB / analytics pipeline.
      */
     onPaymentSettled?: (entry: PaymentLogEntry) => void;
+    /** Optional: Send usage telemetry for billing/analytics. */
+    telemetry?: TelemetryConfig;
+}
+/**
+ * Minimal config for mantlePaywall() - simplified API for single-route protection.
+ * This is the "sweet path" for Mantle mainnet + USDC with sensible defaults.
+ */
+interface MinimalPaywallOptions {
+    /** Price in USD (e.g. 0.01 for 1 cent). */
+    priceUsd: number;
+    /** Recipient address (developer wallet). */
+    payTo: `0x${string}`;
+    /** Optional facilitator URL (defaults to localhost:8080 or NEXT_PUBLIC_FACILITATOR_URL). */
+    facilitatorUrl?: string;
+    /** Optional telemetry config. */
+    telemetry?: TelemetryConfig;
+    /** Optional payment settled hook. */
+    onPaymentSettled?: (entry: PaymentLogEntry) => void;
 }
 
 declare function createPaymentMiddleware(config: PaymentMiddlewareConfig): (req: Request, res: Response, next: NextFunction) => Promise<void>;
 
+/**
+ * Simplified wrapper for protecting a single route with x402 payments.
+ * Uses Mantle mainnet defaults (USDC, exact scheme, etc.).
+ *
+ * Usage:
+ * ```typescript
+ * const pay = mantlePaywall({ priceUsd: 0.01, payTo: "0x..." });
+ * export const POST = pay(async (req) => { ... });
+ * ```
+ *
+ * @param opts - Minimal configuration (price, payTo, optional facilitator/telemetry).
+ * @returns Express middleware function for single-route protection.
+ */
+declare function mantlePaywall(opts: MinimalPaywallOptions): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+
 /** Config for the client-side payment helper. */
 interface PaymentClientConfig {
     /** Base URL of your protected resource server. */
@@ -93,6 +171,8 @@ interface PaymentClientConfig {
     provider: unknown;
     /** Optional user address override; otherwise derived from provider. */
     userAddress?: string;
+    /** Optional: Project key for hosted facilitator billing. */
+    projectKey?: string;
 }
 /** Result of a callWithPayment() client operation. */
 interface CallWithPaymentResult<TResponseBody = unknown> {
@@ -122,8 +202,89 @@ interface PaymentClient {
  *  - calls facilitator /settle
  *  - retries the original request with X-PAYMENT header
  *
- * This logic is x402-like and tailored for Mantle + USDC.
+ * This logic is x402 and tailored for Mantle + USDC.
  */
 declare function createPaymentClient(config: PaymentClientConfig): PaymentClient;
 
-export { type AssetConfig, type Authorization, type CallWithPaymentResult, type NetworkId, type PaymentClient, type PaymentClientConfig, type PaymentHeaderBase64, type PaymentHeaderObject, type PaymentHeaderPayload, type PaymentLogEntry, type PaymentMiddlewareConfig, type PaymentRequirements, type RouteKey, type RoutePricingConfig, type RoutesConfig, createPaymentClient, createPaymentMiddleware };
+/**
+ * Configuration for createMantleClient().
+ * All fields are optional - the client auto-detects sensible defaults.
+ */
+interface MantleClientConfig {
+    /** Optional facilitator URL (auto-detects from NEXT_PUBLIC_FACILITATOR_URL or defaults to localhost:8080). */
+    facilitatorUrl?: string;
+    /** Optional resource URL (defaults to current origin in browser, or empty string for relative paths). */
+    resourceUrl?: string;
+    /** Function to get user's wallet address (required for payments). */
+    getAccount?: () => Promise<string | undefined> | string | undefined;
+    /** Function to get wallet provider/client (e.g., viem WalletClient or window.ethereum). */
+    getProvider?: () => any;
+    /** Optional project key for hosted facilitator billing. */
+    projectKey?: string;
+}
+/**
+ * Simplified Mantle payment client interface.
+ * Provides a clean API for making paid POST requests.
+ */
+interface MantleClient {
+    /**
+     * Make a paid POST request to a protected endpoint.
+     * Automatically handles x402 flow (402 response, signing, payment, retry).
+     *
+     * @param url - API endpoint path (e.g., "/api/generate-image").
+     * @param body - Request body (will be JSON stringified).
+     * @returns Response data from the protected endpoint.
+     * @throws Error if wallet is not connected or payment fails.
+     */
+    post<TResp = any>(url: string, body?: any): Promise<TResp>;
+}
+/**
+ * Create a simplified Mantle payment client with auto-detected defaults.
+ *
+ * Usage:
+ * ```typescript
+ * const client = createMantleClient({
+ *   getAccount: () => account?.address,
+ *   getProvider: () => walletClient,
+ * });
+ *
+ * const data = await client.post("/api/generate", { prompt: "..." });
+ * ```
+ *
+ * @param config - Optional configuration (auto-detects facilitatorUrl and resourceUrl).
+ * @returns MantleClient instance with simplified post() method.
+ */
+declare function createMantleClient(config?: MantleClientConfig): MantleClient;
+
+/**
+ * Options for useMantleX402 React hook.
+ */
+interface UseMantleX402Options {
+    /** Optional facilitator URL (auto-detects from NEXT_PUBLIC_FACILITATOR_URL). */
+    facilitatorUrl?: string;
+    /** Optional resource URL (defaults to current origin). */
+    resourceUrl?: string;
+    /** Optional project key for hosted facilitator billing. */
+    projectKey?: string;
+}
+/**
+ * React hook for simplified Mantle x402 payments with wagmi integration.
+ *
+ * Automatically connects to the user's wallet via wagmi hooks and provides
+ * a clean API for making paid requests.
+ *
+ * Usage:
+ * ```typescript
+ * const { post } = useMantleX402();
+ *
+ * const data = await post("/api/generate-image", {
+ *   prompt: "A beautiful sunset"
+ * });
+ * ```
+ *
+ * @param opts - Optional configuration (facilitatorUrl, resourceUrl, projectKey).
+ * @returns MantleClient instance with post() method.
+ */
+declare function useMantleX402(opts?: UseMantleX402Options): MantleClient;
+
+export { type AssetConfig, type Authorization, type CallWithPaymentResult, MANTLE_DEFAULTS, type MantleClient, type MantleClientConfig, type MinimalPaywallOptions, type NetworkId, type PaymentClient, type PaymentClientConfig, type PaymentHeaderBase64, type PaymentHeaderObject, type PaymentHeaderPayload, type PaymentLogEntry, type PaymentMiddlewareConfig, type PaymentRequirements, type RouteKey, type RoutePricingConfig, type RoutesConfig, type TelemetryConfig, type TelemetryEvent, type UseMantleX402Options, createMantleClient, createPaymentClient, createPaymentMiddleware, mantlePaywall, useMantleX402 };

package/dist/index.d.ts

@@ -42,6 +42,20 @@ interface PaymentHeaderObject {
 /** Base64-encoded payment header, sent in X-PAYMENT. */
 type PaymentHeaderBase64 = string;
 
+/**
+ * Default values for Mantle mainnet x402 payments.
+ * These are used by the simplified API (mantlePaywall, createMantleClient).
+ */
+declare const MANTLE_DEFAULTS: {
+    readonly NETWORK: "mantle-mainnet";
+    readonly CHAIN_ID: 5000;
+    readonly USDC_ADDRESS: "0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9";
+    readonly USDC_DECIMALS: 6;
+    readonly CURRENCY: "USD";
+    readonly SCHEME: "exact";
+    readonly FACILITATOR_URL: string;
+};
+
 /** Unique key for a protected route, e.g. "GET /api/protected". */
 type RouteKey = string;
 /** Pricing config for a single route. */
@@ -64,8 +78,39 @@ interface PaymentLogEntry {
     route?: RouteKey;
     txHash?: string;
     timestamp: number;
+    facilitatorUrl?: string;
     paymentRequirements?: PaymentRequirements;
 }
+/** Config for optional telemetry (billing/analytics). */
+interface TelemetryConfig {
+    /** Project key from nosubs.ai dashboard. */
+    projectKey: string;
+    /**
+     * Telemetry endpoint URL.
+     * If not specified, uses DEFAULT_TELEMETRY_ENDPOINT (see server/constants.ts).
+     * If both are undefined, telemetry is not sent.
+     */
+    endpoint?: string;
+}
+/** Telemetry event payload for payment_verified. */
+interface TelemetryEvent {
+    event: "payment_verified";
+    ts: number;
+    projectKey: string;
+    network: string;
+    buyer: string;
+    payTo: string;
+    amountAtomic: string;
+    asset: string;
+    decimals: number;
+    nonce: string;
+    route: string;
+    facilitatorType: "hosted" | "self-hosted";
+    facilitatorUrl?: string;
+    facilitatorAddress?: string;
+    txHash?: string;
+    priceUsd?: string;
+}
 /** Config for createPaymentMiddleware. */
 interface PaymentMiddlewareConfig {
     /** Base URL of facilitator, e.g. https://facilitator.nosubs.ai */
@@ -79,10 +124,43 @@ interface PaymentMiddlewareConfig {
      * You can use this to push logs into your DB / analytics pipeline.
      */
     onPaymentSettled?: (entry: PaymentLogEntry) => void;
+    /** Optional: Send usage telemetry for billing/analytics. */
+    telemetry?: TelemetryConfig;
+}
+/**
+ * Minimal config for mantlePaywall() - simplified API for single-route protection.
+ * This is the "sweet path" for Mantle mainnet + USDC with sensible defaults.
+ */
+interface MinimalPaywallOptions {
+    /** Price in USD (e.g. 0.01 for 1 cent). */
+    priceUsd: number;
+    /** Recipient address (developer wallet). */
+    payTo: `0x${string}`;
+    /** Optional facilitator URL (defaults to localhost:8080 or NEXT_PUBLIC_FACILITATOR_URL). */
+    facilitatorUrl?: string;
+    /** Optional telemetry config. */
+    telemetry?: TelemetryConfig;
+    /** Optional payment settled hook. */
+    onPaymentSettled?: (entry: PaymentLogEntry) => void;
 }
 
 declare function createPaymentMiddleware(config: PaymentMiddlewareConfig): (req: Request, res: Response, next: NextFunction) => Promise<void>;
 
+/**
+ * Simplified wrapper for protecting a single route with x402 payments.
+ * Uses Mantle mainnet defaults (USDC, exact scheme, etc.).
+ *
+ * Usage:
+ * ```typescript
+ * const pay = mantlePaywall({ priceUsd: 0.01, payTo: "0x..." });
+ * export const POST = pay(async (req) => { ... });
+ * ```
+ *
+ * @param opts - Minimal configuration (price, payTo, optional facilitator/telemetry).
+ * @returns Express middleware function for single-route protection.
+ */
+declare function mantlePaywall(opts: MinimalPaywallOptions): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+
 /** Config for the client-side payment helper. */
 interface PaymentClientConfig {
     /** Base URL of your protected resource server. */
@@ -93,6 +171,8 @@ interface PaymentClientConfig {
     provider: unknown;
     /** Optional user address override; otherwise derived from provider. */
     userAddress?: string;
+    /** Optional: Project key for hosted facilitator billing. */
+    projectKey?: string;
 }
 /** Result of a callWithPayment() client operation. */
 interface CallWithPaymentResult<TResponseBody = unknown> {
@@ -122,8 +202,89 @@ interface PaymentClient {
  *  - calls facilitator /settle
  *  - retries the original request with X-PAYMENT header
  *
- * This logic is x402-like and tailored for Mantle + USDC.
+ * This logic is x402 and tailored for Mantle + USDC.
  */
 declare function createPaymentClient(config: PaymentClientConfig): PaymentClient;
 
-export { type AssetConfig, type Authorization, type CallWithPaymentResult, type NetworkId, type PaymentClient, type PaymentClientConfig, type PaymentHeaderBase64, type PaymentHeaderObject, type PaymentHeaderPayload, type PaymentLogEntry, type PaymentMiddlewareConfig, type PaymentRequirements, type RouteKey, type RoutePricingConfig, type RoutesConfig, createPaymentClient, createPaymentMiddleware };
+/**
+ * Configuration for createMantleClient().
+ * All fields are optional - the client auto-detects sensible defaults.
+ */
+interface MantleClientConfig {
+    /** Optional facilitator URL (auto-detects from NEXT_PUBLIC_FACILITATOR_URL or defaults to localhost:8080). */
+    facilitatorUrl?: string;
+    /** Optional resource URL (defaults to current origin in browser, or empty string for relative paths). */
+    resourceUrl?: string;
+    /** Function to get user's wallet address (required for payments). */
+    getAccount?: () => Promise<string | undefined> | string | undefined;
+    /** Function to get wallet provider/client (e.g., viem WalletClient or window.ethereum). */
+    getProvider?: () => any;
+    /** Optional project key for hosted facilitator billing. */
+    projectKey?: string;
+}
+/**
+ * Simplified Mantle payment client interface.
+ * Provides a clean API for making paid POST requests.
+ */
+interface MantleClient {
+    /**
+     * Make a paid POST request to a protected endpoint.
+     * Automatically handles x402 flow (402 response, signing, payment, retry).
+     *
+     * @param url - API endpoint path (e.g., "/api/generate-image").
+     * @param body - Request body (will be JSON stringified).
+     * @returns Response data from the protected endpoint.
+     * @throws Error if wallet is not connected or payment fails.
+     */
+    post<TResp = any>(url: string, body?: any): Promise<TResp>;
+}
+/**
+ * Create a simplified Mantle payment client with auto-detected defaults.
+ *
+ * Usage:
+ * ```typescript
+ * const client = createMantleClient({
+ *   getAccount: () => account?.address,
+ *   getProvider: () => walletClient,
+ * });
+ *
+ * const data = await client.post("/api/generate", { prompt: "..." });
+ * ```
+ *
+ * @param config - Optional configuration (auto-detects facilitatorUrl and resourceUrl).
+ * @returns MantleClient instance with simplified post() method.
+ */
+declare function createMantleClient(config?: MantleClientConfig): MantleClient;
+
+/**
+ * Options for useMantleX402 React hook.
+ */
+interface UseMantleX402Options {
+    /** Optional facilitator URL (auto-detects from NEXT_PUBLIC_FACILITATOR_URL). */
+    facilitatorUrl?: string;
+    /** Optional resource URL (defaults to current origin). */
+    resourceUrl?: string;
+    /** Optional project key for hosted facilitator billing. */
+    projectKey?: string;
+}
+/**
+ * React hook for simplified Mantle x402 payments with wagmi integration.
+ *
+ * Automatically connects to the user's wallet via wagmi hooks and provides
+ * a clean API for making paid requests.
+ *
+ * Usage:
+ * ```typescript
+ * const { post } = useMantleX402();
+ *
+ * const data = await post("/api/generate-image", {
+ *   prompt: "A beautiful sunset"
+ * });
+ * ```
+ *
+ * @param opts - Optional configuration (facilitatorUrl, resourceUrl, projectKey).
+ * @returns MantleClient instance with post() method.
+ */
+declare function useMantleX402(opts?: UseMantleX402Options): MantleClient;
+
+export { type AssetConfig, type Authorization, type CallWithPaymentResult, MANTLE_DEFAULTS, type MantleClient, type MantleClientConfig, type MinimalPaywallOptions, type NetworkId, type PaymentClient, type PaymentClientConfig, type PaymentHeaderBase64, type PaymentHeaderObject, type PaymentHeaderPayload, type PaymentLogEntry, type PaymentMiddlewareConfig, type PaymentRequirements, type RouteKey, type RoutePricingConfig, type RoutesConfig, type TelemetryConfig, type TelemetryEvent, type UseMantleX402Options, createMantleClient, createPaymentClient, createPaymentMiddleware, mantlePaywall, useMantleX402 };

package/dist/index.js

@@ -13,6 +13,15 @@ var MANTLE_MAINNET_USDC = {
   address: "0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9",
   decimals: 6
 };
+var MANTLE_DEFAULTS = {
+  NETWORK: "mantle-mainnet",
+  CHAIN_ID: 5e3,
+  USDC_ADDRESS: "0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9",
+  USDC_DECIMALS: 6,
+  CURRENCY: "USD",
+  SCHEME: "exact",
+  FACILITATOR_URL: (typeof process !== "undefined" ? process.env?.NEXT_PUBLIC_FACILITATOR_URL : void 0) || "http://localhost:8080"
+};
 function getDefaultAssetForNetwork(network) {
   switch (network) {
     case MANTLE_MAINNET_NETWORK_ID:
@@ -38,6 +47,59 @@ function usdCentsToAtomic(cents, decimals) {
   return BigInt(cents) * base;
 }
 
+// src/server/constants.ts
+var DEFAULT_TELEMETRY_ENDPOINT = void 0;
+
+// src/server/telemetry.ts
+function createTelemetryEvent(entry, config) {
+  const assetConfig = getDefaultAssetForNetwork(entry.network);
+  return {
+    event: "payment_verified",
+    ts: entry.timestamp,
+    projectKey: config.projectKey,
+    network: entry.network,
+    buyer: entry.from,
+    payTo: entry.to,
+    amountAtomic: entry.valueAtomic,
+    asset: entry.asset,
+    decimals: assetConfig.decimals,
+    nonce: entry.id,
+    route: entry.route ?? "unknown",
+    // Facilitator metadata
+    facilitatorType: "hosted",
+    // SDK always uses hosted mode
+    facilitatorUrl: entry.facilitatorUrl,
+    // From PaymentLogEntry
+    // facilitatorAddress is undefined for SDK (not available)
+    // Optional metadata
+    txHash: entry.txHash,
+    priceUsd: entry.paymentRequirements?.price
+  };
+}
+async function sendTelemetry(event, endpoint) {
+  const targetEndpoint = endpoint ?? DEFAULT_TELEMETRY_ENDPOINT;
+  if (!targetEndpoint) {
+    return;
+  }
+  try {
+    const response = await fetch(targetEndpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${event.projectKey}`
+      },
+      body: JSON.stringify(event)
+    });
+    if (!response.ok) {
+      console.warn(
+        `[x402-telemetry] Failed to send event: HTTP ${response.status}`
+      );
+    }
+  } catch (err) {
+    console.error("[x402-telemetry] Error sending telemetry:", err);
+  }
+}
+
 // src/server/paymentMiddleware.ts
 function getRouteKey(req) {
   const method = (req.method || "GET").toUpperCase();
@@ -61,7 +123,7 @@ function decodePaymentHeader(paymentHeaderBase64) {
   }
 }
 function createPaymentMiddleware(config) {
-  const { facilitatorUrl, receiverAddress, routes, onPaymentSettled } = config;
+  const { facilitatorUrl, receiverAddress, routes, onPaymentSettled, telemetry } = config;
   if (!facilitatorUrl) {
     throw new Error("facilitatorUrl is required");
   }
@@ -151,9 +213,17 @@ function createPaymentMiddleware(config) {
             asset: assetConfig.address,
             route: routeKey,
             timestamp: Date.now(),
+            facilitatorUrl,
+            // Pass from config closure
             paymentRequirements
           };
           onPaymentSettled(logEntry);
+          if (telemetry) {
+            const event = createTelemetryEvent(logEntry, telemetry);
+            sendTelemetry(event, telemetry.endpoint).catch(
+              (err) => console.error("[x402-telemetry] Async send failed:", err)
+            );
+          }
         } catch (err) {
           console.error(
             "[x402-mantle-sdk] Error calling onPaymentSettled hook:",
@@ -178,6 +248,30 @@ function createPaymentMiddleware(config) {
   };
 }
 
+// src/server/mantlePaywall.ts
+function mantlePaywall(opts) {
+  const { priceUsd, payTo, facilitatorUrl, telemetry, onPaymentSettled } = opts;
+  const priceUsdCents = Math.round(priceUsd * 100);
+  return (req, res, next) => {
+    const method = (req.method || "GET").toUpperCase();
+    const path = req.path || "/";
+    const routeKey = `${method} ${path}`;
+    const middleware = createPaymentMiddleware({
+      facilitatorUrl: facilitatorUrl || MANTLE_DEFAULTS.FACILITATOR_URL,
+      receiverAddress: payTo,
+      routes: {
+        [routeKey]: {
+          priceUsdCents,
+          network: MANTLE_DEFAULTS.NETWORK
+        }
+      },
+      telemetry,
+      onPaymentSettled
+    });
+    return middleware(req, res, next);
+  };
+}
+
 // src/shared/utils.ts
 function encodeJsonToBase64(value) {
   const json = JSON.stringify(value);
@@ -280,7 +374,8 @@ function createPaymentClient(config) {
     resourceUrl,
     facilitatorUrl,
     provider,
-    userAddress: userAddressOverride
+    userAddress: userAddressOverride,
+    projectKey
   } = config;
   if (!resourceUrl) {
     throw new Error("resourceUrl is required");
@@ -367,7 +462,8 @@ function createPaymentClient(config) {
       const settleRes = await fetch(settleUrl, {
         method: "POST",
         headers: {
-          "Content-Type": "application/json"
+          "Content-Type": "application/json",
+          ...projectKey ? { "X-Project-Key": projectKey } : {}
         },
         body: JSON.stringify({
           x402Version: 1,
@@ -419,7 +515,61 @@ function createPaymentClient(config) {
     }
   };
 }
+
+// src/client/createMantleClient.ts
+function createMantleClient(config) {
+  const resourceUrl = config?.resourceUrl ?? (typeof window !== "undefined" ? window.location.origin : "");
+  const facilitatorUrl = config?.facilitatorUrl ?? (typeof process !== "undefined" ? process.env?.NEXT_PUBLIC_FACILITATOR_URL : void 0) ?? "http://localhost:8080";
+  return {
+    async post(url, body) {
+      const account = await config?.getAccount?.();
+      if (!account) {
+        throw new Error(
+          "Wallet not connected. Please connect your wallet first."
+        );
+      }
+      const provider = config?.getProvider?.();
+      if (!provider) {
+        throw new Error("Wallet provider not available");
+      }
+      const client = createPaymentClient({
+        resourceUrl,
+        facilitatorUrl,
+        provider,
+        userAddress: account,
+        projectKey: config?.projectKey
+      });
+      const result = await client.callWithPayment(url, {
+        method: "POST",
+        body
+      });
+      return result.response;
+    }
+  };
+}
+
+// src/client/react/useMantleX402.ts
+import { useAccount, useWalletClient } from "wagmi";
+function useMantleX402(opts) {
+  const { address, isConnected } = useAccount();
+  const { data: walletClient } = useWalletClient();
+  const client = createMantleClient({
+    facilitatorUrl: opts?.facilitatorUrl,
+    resourceUrl: opts?.resourceUrl,
+    projectKey: opts?.projectKey,
+    getAccount: () => {
+      if (!isConnected || !address) return void 0;
+      return address;
+    },
+    getProvider: () => walletClient
+  });
+  return client;
+}
 export {
+  MANTLE_DEFAULTS,
+  createMantleClient,
   createPaymentClient,
-  createPaymentMiddleware
+  createPaymentMiddleware,
+  mantlePaywall,
+  useMantleX402
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@puga-labs/x402-mantle-sdk",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "x402 payments SDK for Mantle (USDC, gasless, facilitator-based)",
   "license": "MIT",
   "author": "Evgenii Pugachev <cyprus.pugamuga@gmail.com>",
@@ -46,7 +46,13 @@
     "test:watch": "vitest watch"
   },
   "peerDependencies": {
-    "ethers": "^6.0.0"
+    "ethers": "^6.0.0",
+    "wagmi": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "wagmi": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@eslint/js": "^9.17.0",
@@ -56,6 +62,7 @@
     "@typescript-eslint/parser": "^8.20.0",
     "@vitest/coverage-v8": "^4.0.15",
     "@vitest/ui": "^4.0.15",
+    "@wagmi/core": "^2.22.1",
     "eslint": "^9.17.0",
     "express": "^5.2.1",
     "globals": "^15.14.0",
@@ -63,6 +70,8 @@
     "rimraf": "^6.0.0",
     "tsup": "^8.0.0",
     "typescript": "^5.6.0",
-    "vitest": "^4.0.15"
+    "viem": "^2.41.2",
+    "vitest": "^4.0.15",
+    "wagmi": "^2.19.5"
   }
 }