PayNode Master SDK (JS/TS)

[!NOTE] Compatibility policy & legacy header aliases are documented in COMPATIBILITY.md.

The Master SDK for the PayNode Protocol. 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. The protocol source of truth lives in meta/SPEC.md.

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.

🏗️ Reference Implementation Status

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

Installation

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).

import { PayNodeAgentClient } from "@paynodelabs/sdk-js";

// 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, settles USDC, and retries the request
  const response = await client.requestGate("https://api.merchant.com/premium-data");
  const result = await response.json();
  console.log("Success:", result);
}
main();

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.

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 });
  }
);

🚀 Key Features

• 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.

🧭 Roadmap & Ecosystem

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).

🛠️ Development & Testing

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

| Component | Current Version | | :--- | :--- | | Protocol (x402) | v2 | | SDK Implementation | v2.4.0 |

[!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.

Built for the Autonomous AI Economy by PayNodeLabs.