@paynodelabs/sdk-js 2.2.3 → 2.4.0

package/README.md

@@ -1,14 +1,32 @@
-# PayNode JavaScript SDK
+# PayNode Master SDK (JS/TS)
+
+> [!NOTE]
+> Compatibility policy & legacy header aliases are documented in [COMPATIBILITY.md](./COMPATIBILITY.md).
 
 [![Official Documentation](https://img.shields.io/badge/Docs-docs.paynode.dev-00ff88?style=for-the-badge&logo=readthedocs)](https://docs.paynode.dev)
 [![NPM Version](https://img.shields.io/npm/v/@paynodelabs/sdk-js.svg?style=for-the-badge)](https://www.npmjs.com/package/@paynodelabs/sdk-js)
+[![License](https://img.shields.io/github/license/paynodeprotocol/paynode?style=for-the-badge)](LICENSE)
+
+The **Master SDK** for the [PayNode Protocol](https://paynode.dev). This JavaScript/TypeScript implementation serves as the **Reference Implementation** for the x402 V2 protocol. All future SDKs (Python, Go, Rust, etc.) are built following the architectural patterns and logic established in this codebase.
+
+The current baseline and cleanup requirements for turning `sdk-js` into the formal multi-language source of truth are documented in [`meta/MULTI_LANGUAGE_BASELINE.md`](../../meta/MULTI_LANGUAGE_BASELINE.md). The protocol source of truth lives in [`meta/SPEC.md`](../../meta/SPEC.md).
 
-The official TypeScript/JavaScript SDK for the **PayNode Protocol (v2.2.1)**. PayNode is a stateless, non-custodial M2M payment gateway that standardizes the HTTP 402 "Payment Required" flow for AI Agents, with support for both on-chain receipts and off-chain signatures (EIP-3009).
+PayNode is a stateless, non-custodial M2M payment gateway that standardizes the HTTP 402 "Payment Required" flow for AI Agents, enabling seamless USDC settlement on Base L2.
 
-## 📖 Read the Docs
+---
+
+## 🏗️ Reference Implementation Status
 
-**For complete installation guides, advanced usage, API references, and architecture details, please visit our official documentation:**
-👉 **[docs.paynode.dev](https://docs.paynode.dev)**
+As the **Master SDK**, `sdk-js` defines the gold standard for:
+- **x402 V2 Handshake**: The JSON-based negotiation protocol between Agents and Merchants.
+- **Dual-Mode Settlement**: Seamless switching between high-speed off-chain signatures (EIP-3009) and robust on-chain receipts.
+- **Proof-of-Intent**: Standardized cryptographic signatures for M2M commerce.
+- **Stateless Verification**: Logic for verifying payments without requiring complex backend databases.
+
+> [!TIP]
+> Developers building PayNode SDKs for other languages should treat this repository as the **Source of Truth** for internal logic and protocol compliance.
+
+---
 
 ## ⚡ Quick Start
 
@@ -19,102 +37,92 @@ npm install @paynodelabs/sdk-js ethers
 ```
 
 ### Agent Client (Payer)
+The `PayNodeAgentClient` automatically identifies 402 challenges and executes the best settlement path (On-chain or EIP-3009).
 
 ```typescript
 import { PayNodeAgentClient } from "@paynodelabs/sdk-js";
 
-const client = new PayNodeAgentClient("YOUR_AGENT_PRIVATE_KEY", ["https://mainnet.base.org", "https://rpc.ankr.com/base"]);
+// Initialize with Private Key and Base RPC
+const client = new PayNodeAgentClient("YOUR_PRIVATE_KEY", ["https://mainnet.base.org"]);
 
 async function main() {
-  // Automatically handles 402 challenges, pays USDC, and retries the request
+  // Automatically handles 402 challenges, settles USDC, and retries the request
   const response = await client.requestGate("https://api.merchant.com/premium-data");
-  console.log(await response.text());
+  const result = await response.json();
+  console.log("Success:", result);
 }
 main();
 ```
 
-### Key Features (v2.2.1)
-- **Zero-Wait Checkout**: API response speed drops from 5 seconds to **under 50ms** by using local signatures instead of waiting for on-chain inclusion.
-- **Double-Spend Protection**: 
-  - **L1 (Memory)**: High-speed local replay protection via `IdempotencyStore`.
-  - **L2 (RPC)**: Real-time on-chain `authorizationState` verification.
-- **Empty-Wallet Proof**: Integrated `balanceOf` probes to block malicious agents using empty wallets to generate valid signatures.
-- **EIP-3009 Support**: Sign payments off-chain using `TransferWithAuthorization`.
-- **X402 V2 Protocol**: JSON-based handshake for structured agent interaction.
-- **Dual Flow**: Automatic switch between V1 (on-chain receipts) and V2 (off-chain signatures).
-
-## 🗺️ Roadmap
-- **TRON Support**: USDT (TRC-20) payment integration.
-- **Solana Support**: SPL USDC/USDT payment integration.
-- **Cross-chain**: Universal settlement via bridges.
-
-## 🚀 Run the Demo
-
-The SDK includes a full merchant/agent demonstration in the `examples/` directory.
+### Merchant Gateway (Seller)
+Starting from **v2.3.0**, the SDK provides a unified middleware for **PayNode Market Proxy** requests. It handles discovery probes, signature verification, and body unwrap in a single line.
 
-### 1. Setup Environment
-
-```bash
-cp .env.example .env
-# Edit .env with your PRIVATE_KEY and RPC_URL
-```
-
-### 2. Get Test Tokens (Required for Base Sepolia)
-
-If you're testing on Sepolia, run the helper script to mint 1,000 mock USDC:
-
-```bash
-npx ts-node examples/mint-test-tokens.ts
+```typescript
+import { PayNodeMerchant } from "@paynodelabs/sdk-js";
+import express from "express";
+
+const app = express();
+const merchant = new PayNodeMerchant({
+  sharedSecret: "YOUR_MARKET_SECRET" // Obtainable from PayNode Market Hub
+});
+
+// Unified Middleware (Manifest + Auth + Discovery)
+app.post("/api/v1/tools", merchant.middleware({
+    manifest: {
+      slug: "gpt-researcher",
+      name: "GPT Researcher",
+      description: "Research endpoint",
+      price_per_call: "0.05",
+      currency: "USDC"
+    },
+    price: "0.05"  // Also set price directly — manifest.price_per_call is for Market Hub sync only
+  }), (req, res) => {
+    // req.body is automatically unwrapped for valid Market Proxy requests
+    res.json({ result: "Data for " + req.body.query });
+  }
+);
 ```
 
-### 3. Run the Merchant Server (Express)
+---
 
-```bash
-npx ts-node examples/express-server.ts
-```
+## 🚀 Key Features
 
-### 4. Run the Agent Client
+- **Zero-Wait Checkout**: Off-chain EIP-3009 signatures allow **<50ms** checkout times by bypassing block confirmation delays.
+- **Autonomous Recovery**: Built-in RPC failover and retry logic for high-availability agent environments.
+- **Double-Spend Protection**: Memory-efficient `IdempotencyStore` for high-frequency replay protection.
+- **EIP-2612 & EIP-3009**: Native support for gasless approvals and off-chain transfers.
+- **Market Proxy Middleware**: Drop-in Express support for PayNode Market discovery, authentication, and payload unwrap.
 
-In another terminal:
+---
 
-```bash
-npx ts-node examples/agent-client.ts
-```
+## 🧭 Roadmap & Ecosystem
 
-The demo will perform a full loop: `402 Handshake -> On-chain Payment -> 200 Verification`.
+As the lead SDK, this package drives the protocol forward. Current initiatives:
+- 🐍 **Python SDK**: Porting `sdk-js` logic to Python for LangChain/AutoGPT integration.
+- 🦀 **Rust SDK**: High-performance implementation for edge compute.
+- 📡 **Cross-chain Settlement**: Integration with Solana (USDC) and TRON (USDT).
 
 ---
 
-## 📦 Publishing to NPM
+## 🛠️ Development & Testing
 
-To publish a new version of the SDK:
-
-1. **Build the project**:
-   ```bash
-   npm run build
-   ```
-2. **Login to NPM** (if not already):
-   ```bash
-   npm login
-   ```
-3. **Publish**:
-   ```bash
-   npm publish --access public
-   ```
+### Run the Demo
+1. **Setup Env**: `cp .env.example .env` and set `CLIENT_PRIVATE_KEY`. If you want to run the merchant demo too, also set `MERCHANT_ADDRESS`.
+2. **Mint Test USDC**: `npx ts-node examples/mint-test-tokens.ts` (Base Sepolia).
+3. **Start Merchant**: `npm run example:server`
+4. **Run Agent**: `npx ts-node examples/agent-client.ts`
 
 ---
 
-## Versioning Guide
-
-PayNode uses two distinct versioning schemes:
+## 📖 Versioning
 
-| Version Type | Description | Current Value |
-| :--- | :--- | :--- |
-| **Protocol Version** | On-chain contracts & core x402 data schema. | `1.4.0` |
-| **SDK/Product Version** | Software package version (npm/SemVer). | `2.2.2` |
+| Component | Current Version |
+| :--- | :--- |
+| **Protocol (x402)** | `v2` |
+| **SDK Implementation** | `v2.4.0` |
 
-> [!NOTE]
-> Protocol Version changes imply breaking changes in verification or contract interfaces. SDK Version changes may include features, fixes, or performance improvements without altering protocol logic.
+> [!IMPORTANT]
+> Protocol and SDK package versioning are not the same thing. Treat the protocol as `x402 v2`, and treat `2.4.0` as the current JS SDK implementation version.
 
 ---
 

package/dist/client.d.ts

@@ -2,15 +2,22 @@ import { ExactEVMPayload } from './types/x402';
 export interface RequestOptions extends RequestInit {
     json?: any;
 }
+export interface AgentClientOptions {
+    rpcUrls?: string | string[];
+    maxRetries?: number;
+    quiet?: boolean;
+}
 export declare class PayNodeAgentClient {
     private wallet;
     private provider;
     private rpcUrls;
     private maxRetries;
+    private options;
     private nonceLock;
     private ERC20_ABI;
     private ROUTER_ABI;
     constructor(privateKey: string, rpcUrls?: string | string[], maxRetries?: number);
+    constructor(privateKey: string, options?: AgentClientOptions);
     private _fetchWithRetry;
     requestGate(url: string, options?: RequestOptions): Promise<Response>;
     private _handleX402V2;

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,eAAe,EAEhB,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,cAAe,SAAQ,WAAW;IACjD,IAAI,CAAC,EAAE,GAAG,CAAC;CACZ;AAID,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,QAAQ,CAA0B;IAC1C,OAAO,CAAC,OAAO,CAAW;IAC1B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,SAAS,CAAoC;IAErD,OAAO,CAAC,SAAS,CAMf;IAEF,OAAO,CAAC,UAAU,CAAsB;gBAE5B,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,GAAG,MAAM,EAAkB,EAAE,UAAU,GAAE,MAAU;YAepF,eAAe;IAoCvB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC;YAuEjE,aAAa;IAkKrB,6BAA6B,CACjC,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,EACb,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,GAC9B,OAAO,CAAC,eAAe,CAAC;IA+CrB,GAAG,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAqBpH,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IA8BrJ,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAE,MAAa,EAAE,OAAO,GAAE,MAAY;;;;;;YAyChH,UAAU;CAYzB"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,eAAe,EAEhB,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,cAAe,SAAQ,WAAW;IACjD,IAAI,CAAC,EAAE,GAAG,CAAC;CACZ;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAKD,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,QAAQ,CAA0B;IAC1C,OAAO,CAAC,OAAO,CAAW;IAC1B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,SAAS,CAAoC;IAErD,OAAO,CAAC,SAAS,CAMf;IAEF,OAAO,CAAC,UAAU,CAAsB;gBAE5B,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,UAAU,CAAC,EAAE,MAAM;gBACpE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB;YAuB9C,eAAe;IAoCvB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC;YAuEjE,aAAa;IAoKrB,6BAA6B,CACjC,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,EACb,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,GAC9B,OAAO,CAAC,eAAe,CAAC;IA+CrB,GAAG,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAqBpH,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IA8BrJ,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAE,MAAa,EAAE,OAAO,GAAE,MAAY;;;;;;YAyChH,UAAU;CAYzB"}

package/dist/client.js

@@ -10,6 +10,7 @@ class PayNodeAgentClient {
     provider;
     rpcUrls;
     maxRetries;
+    options;
     nonceLock = Promise.resolve();
     ERC20_ABI = [
         "function approve(address spender, uint256 value) public returns (bool)",
@@ -19,9 +20,17 @@ class PayNodeAgentClient {
         "function nonces(address owner) view returns (uint256)"
     ];
     ROUTER_ABI = constants_1.PAYNODE_ROUTER_ABI;
-    constructor(privateKey, rpcUrls = constants_1.BASE_RPC_URLS, maxRetries = 3) {
-        this.rpcUrls = Array.isArray(rpcUrls) ? rpcUrls : [rpcUrls];
-        this.maxRetries = maxRetries;
+    constructor(privateKey, arg2, arg3) {
+        if (typeof arg2 === 'object' && !Array.isArray(arg2)) {
+            this.options = { ...arg2 };
+            this.rpcUrls = Array.isArray(this.options.rpcUrls) ? this.options.rpcUrls : (this.options.rpcUrls ? [this.options.rpcUrls] : constants_1.BASE_RPC_URLS);
+            this.maxRetries = this.options.maxRetries ?? 3;
+        }
+        else {
+            this.rpcUrls = Array.isArray(arg2) ? arg2 : (arg2 ? [arg2] : constants_1.BASE_RPC_URLS);
+            this.maxRetries = arg3 ?? 3;
+            this.options = { rpcUrls: this.rpcUrls, maxRetries: this.maxRetries };
+        }
         const configs = this.rpcUrls.map((url, index) => ({
             provider: new ethers_1.ethers.JsonRpcProvider(url, undefined, { staticNetwork: true }),
             priority: index,
@@ -44,7 +53,8 @@ class PayNodeAgentClient {
                 }
                 if (attempt < this.maxRetries - 1) {
                     const backoffMs = Math.pow(2, attempt) * 1000;
-                    console.warn(`⚠️ [PayNode-JS] ${response.status} received. Retrying in ${backoffMs}ms...`);
+                    if (!this.options.quiet)
+                        console.warn(`⚠️ [PayNode-JS] ${response.status} received. Retrying in ${backoffMs}ms...`);
                     await new Promise(resolve => setTimeout(resolve, backoffMs));
                     continue;
                 }
@@ -54,7 +64,8 @@ class PayNodeAgentClient {
                 lastError = error;
                 if (attempt < this.maxRetries - 1) {
                     const backoffMs = Math.pow(2, attempt) * 1000;
-                    console.warn(`⚠️ [PayNode-JS] Request failed: ${error.message}. Retrying in ${backoffMs}ms...`);
+                    if (!this.options.quiet)
+                        console.warn(`⚠️ [PayNode-JS] Request failed: ${error.message}. Retrying in ${backoffMs}ms...`);
                     await new Promise(resolve => setTimeout(resolve, backoffMs));
                 }
             }
@@ -79,7 +90,8 @@ class PayNodeAgentClient {
         try {
             let response = await this._fetchWithRetry(url, fetchOptions);
             if (response.status === 402) {
-                console.log(`💡 [PayNode-JS] 402 Payment Required detected. Analyzing protocol version...`);
+                if (!this.options.quiet)
+                    console.log(`💡 [PayNode-JS] 402 Payment Required detected. Analyzing protocol version...`);
                 const contentType = response.headers.get('content-type');
                 const b64Required = response.headers.get('PAYMENT-REQUIRED') || response.headers.get('X-402-Required');
                 const orderId = response.headers.get('X-402-Order-Id');
@@ -93,7 +105,8 @@ class PayNodeAgentClient {
                         headerBody = JSON.parse(decoded);
                     }
                     catch (e) {
-                        console.debug('⚠️ [PayNode-JS] Failed to parse PAYMENT-REQUIRED header:', e);
+                        if (!this.options.quiet)
+                            console.debug('⚠️ [PayNode-JS] Failed to parse PAYMENT-REQUIRED header:', e);
                     }
                 }
                 if (contentType && contentType.includes('application/json')) {
@@ -107,7 +120,8 @@ class PayNodeAgentClient {
                     body = { ...body, ...headerBody };
                 }
                 if (body && body.x402Version === 2) {
-                    console.log(`🚀 [PayNode-JS] x402 v2 detected. Handling autonomous payment...`);
+                    if (!this.options.quiet)
+                        console.log(`🚀 [PayNode-JS] x402 v2 detected. Handling autonomous payment...`);
                     if (orderId && !body.orderId)
                         body.orderId = orderId;
                     return await this._handleX402V2(url, fetchOptions, body);
@@ -119,7 +133,8 @@ class PayNodeAgentClient {
         catch (error) {
             if (error instanceof errors_1.PayNodeException || error?.name === "PayNodeException")
                 throw error;
-            console.error(`❌ [PayNode-JS] Critical error in requestGate:`, error);
+            if (!this.options.quiet)
+                console.error(`❌ [PayNode-JS] Critical error in requestGate:`, error);
             throw new errors_1.PayNodeException(errors_1.ErrorCode.RpcError, undefined, error);
         }
     }
@@ -132,7 +147,8 @@ class PayNodeAgentClient {
         if (!requirement) {
             throw new errors_1.PayNodeException(errors_1.ErrorCode.TransactionFailed, `No compatible payment requirement found for network ${caip2ChainId}`);
         }
-        console.log(`💡 [PayNode-JS] Selected payment method: ${requirement.type || 'onchain'} on ${requirement.network}`);
+        if (!this.options.quiet)
+            console.log(`💡 [PayNode-JS] Selected payment method: ${requirement.type || 'onchain'} on ${requirement.network}`);
         // 🛡️ Token Whitelist Check (Case-insensitive)
         const chainTokens = constants_1.ACCEPTED_TOKENS[chainId]?.map(t => t.toLowerCase());
         if (chainTokens && !chainTokens.includes(requirement.asset.toLowerCase())) {
@@ -154,6 +170,7 @@ class PayNodeAgentClient {
                 resource: requirements.resource,
                 accepted: {
                     scheme: requirement.scheme,
+                    type: 'eip3009',
                     network: requirement.network,
                     amount: requirement.amount,
                     asset: requirement.asset,
@@ -163,7 +180,7 @@ class PayNodeAgentClient {
                 },
                 payload: authorization,
                 _paynode: {
-                    version: constants_1.SDK_VERSION,
+                    sdkVersion: constants_1.SDK_VERSION,
                     type: 'eip3009',
                     orderId: orderId
                 }
@@ -175,7 +192,8 @@ class PayNodeAgentClient {
             if (!routerAddr) {
                 throw new errors_1.PayNodeException(errors_1.ErrorCode.InternalError, "On-chain payment required but no router address provided.");
             }
-            console.log(`⚡ [PayNode-JS] Executing on-chain payment to ${requirement.payTo}...`);
+            if (!this.options.quiet)
+                console.log(`⚡ [PayNode-JS] Executing on-chain payment to ${requirement.payTo}...`);
             const amount = BigInt(requirement.amount);
             const tokenContract = new ethers_1.ethers.Contract(requirement.asset, this.ERC20_ABI, this.wallet);
             const allowance = await tokenContract.allowance(this.wallet.address, routerAddr);
@@ -185,7 +203,8 @@ class PayNodeAgentClient {
                     txHash = await this.pay(routerAddr, requirement.asset, requirement.payTo, amount, orderId);
                 }
                 catch (e) {
-                    console.warn(`⚠️ [PayNode-JS] Direct pay failed (possibly allowance race), falling back to permit:`, e);
+                    if (!this.options.quiet)
+                        console.warn(`⚠️ [PayNode-JS] Direct pay failed (possibly allowance race), falling back to permit:`, e);
                     txHash = await this.payWithPermit(routerAddr, requirement.asset, requirement.payTo, amount, orderId, requirement.extra?.version || '2');
                 }
             }
@@ -197,6 +216,7 @@ class PayNodeAgentClient {
                 resource: requirements.resource,
                 accepted: {
                     scheme: requirement.scheme,
+                    type: 'onchain',
                     network: requirement.network,
                     amount: requirement.amount,
                     asset: requirement.asset,
@@ -207,7 +227,7 @@ class PayNodeAgentClient {
                 },
                 payload: { txHash },
                 _paynode: {
-                    version: constants_1.SDK_VERSION,
+                    sdkVersion: constants_1.SDK_VERSION,
                     type: 'onchain',
                     orderId: orderId
                 }
@@ -248,14 +268,17 @@ class PayNodeAgentClient {
                 }
                 const settleData = JSON.parse(decoded);
                 if (settleData.success) {
-                    console.log(`✅ [PayNode-JS] Settlement confirmed: ${settleData.transaction}`);
+                    if (!this.options.quiet)
+                        console.log(`✅ [PayNode-JS] Settlement confirmed: ${settleData.transaction}`);
                 }
                 else {
-                    console.warn(`⚠️ [PayNode-JS] Settlement failed: ${settleData.errorReason || 'Unknown error'}`);
+                    if (!this.options.quiet)
+                        console.warn(`⚠️ [PayNode-JS] Settlement failed: ${settleData.errorReason || 'Unknown error'}`);
                 }
             }
             catch (e) {
-                console.warn(`⚠️ [PayNode-JS] Failed to parse settlement response:`, e);
+                if (!this.options.quiet)
+                    console.warn(`⚠️ [PayNode-JS] Failed to parse settlement response:`, e);
             }
         }
         return retryResponse;

package/dist/constants.d.ts

@@ -6,7 +6,8 @@ export declare const BASE_USDC_ADDRESS_SANDBOX = "0x65c088EfBDB0E03185Dbe8e258Ad
 export declare const PROTOCOL_TREASURY = "0x598bF63F5449876efafa7b36b77Deb2070621C0E";
 export declare const PROTOCOL_FEE_BPS = 100;
 export declare const MIN_PAYMENT_AMOUNT: bigint;
-export declare const SDK_VERSION = "2.2.2";
+export declare const PROTOCOL_VERSION = 2;
+export declare const SDK_VERSION = "2.4.0";
 export declare const BASE_RPC_URLS: string[];
 export declare const BASE_RPC_URLS_SANDBOX: string[];
 export declare const ACCEPTED_TOKENS: Record<number, string[]>;

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C,eAAO,MAAM,sBAAsB,+CAA+C,CAAC;AACnF,eAAO,MAAM,8BAA8B,+CAA+C,CAAC;AAC3F,eAAO,MAAM,iBAAiB,+CAA+C,CAAC;AAC9E,eAAO,MAAM,yBAAyB,+CAA+C,CAAC;AACtF,eAAO,MAAM,iBAAiB,+CAA+C,CAAC;AAC9E,eAAO,MAAM,gBAAgB,MAAM,CAAC;AACpC,eAAO,MAAM,kBAAkB,QAAe,CAAC;AAC/C,eAAO,MAAM,WAAW,UAAU,CAAC;AAEnC,eAAO,MAAM,aAAa,UAAmF,CAAC;AAC9G,eAAO,MAAM,qBAAqB,UAA0E,CAAC;AAE7G,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAGpD,CAAC;AAEF,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAA25K,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C,eAAO,MAAM,sBAAsB,+CAA+C,CAAC;AACnF,eAAO,MAAM,8BAA8B,+CAA+C,CAAC;AAC3F,eAAO,MAAM,iBAAiB,+CAA+C,CAAC;AAC9E,eAAO,MAAM,yBAAyB,+CAA+C,CAAC;AACtF,eAAO,MAAM,iBAAiB,+CAA+C,CAAC;AAC9E,eAAO,MAAM,gBAAgB,MAAM,CAAC;AACpC,eAAO,MAAM,kBAAkB,QAAe,CAAC;AAC/C,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAClC,eAAO,MAAM,WAAW,UAAU,CAAC;AAEnC,eAAO,MAAM,aAAa,UAAmF,CAAC;AAC9G,eAAO,MAAM,qBAAqB,UAA0E,CAAC;AAE7G,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAGpD,CAAC;AAEF,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAA25K,CAAC"}

package/dist/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PAYNODE_ROUTER_ABI = exports.ACCEPTED_TOKENS = exports.BASE_RPC_URLS_SANDBOX = exports.BASE_RPC_URLS = exports.SDK_VERSION = exports.MIN_PAYMENT_AMOUNT = exports.PROTOCOL_FEE_BPS = exports.PROTOCOL_TREASURY = exports.BASE_USDC_ADDRESS_SANDBOX = exports.BASE_USDC_ADDRESS = exports.PAYNODE_ROUTER_ADDRESS_SANDBOX = exports.PAYNODE_ROUTER_ADDRESS = void 0;
+exports.PAYNODE_ROUTER_ABI = exports.ACCEPTED_TOKENS = exports.BASE_RPC_URLS_SANDBOX = exports.BASE_RPC_URLS = exports.SDK_VERSION = exports.PROTOCOL_VERSION = exports.MIN_PAYMENT_AMOUNT = exports.PROTOCOL_FEE_BPS = exports.PROTOCOL_TREASURY = exports.BASE_USDC_ADDRESS_SANDBOX = exports.BASE_USDC_ADDRESS = exports.PAYNODE_ROUTER_ADDRESS_SANDBOX = exports.PAYNODE_ROUTER_ADDRESS = void 0;
 /** Generated by meta/scripts/sync-config.py */
 exports.PAYNODE_ROUTER_ADDRESS = "0x4A73696ccF76E7381b044cB95127B3784369Ed63";
 exports.PAYNODE_ROUTER_ADDRESS_SANDBOX = "0x24cD8b68aaC209217ff5a6ef1Bf55a59f2c8Ca6F";
@@ -9,7 +9,8 @@ exports.BASE_USDC_ADDRESS_SANDBOX = "0x65c088EfBDB0E03185Dbe8e258Ad0cf4Ab7946b0"
 exports.PROTOCOL_TREASURY = "0x598bF63F5449876efafa7b36b77Deb2070621C0E";
 exports.PROTOCOL_FEE_BPS = 100;
 exports.MIN_PAYMENT_AMOUNT = BigInt(1000);
-exports.SDK_VERSION = "2.2.2";
+exports.PROTOCOL_VERSION = 2;
+exports.SDK_VERSION = "2.4.0";
 exports.BASE_RPC_URLS = ["https://mainnet.base.org", "https://base.meowrpc.com", "https://1rpc.io/base"];
 exports.BASE_RPC_URLS_SANDBOX = ["https://sepolia.base.org", "https://base-sepolia-rpc.publicnode.com"];
 exports.ACCEPTED_TOKENS = {

package/dist/index.d.ts

@@ -8,4 +8,6 @@ export * from './constants';
 export * from './utils/payload';
 export * from './types/x402';
 export { ethers } from 'ethers';
+export * from './merchant';
+export * from './merchant/types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -26,3 +26,5 @@ __exportStar(require("./utils/payload"), exports);
 __exportStar(require("./types/x402"), exports);
 var ethers_1 = require("ethers");
 Object.defineProperty(exports, "ethers", { enumerable: true, get: function () { return ethers_1.ethers; } });
+__exportStar(require("./merchant"), exports);
+__exportStar(require("./merchant/types"), exports);

package/dist/merchant/index.d.ts

@@ -0,0 +1,37 @@
+import { MerchantConfig, MerchantMiddlewareOptions, ApiManifest } from './types';
+import { PayNodeMiddlewareOptions } from '../middleware/x402';
+/**
+ * PayNodeMerchant: The high-level SDK class for Merchant Integration.
+ */
+export declare class PayNodeMerchant {
+    private config;
+    constructor(config: MerchantConfig);
+    /**
+     * Registers or syncs the API manifest with the PayNode Market.
+     * This ensures the market shows the correct price and input schema.
+     */
+    sync(manifest: ApiManifest): Promise<boolean>;
+    /**
+     * Returns a unified middleware that handles:
+     * 1. Market Proxy (Strict Signature Check + Body Unwrap)
+     * 2. Auto-Discovery (Market Sync Probe)
+     * 3. (Optional) Direct X402 payment
+     */
+    middleware(options?: MerchantMiddlewareOptions & Partial<PayNodeMiddlewareOptions>): (req: import("express").Request | any, res: import("express").Response | any, next: import("express").NextFunction) => Promise<any>;
+    /**
+     * Manual verification for Next.js or other non-Express environments.
+     * Extracts headers and verifies signature. Returns the unwrapped body and context.
+     */
+    verify(req: any): Promise<{
+        isValid: boolean;
+        error: string;
+        body?: undefined;
+        paynodeContext?: undefined;
+    } | {
+        isValid: boolean;
+        body: any;
+        paynodeContext: any;
+        error?: undefined;
+    }>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/merchant/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/merchant/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,yBAAyB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEjF,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAG9D;;GAEG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAiB;gBAEnB,MAAM,EAAE,cAAc;IAOlC;;;OAGG;IACG,IAAI,CAAC,QAAQ,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IA4BnD;;;;;OAKG;IACH,UAAU,CAAC,OAAO,GAAE,yBAAyB,GAAG,OAAO,CAAC,wBAAwB,CAAM;IAOtF;;;OAGG;IACG,MAAM,CAAC,GAAG,EAAE,GAAG;;;;;;;;;;;CAiDtB"}

package/dist/merchant/index.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PayNodeMerchant = void 0;
+const middleware_1 = require("./middleware");
+const signature_1 = require("../utils/signature");
+/**
+ * PayNodeMerchant: The high-level SDK class for Merchant Integration.
+ */
+class PayNodeMerchant {
+    config;
+    constructor(config) {
+        this.config = {
+            marketUrl: 'https://mk.paynode.dev',
+            ...config
+        };
+    }
+    /**
+     * Registers or syncs the API manifest with the PayNode Market.
+     * This ensures the market shows the correct price and input schema.
+     */
+    async sync(manifest) {
+        if (!this.config.quiet)
+            console.log(`[PayNode-SDK] Syncing API manifest for ${manifest.slug} to ${this.config.marketUrl}`);
+        try {
+            const response = await fetch(`${this.config.marketUrl}/api/v1/merchant/apis`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    ...manifest,
+                    gateway_url: manifest.slug
+                })
+            });
+            const result = await response.json();
+            if (response.ok && result.success) {
+                if (!this.config.quiet)
+                    console.log(`[PayNode-SDK] Successfully synced ${manifest.slug}. Status: ${result.api_id}`);
+                return true;
+            }
+            else {
+                if (!this.config.quiet)
+                    console.warn(`[PayNode-SDK] Sync failed for ${manifest.slug}: ${result.error || response.statusText}`);
+                return false;
+            }
+        }
+        catch (err) {
+            if (!this.config.quiet)
+                console.error(`[PayNode-SDK] Network error during sync for ${manifest.slug}:`, err.message);
+            return false;
+        }
+    }
+    /**
+     * Returns a unified middleware that handles:
+     * 1. Market Proxy (Strict Signature Check + Body Unwrap)
+     * 2. Auto-Discovery (Market Sync Probe)
+     * 3. (Optional) Direct X402 payment
+     */
+    middleware(options = {}) {
+        return (0, middleware_1.createMerchantMiddleware)(this.config, {
+            price: options.manifest?.price_per_call || '0.01',
+            ...options
+        });
+    }
+    /**
+     * Manual verification for Next.js or other non-Express environments.
+     * Extracts headers and verifies signature. Returns the unwrapped body and context.
+     */
+    async verify(req) {
+        const getHeader = (name) => {
+            if (typeof req.getHeader === 'function')
+                return req.getHeader(name);
+            if (typeof req.get === 'function')
+                return req.get(name);
+            if (req.headers?.get && typeof req.headers.get === 'function')
+                return req.headers.get(name);
+            if (req.headers)
+                return req.headers[name.toLowerCase()] || req.headers[name];
+            return null;
+        };
+        const signature = getHeader('X-PayNode-Signature');
+        const timestamp = getHeader('X-PayNode-Timestamp');
+        const requestId = getHeader('X-PayNode-Request-Id') || getHeader('X-402-Order-Id') || getHeader('PAYMENT-SIGNATURE'); // Try fallback
+        const isValid = (0, signature_1.verifyMarketSignature)({
+            signature,
+            orderId: requestId,
+            timestamp,
+            sharedSecret: this.config.sharedSecret,
+        });
+        if (!isValid) {
+            return { isValid: false, error: 'Invalid PayNode Market Signature' };
+        }
+        // Handle Body Unwrap if it's a JSON body
+        let body = {};
+        try {
+            if (typeof req.json === 'function') {
+                body = await req.json();
+            }
+            else {
+                body = req.body;
+            }
+        }
+        catch (e) { }
+        let paynodeContext = { orderId: requestId };
+        if (body && body.payload && typeof body.payload === 'object') {
+            paynodeContext = {
+                ...paynodeContext,
+                txHash: getHeader('X-PayNode-Transaction-Hash') || body.tx_hash,
+                amount: getHeader('X-PayNode-Amount') || body.amount,
+                network: getHeader('X-PayNode-Network') || body.network,
+                chainId: getHeader('X-PayNode-Chain-Id') || body.chain_id?.toString(),
+            };
+            body = body.payload;
+        }
+        return { isValid: true, body, paynodeContext };
+    }
+}
+exports.PayNodeMerchant = PayNodeMerchant;

package/dist/merchant/middleware.d.ts

@@ -0,0 +1,14 @@
+import { Request, Response, NextFunction } from 'express';
+import { MerchantConfig, MerchantMiddlewareOptions } from './types';
+import { PayNodeMiddlewareOptions } from '../middleware/x402';
+/**
+ * Unified PayNode Merchant Middleware
+ * Handles:
+ * 1. Market Proxy (Strict HMAC Signature + Body Unwrapping)
+ * 2. Discovery Probes (Auto-respond with API Manifest)
+ *
+ * Note: Standalone direct X402 payment flow should be handled
+ * via x402Gate component.
+ */
+export declare const createMerchantMiddleware: (config: MerchantConfig, options: MerchantMiddlewareOptions & PayNodeMiddlewareOptions) => (req: Request | any, res: Response | any, next: NextFunction) => Promise<any>;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/merchant/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/merchant/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAC;AAEpE,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAE9D;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,GAAI,QAAQ,cAAc,EAAE,SAAS,yBAAyB,GAAG,wBAAwB,MAG9G,KAAK,OAAO,GAAG,GAAG,EAAE,KAAK,QAAQ,GAAG,GAAG,EAAE,MAAM,YAAY,iBAiE1E,CAAC"}

package/dist/merchant/middleware.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMerchantMiddleware = void 0;
+const signature_1 = require("../utils/signature");
+/**
+ * Unified PayNode Merchant Middleware
+ * Handles:
+ * 1. Market Proxy (Strict HMAC Signature + Body Unwrapping)
+ * 2. Discovery Probes (Auto-respond with API Manifest)
+ *
+ * Note: Standalone direct X402 payment flow should be handled
+ * via x402Gate component.
+ */
+const createMerchantMiddleware = (config, options) => {
+    const { manifest } = options;
+    return async (req, res, next) => {
+        // 1. Check for Market Proxy Headers
+        const signature = req.header('X-PayNode-Signature');
+        const timestamp = req.header('X-PayNode-Timestamp');
+        const requestId = req.header('X-PayNode-Request-Id') || req.header('X-402-Order-Id');
+        const isDiscovery = req.header('X-PayNode-Discovery') === 'true';
+        if (signature && requestId && timestamp) {
+            // ✅ Verify Signature from PayNode Market
+            const isValid = (0, signature_1.verifyMarketSignature)({
+                signature,
+                orderId: requestId,
+                timestamp,
+                sharedSecret: config.sharedSecret,
+            });
+            if (!isValid) {
+                if (!config.quiet)
+                    console.error(`[PayNode-SDK] Invalid Market Proxy Signature for request ${requestId}`);
+                return res.status(401).json({ error: 'unauthorized', message: 'PayNode Market Signature verification failed.' });
+            }
+            // --- Scene A: Discovery Probe ---
+            if (isDiscovery) {
+                return res.status(200).json({
+                    status: 'DISCOVERED',
+                    x402Version: 2,
+                    manifest: manifest || {},
+                    last_synced: new Date().toISOString()
+                });
+            }
+            // --- Scene B: Proxy Flow - Body Unwrapping ---
+            // The Market Proxy wraps original body in { payload: { ... } }
+            if (req.body && req.body.payload && typeof req.body.payload === 'object') {
+                const metadata = { ...req.body };
+                delete metadata.payload;
+                // Enrich request context with Proxy details
+                req.paynode = {
+                    orderId: requestId,
+                    txHash: req.header('X-PayNode-Transaction-Hash') || req.body.tx_hash,
+                    amount: req.header('X-PayNode-Amount') || req.body.amount,
+                    network: req.header('X-PayNode-Network') || req.body.network,
+                    chainId: req.header('X-PayNode-Chain-Id') || req.body.chain_id?.toString(),
+                    proxyMetadata: metadata
+                };
+                // Transparently Unwrap Body
+                req.body = req.body.payload;
+            }
+            else {
+                // Direct call via Proxy (unlikely for POST, but possible for some flows)
+                req.paynode = { orderId: requestId };
+            }
+            return next();
+        }
+        // 2. Scene C: Direct Agent Call (Rejected)
+        // PayNodeMerchant component REQUIRES Market Proxy to ensure protocol consistency and fee collection.
+        // Use x402Gate directly for standalone/direct 402 integration.
+        return res.status(403).json({
+            error: 'forbidden',
+            message: 'PayNode Market Auth required. This API must be accessed via PayNode Market Proxy for verification.'
+        });
+    };
+};
+exports.createMerchantMiddleware = createMerchantMiddleware;

package/dist/merchant/types.d.ts

@@ -0,0 +1,27 @@
+export interface MerchantConfig {
+    sharedSecret: string;
+    marketUrl?: string;
+    quiet?: boolean;
+}
+export interface ApiManifest {
+    slug: string;
+    name: string;
+    description: string;
+    price_per_call: string;
+    currency?: string;
+    network?: 'mainnet' | 'testnet';
+    input_schema?: Record<string, any>;
+    sample_response?: Record<string, any>;
+}
+export interface PayNodeRequestContext {
+    orderId: string;
+    txHash?: string;
+    payer?: string;
+    amount?: string;
+    network?: string;
+    chainId?: string;
+}
+export interface MerchantMiddlewareOptions {
+    manifest?: Partial<ApiManifest>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/merchant/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/merchant/types.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;CACjC"}

package/dist/merchant/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/middleware/x402.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"x402.d.ts","sourceRoot":"","sources":["../../src/middleware/x402.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAG1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAcxD,MAAM,WAAW,wBAAwB;IACvC,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,KAAK,MAAM,CAAC;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,eAAO,MAAM,QAAQ,GAAI,SAAS,wBAAwB,MA6B1C,KAAK,OAAO,GAAG,GAAG,EAAE,KAAK,QAAQ,GAAG,GAAG,EAAE,MAAM,YAAY,iBA0J1E,CAAC"}
+{"version":3,"file":"x402.d.ts","sourceRoot":"","sources":["../../src/middleware/x402.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAG1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAgBxD,MAAM,WAAW,wBAAwB;IACvC,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,KAAK,MAAM,CAAC;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,eAAO,MAAM,QAAQ,GAAI,SAAS,wBAAwB,MA6B1C,KAAK,OAAO,GAAG,GAAG,EAAE,KAAK,QAAQ,GAAG,GAAG,EAAE,MAAM,YAAY,iBAkK1E,CAAC"}

package/dist/middleware/x402.js

@@ -40,7 +40,7 @@ const x402Gate = (options) => {
                 return req.headers[name.toLowerCase()] || req.headers[name];
             return null;
         };
-        const v2PayloadHeader = getHeader('PAYMENT-SIGNATURE') || getHeader('X-402-Payload');
+        const v2PayloadHeader = getHeader('PAYMENT-SIGNATURE') || getHeader('X-402-Payload'); // COMPAT: X-402-Payload is a legacy alias for PAYMENT-SIGNATURE
         let orderId = getHeader('X-402-Order-Id');
         if (!orderId) {
             orderId = (options.generateOrderId || defaultOrderIdGen)(req);
@@ -63,23 +63,29 @@ const x402Gate = (options) => {
                         inferredType = "onchain";
                     }
                     unifiedPayload = {
-                        version: "2.2.2",
+                        x402Version: constants_1.PROTOCOL_VERSION,
                         type: parsed._paynode?.type || inferredType,
                         orderId: internalOrderId,
                         router: parsed.accepted?.router,
-                        payload: parsed.payload
+                        payload: parsed.payload,
+                        _paynode: {
+                            sdkVersion: constants_1.SDK_VERSION
+                        }
                     };
                     orderId = internalOrderId;
                 }
-                else if (typeof parsed.version === 'string' && (parsed.version.startsWith("2.3") || parsed.version.startsWith("2.2"))) {
-                    // Legacy PayNode format
-                    unifiedPayload = parsed;
-                    if (unifiedPayload?.orderId) {
-                        orderId = unifiedPayload.orderId;
-                    }
-                    else if (unifiedPayload?.order_id) {
-                        orderId = unifiedPayload.order_id;
-                    }
+                else if (typeof (parsed.version || parsed.x402Version) === 'string' || typeof parsed.version === 'string') {
+                    // Legacy PayNode format or old x402 V2 drafts
+                    unifiedPayload = {
+                        x402Version: constants_1.PROTOCOL_VERSION,
+                        type: parsed.type || (parsed.payload?.txHash ? "onchain" : "eip3009"),
+                        orderId: parsed.orderId || parsed.order_id || orderId || `legacy_${Date.now()}`,
+                        payload: parsed.payload,
+                        _paynode: {
+                            sdkVersion: constants_1.SDK_VERSION
+                        }
+                    };
+                    orderId = unifiedPayload.orderId;
                 }
             }
             catch (e) {
@@ -104,7 +110,7 @@ const x402Gate = (options) => {
                 const b64Response = Buffer.from(JSON.stringify(settleResponse)).toString('base64');
                 if (res.set) {
                     res.set('PAYMENT-RESPONSE', b64Response);
-                    res.set('X-PAYMENT-RESPONSE', b64Response); // Compatibility
+                    res.set('X-PAYMENT-RESPONSE', b64Response); // COMPAT (legacy): deprecated alias for PAYMENT-RESPONSE
                 }
                 req.paynode = { unifiedPayload, orderId };
                 return next();
@@ -120,7 +126,7 @@ const x402Gate = (options) => {
                 const b64Response = Buffer.from(JSON.stringify(settleResponse)).toString('base64');
                 if (res.set) {
                     res.set('PAYMENT-RESPONSE', b64Response);
-                    res.set('X-PAYMENT-RESPONSE', b64Response); // Compatibility
+                    res.set('X-PAYMENT-RESPONSE', b64Response); // COMPAT (legacy): deprecated alias for PAYMENT-RESPONSE
                 }
                 return res.status(403).json({
                     error: "Forbidden",
@@ -131,13 +137,14 @@ const x402Gate = (options) => {
         }
         // No valid payment found, return 402 with appropriate headers
         const v2Response = {
-            x402Version: 2,
+            x402Version: constants_1.PROTOCOL_VERSION,
             error: "Payment Required by PayNode",
             resource: {
                 url: req.protocol + '://' + req.get('host') + (req.originalUrl || req.url),
                 description: options.description || "Protected Resource",
                 mimeType: getHeader('accept') || "application/json"
             },
+            orderId: orderId || undefined,
             accepts: [
                 {
                     scheme: "exact",
@@ -167,7 +174,7 @@ const x402Gate = (options) => {
         const b64Required = Buffer.from(JSON.stringify(v2Response)).toString('base64');
         if (res.set) {
             res.set('PAYMENT-REQUIRED', b64Required);
-            res.set('X-402-Required', b64Required);
+            res.set('X-402-Required', b64Required); // COMPAT (legacy): deprecated alias for PAYMENT-REQUIRED
             res.set('X-402-Order-Id', orderId);
         }
         return res.status(402).json(v2Response);

package/dist/types/x402.d.ts

@@ -4,6 +4,19 @@ export interface ResourceInfo {
     description?: string;
     mimeType?: string;
 }
+/**
+ * PaymentRequirements describes a single payment option returned
+ * in the `accepts[]` array of a 402 challenge.
+ *
+ * NOTE: The `orderId` (legacy) is DEPRECATED. All SDKs MUST read
+ * and write the request ID exclusively via the
+ * `X-402-Order-Id` HTTP header. This field exists only for
+ * backward compatibility with paynode-js <= 2.2.x and must
+ * not be used by new implementations.
+ *
+ * Protocol: x402 v2
+ * Canonical orderId transport: X-402-Order-Id header
+ */
 export interface PaymentRequirements {
     scheme: string;
     type?: "onchain" | "eip3009";
@@ -12,6 +25,7 @@ export interface PaymentRequirements {
     asset: string;
     payTo: string;
     router?: string;
+    /** @deprecated Use X-402-Order-Id header exclusively. Legacy alias only. */
     orderId?: string;
     maxTimeoutSeconds: number;
     extra?: Record<string, any>;
@@ -37,7 +51,7 @@ export interface PaymentPayload {
     };
     extensions?: Record<string, any>;
     _paynode?: {
-        version: string;
+        sdkVersion: string;
         type: "onchain" | "eip3009";
         orderId: string;
     };
@@ -67,7 +81,7 @@ export interface VerifyResponse {
     payer?: string;
 }
 export interface UnifiedPaymentPayload {
-    version: "2.2.2";
+    x402Version: X402Version;
     type: "onchain" | "eip3009";
     orderId: string;
     router?: string;
@@ -76,6 +90,9 @@ export interface UnifiedPaymentPayload {
         signature?: string;
         authorization?: any;
     } | ExactEVMPayload;
+    _paynode?: {
+        sdkVersion: string;
+    };
 }
 export interface SupportedKind {
     x402Version: X402Version;

package/dist/types/x402.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"x402.d.ts","sourceRoot":"","sources":["../../src/types/x402.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"x402.d.ts","sourceRoot":"","sources":["../../src/types/x402.ts"],"names":[],"mappings":"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"}

package/dist/utils/payload.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"payload.d.ts","sourceRoot":"","sources":["../../src/utils/payload.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAEtD,qBAAa,iBAAiB;IAC5B;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,qBAAqB;CAuCtF"}
+{"version":3,"file":"payload.d.ts","sourceRoot":"","sources":["../../src/utils/payload.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAGtD,qBAAa,iBAAiB;IAC5B;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,qBAAqB;CA8CtF"}

package/dist/utils/payload.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.X402PayloadHelper = void 0;
+const constants_1 = require("../constants");
 class X402PayloadHelper {
     /**
      * Normalizes a raw payment payload (usually from PAYMENT-SIGNATURE or X-402-Payload headers)
@@ -29,18 +30,25 @@ class X402PayloadHelper {
                     inferredType = "onchain";
                 }
                 return {
-                    version: "2.2.2",
+                    x402Version: 2,
                     type: parsed._paynode?.type || inferredType,
                     orderId: parsed._paynode?.orderId || fallbackOrderId || "",
                     router: parsed.accepted?.router || parsed.router,
-                    payload: parsed.payload
+                    payload: parsed.payload,
+                    _paynode: {
+                        sdkVersion: constants_1.SDK_VERSION
+                    }
                 };
             }
             // 2. Handle Legacy or already Unified Format
             if (typeof parsed.version === 'string' && (parsed.version.startsWith("2.2") || parsed.version.startsWith("2.3"))) {
                 return {
                     ...parsed,
-                    orderId: parsed.orderId || parsed.order_id || fallbackOrderId || ""
+                    x402Version: parsed.x402Version || 2,
+                    orderId: parsed.orderId || parsed.order_id || fallbackOrderId || "",
+                    _paynode: parsed._paynode || {
+                        sdkVersion: parsed.version
+                    }
                 };
             }
             // 3. Fallback for raw internal format

package/dist/utils/signature.d.ts

@@ -0,0 +1,13 @@
+export interface SignatureContext {
+    signature: string;
+    orderId: string;
+    timestamp: string;
+    sharedSecret: string;
+    now?: number;
+    driftWindow?: number;
+}
+/**
+ * Verifies the HMAC-SHA256 signature from PayNode Market Proxy
+ */
+export declare function verifyMarketSignature(context: SignatureContext): boolean;
+//# sourceMappingURL=signature.d.ts.map

package/dist/utils/signature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.d.ts","sourceRoot":"","sources":["../../src/utils/signature.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAuCxE"}

package/dist/utils/signature.js

@@ -0,0 +1,42 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyMarketSignature = verifyMarketSignature;
+const crypto_1 = __importDefault(require("crypto"));
+/**
+ * Verifies the HMAC-SHA256 signature from PayNode Market Proxy
+ */
+function verifyMarketSignature(context) {
+    const { signature, orderId, timestamp, sharedSecret } = context;
+    if (!signature || !orderId || !timestamp || !sharedSecret) {
+        return false;
+    }
+    // Check for timestamp drift (default 5 minutes to prevent replay)
+    const tsDate = new Date(timestamp);
+    const checkTime = context.now || Date.now();
+    const driftWindow = context.driftWindow || 5 * 60 * 1000;
+    // Accept both ISO string and milliseconds
+    const tsMs = isNaN(tsDate.getTime()) ? parseInt(timestamp) : tsDate.getTime();
+    if (isNaN(tsMs))
+        return false;
+    const drift = Math.abs(checkTime - tsMs);
+    if (drift > driftWindow) {
+        if (driftWindow > 0) {
+            console.warn(`[PayNode-SDK] Signature timestamp drift too high: ${drift}ms`);
+            return false;
+        }
+    }
+    const expectedSig = crypto_1.default
+        .createHmac('sha256', sharedSecret)
+        .update(`${orderId}:${timestamp}`)
+        .digest('hex');
+    // Use constant-time comparison to prevent timing attacks
+    try {
+        return crypto_1.default.timingSafeEqual(Buffer.from(signature, 'hex'), Buffer.from(expectedSig, 'hex'));
+    }
+    catch (e) {
+        return false;
+    }
+}

package/dist/utils/verifier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verifier.d.ts","sourceRoot":"","sources":["../../src/utils/verifier.ts"],"names":[],"mappings":"AACA,OAAO,EAAa,gBAAgB,EAAE,MAAM,WAAW,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAA0B,MAAM,eAAe,CAAC;AAEzE,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAEvE,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,oGAAoG;IACpG,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAqC;IACrD,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,KAAK,CAAC,CAAmB;IACjC,OAAO,CAAC,cAAc,CAAc;gBAExB,MAAM,EAAE,qBAAqB;IAyCzC,OAAO,CAAC,MAAM,CAAC,UAAU,CAEvB;IAEI,MAAM,CACV,cAAc,EAAE,qBAAqB,EACrC,QAAQ,EAAE,eAAe,EACzB,KAAK,CAAC,EAAE,GAAG,GACV,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IA8BpE,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IA4ElI;;;OAGG;IACG,+BAA+B,CACnC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,eAAe,EACxB,QAAQ,EAAE;QACR,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;KACjC,EACD,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,GAC9B,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CA0G3E"}
+{"version":3,"file":"verifier.d.ts","sourceRoot":"","sources":["../../src/utils/verifier.ts"],"names":[],"mappings":"AAEA,OAAO,EAAa,gBAAgB,EAAE,MAAM,WAAW,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAA0B,MAAM,eAAe,CAAC;AAEzE,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAEvE,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,oGAAoG;IACpG,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAqC;IACrD,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,KAAK,CAAC,CAAmB;IACjC,OAAO,CAAC,cAAc,CAAc;gBAExB,MAAM,EAAE,qBAAqB;IAyCzC,OAAO,CAAC,MAAM,CAAC,UAAU,CAEvB;IAEI,MAAM,CACV,cAAc,EAAE,qBAAqB,EACrC,QAAQ,EAAE,eAAe,EACzB,KAAK,CAAC,EAAE,GAAG,GACV,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IA8BpE,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAqFlI;;;OAGG;IACG,+BAA+B,CACnC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,eAAe,EACxB,QAAQ,EAAE;QACR,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;KACjC,EACD,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,GAC9B,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CA+G3E"}

package/dist/utils/verifier.js

@@ -1,7 +1,11 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PayNodeVerifier = void 0;
 const ethers_1 = require("ethers");
+const crypto_1 = __importDefault(require("crypto"));
 const errors_1 = require("../errors");
 const idempotency_1 = require("./idempotency");
 const constants_1 = require("../constants");
@@ -108,10 +112,16 @@ class PayNodeVerifier {
                     const parsed = router.parseLog(log);
                     if (parsed && parsed.name === 'PaymentReceived') {
                         const { merchant, token, amount, orderId, payer } = parsed.args;
-                        const isMerchantMatch = merchant.toLowerCase() === expected.merchantAddress.toLowerCase();
-                        const isTokenMatch = token.toLowerCase() === expected.tokenAddress.toLowerCase();
+                        const merchantBuf = Buffer.from(merchant.toLowerCase().replace('0x', ''), 'hex');
+                        const expectedMerchantBuf = Buffer.from(expected.merchantAddress.toLowerCase().replace('0x', ''), 'hex');
+                        const isMerchantMatch = merchantBuf.length === expectedMerchantBuf.length && crypto_1.default.timingSafeEqual(merchantBuf, expectedMerchantBuf);
+                        const tokenBuf = Buffer.from(token.toLowerCase().replace('0x', ''), 'hex');
+                        const expectedTokenBuf = Buffer.from(expected.tokenAddress.toLowerCase().replace('0x', ''), 'hex');
+                        const isTokenMatch = tokenBuf.length === expectedTokenBuf.length && crypto_1.default.timingSafeEqual(tokenBuf, expectedTokenBuf);
                         const isAmountMatch = BigInt(amount) >= BigInt(expected.amount);
-                        const isOrderMatch = orderId === targetOrderId;
+                        const orderIdBuf = Buffer.from(orderId.replace('0x', ''), 'hex');
+                        const targetOrderIdBuf = Buffer.from(targetOrderId.replace('0x', ''), 'hex');
+                        const isOrderMatch = orderIdBuf.length === targetOrderIdBuf.length && crypto_1.default.timingSafeEqual(orderIdBuf, targetOrderIdBuf);
                         if (isMerchantMatch && isTokenMatch && isAmountMatch) {
                             if (isOrderMatch) {
                                 validEventFound = true;
@@ -169,7 +179,9 @@ class PayNodeVerifier {
             const expectedValue = BigInt(expected.value);
             const payloadValue = BigInt(value);
             // 2. 基础字段与金额校验 (防粉尘攻击)
-            if (to.toLowerCase() !== expected.to.toLowerCase()) {
+            const toBuf = Buffer.from(to.toLowerCase().replace('0x', ''), 'hex');
+            const expectedToBuf = Buffer.from(expected.to.toLowerCase().replace('0x', ''), 'hex');
+            if (toBuf.length !== expectedToBuf.length || !crypto_1.default.timingSafeEqual(toBuf, expectedToBuf)) {
                 return { isValid: false, error: new errors_1.PayNodeException(errors_1.ErrorCode.InvalidReceipt, "Recipient mismatch") };
             }
             if (payloadValue < expectedValue) {
@@ -202,7 +214,9 @@ class PayNodeVerifier {
                 ]
             };
             const recoveredAddress = ethers_1.ethers.verifyTypedData(domain, types, authorization, signature);
-            if (recoveredAddress.toLowerCase() !== from.toLowerCase()) {
+            const recoveredBuf = Buffer.from(recoveredAddress.toLowerCase().replace('0x', ''), 'hex');
+            const fromBuf = Buffer.from(from.toLowerCase().replace('0x', ''), 'hex');
+            if (recoveredBuf.length !== fromBuf.length || !crypto_1.default.timingSafeEqual(recoveredBuf, fromBuf)) {
                 return { isValid: false, error: new errors_1.PayNodeException(errors_1.ErrorCode.InvalidReceipt, "Invalid signature: recovered address mismatch") };
             }
             // 4. 内存幂等性校验 (防高频重放)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paynodelabs/sdk-js",
-  "version": "2.2.3",
+  "version": "2.4.0",
   "description": "The official JavaScript/TypeScript SDK for PayNode x402 protocol on Base L2.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",