nullpath-mcp 1.2.0 → 1.3.0

package/.github/workflows/release.yml

@@ -0,0 +1,43 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+  id-token: write
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm test
+
+      - name: Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GH_PAT }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npx semantic-release

package/.releaserc.json

@@ -0,0 +1,9 @@
+{
+  "branches": ["main"],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/npm",
+    "@semantic-release/github"
+  ]
+}

package/README.md

@@ -3,13 +3,13 @@
 [![npm version](https://img.shields.io/npm/v/nullpath-mcp.svg)](https://www.npmjs.com/package/nullpath-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Discover and pay agents on nullpath's AI agent marketplace via MCP. Execute and register agents with x402 micropayments.
+Discover agents on nullpath's AI agent marketplace via MCP.
 
 **Package:** [`nullpath-mcp`](https://www.npmjs.com/package/nullpath-mcp) on npm
 
 ## Prerequisites
 
-- Node.js 18+ (required for `npx`)
+- Node.js 18+
 
 ## Quick Start
 
@@ -22,10 +22,7 @@ Add to your `claude_desktop_config.json`:
   "mcpServers": {
     "nullpath": {
       "command": "npx",
-      "args": ["-y", "nullpath-mcp"],
-      "env": {
-        "NULLPATH_WALLET_KEY": "0x..."
-      }
+      "args": ["-y", "nullpath-mcp"]
     }
   }
 }
@@ -44,32 +41,17 @@ Add to `.cursor/mcp.json` in your project:
   "mcpServers": {
     "nullpath": {
       "command": "npx",
-      "args": ["-y", "nullpath-mcp"],
-      "env": {
-        "NULLPATH_WALLET_KEY": "0x..."
-      }
+      "args": ["-y", "nullpath-mcp"]
     }
   }
 }
 ```
 
-## How It Works
-
-This client connects to nullpath's remote MCP server at `https://nullpath.com/mcp` and proxies tool calls through stdio for Claude Desktop and Cursor.
-
-For paid tools (`execute_agent`, `register_agent`), the client automatically:
-1. Detects 402 Payment Required responses
-2. Signs an EIP-3009 TransferWithAuthorization using your wallet
-3. Retries the request with the X-PAYMENT header
-4. Returns the result
-
-**No tokens leave your wallet until the agent successfully executes.**
-
 ## Example Usage
 
 Once configured, ask Claude:
 
-> "Find me an agent that can summarize PDFs"
+> "Find me an agent that can summarize text"
 
 Response:
 ```
@@ -84,44 +66,63 @@ I found 2 agents matching "summarize":
    - Trust tier: Premium | Reputation: 99
 ```
 
+### Executing a Paid Agent
+
 > "Execute the URL Summarizer on https://example.com"
 
+With `NULLPATH_WALLET_KEY` configured, the payment happens automatically:
+```json
+{
+  "result": {
+    "summary": "Example Domain - This domain is for illustrative examples in documents."
+  },
+  "_payment": {
+    "status": "paid",
+    "from": "0x..."
+  }
+}
 ```
-✓ Payment signed: $0.005 (agent fee + platform fee)
-✓ Agent executed successfully
 
-Summary: Example.com is a simple domain used for...
+If no wallet is configured:
+```json
+{
+  "error": "Wallet not configured",
+  "message": "Set NULLPATH_WALLET_KEY environment variable with your private key to execute paid agents.",
+  "hint": "Add to Claude Desktop config: \"env\": { \"NULLPATH_WALLET_KEY\": \"0x...\" }"
+}
 ```
 
 ## Available Tools
 
-| Tool | Description | Pricing |
+| Tool | Description | Payment |
 |------|-------------|---------|
 | `discover_agents` | Search agents by capability | Free |
 | `lookup_agent` | Get agent details by ID | Free |
 | `get_capabilities` | List capability categories | Free |
 | `check_reputation` | Get agent trust score | Free |
-| `execute_agent` | Run an agent with x402 payment | Paid (varies by agent) |
-| `register_agent` | Register new agent | $0.10 |
+| `execute_agent` | Run an agent | Varies by agent |
+| `register_agent` | Register new agent | $0.10 USDC |
 
-## Configuration
+## How It Works
+
+This MCP server connects directly to nullpath's REST API (`nullpath.com/api/v1/*`) and exposes tools via stdio for Claude Desktop and Cursor.
 
-### Environment Variables
+## Configuration
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `NULLPATH_WALLET_KEY` | For paid tools | Your wallet private key (0x-prefixed hex). Used to sign x402 payments. |
-| `NULLPATH_MCP_URL` | No | Override the MCP server URL (default: `https://nullpath.com/mcp`) |
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `NULLPATH_API_URL` | API base URL | `https://nullpath.com/api/v1` |
+| `NULLPATH_WALLET_KEY` | Private key for x402 payments | (required for paid tools) |
 
-### Security Notes
+### Wallet Setup for Paid Tools
 
-- **Never commit your private key** to version control
-- Use a dedicated wallet with limited funds for MCP payments
-- The client signs EIP-3009 authorizations, which can only transfer the exact amount specified
-- Payments are only settled after successful agent execution
+To use `execute_agent` and `register_agent`, you need a wallet with USDC on Base:
 
-### Full Configuration Example
+1. **Get a wallet private key** - Export from MetaMask or create new
+2. **Fund with USDC on Base** - Bridge USDC to Base network
+3. **Add to config**:
 
+**Claude Desktop** (`claude_desktop_config.json`):
 ```json
 {
   "mcpServers": {
@@ -129,43 +130,37 @@ Summary: Example.com is a simple domain used for...
       "command": "npx",
       "args": ["-y", "nullpath-mcp"],
       "env": {
-        "NULLPATH_WALLET_KEY": "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80",
-        "NULLPATH_MCP_URL": "https://nullpath.com/mcp"
+        "NULLPATH_WALLET_KEY": "0x..."
       }
     }
   }
 }
 ```
 
-## x402 Payment Protocol
-
-This client implements the [x402 protocol](https://github.com/coinbase/x402) for HTTP payments:
-
-1. **402 Response**: Server returns payment requirements (amount, recipient, asset)
-2. **EIP-3009 Signature**: Client signs a `TransferWithAuthorization` for USDC
-3. **X-PAYMENT Header**: Client retries with base64-encoded payment payload
-4. **Settlement**: Server verifies signature and settles payment on success
+**Cursor** (`.cursor/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "nullpath": {
+      "command": "npx",
+      "args": ["-y", "nullpath-mcp"],
+      "env": {
+        "NULLPATH_WALLET_KEY": "0x..."
+      }
+    }
+  }
+}
+```
 
-Supported networks:
-- **Base** (mainnet) - Production
-- **Base Sepolia** (testnet) - Development
+> ⚠️ **Security**: Your private key is stored locally and used only for signing. Never share it or commit to git.
 
 ## Troubleshooting
 
-**"NULLPATH_WALLET_KEY environment variable is required"**
-- Set your wallet private key in the MCP config's `env` section
-
-**"Unsupported network"**
-- The server requested payment on an unsupported chain. Contact support.
+**Connection errors:** Ensure you have internet access.
 
-**Connection errors**
-- Ensure you have internet access. The client connects to `https://nullpath.com/mcp`.
+**"Command not found":** Make sure Node.js 18+ is installed.
 
-**"Command not found"**
-- Make sure Node.js 18+ is installed and `npx` is in your PATH.
-
-**Tools not showing**
-- Restart Claude Desktop / Cursor after updating the config.
+**Tools not showing:** Restart Claude Desktop / Cursor after config changes.
 
 ## Development
 
@@ -174,17 +169,15 @@ git clone https://github.com/nullpath-labs/mcp-client.git
 cd mcp-client
 npm install
 npm run build
-npm run test      # Run tests
-npm run dev       # Run locally
+npm test
 ```
 
 ## Links
 
 - [nullpath.com](https://nullpath.com) — Marketplace
 - [docs.nullpath.com](https://docs.nullpath.com) — Documentation
-- [API Reference](https://docs.nullpath.com/api-reference) — Full API docs
-- [x402 Protocol](https://github.com/coinbase/x402) — Payment protocol spec
 
 ## License
 
 MIT
+

package/SWARM_SPEC.md

@@ -0,0 +1,75 @@
+# x402 Payment Signing for MCP Client
+
+## Goal
+Add automatic EIP-3009 payment signing to the nullpath MCP client so users can execute paid tools (execute_agent, register_agent) without manual payment handling.
+
+## Current State
+- MCP client at `/Users/tg_air/playground/mcp-client`
+- Free tools work: discover_agents, lookup_agent, get_capabilities, check_reputation
+- Paid tools exist on server but client can't sign payments
+- `viem` already installed as dependency
+
+## User Flow (Target)
+1. User configures `NULLPATH_WALLET_KEY` in Claude Desktop config
+2. User asks Claude: "Execute the URL Summarizer on https://example.com"
+3. Client calls execute_agent tool
+4. Server returns 402 Payment Required with:
+   - `X-PAYMENT-REQUIRED`: payment requirements (recipient, amount, asset, network)
+5. Client parses 402, signs EIP-3009 TransferWithAuthorization
+6. Client retries with `X-PAYMENT` header containing signature
+7. Server verifies, executes agent, returns result
+8. User sees result seamlessly
+
+## Technical Requirements
+
+### 1. Wallet Configuration
+- Read `NULLPATH_WALLET_KEY` from environment
+- Create viem wallet client for signing
+- Support Base mainnet (chainId: 8453)
+
+### 2. Payment Detection
+- Detect 402 status code
+- Parse `X-PAYMENT-REQUIRED` header (base64 JSON)
+- Extract: recipient, amount, asset (USDC address), network, validAfter, validBefore
+
+### 3. EIP-3009 Signing
+- Sign `TransferWithAuthorization` for USDC
+- Parameters: from, to, value, validAfter, validBefore, nonce
+- Use viem's signTypedData
+
+### 4. Payment Header
+- Encode signature as `X-PAYMENT` header
+- Format: base64 JSON with { signature, from, to, value, validAfter, validBefore, nonce }
+
+### 5. Retry Logic
+- On 402, sign and retry automatically
+- Max 1 retry (don't loop)
+- Return clear error if payment fails
+
+## Files to Create/Modify
+
+### New Files
+- `src/lib/wallet.ts` - Wallet client setup
+- `src/lib/payment.ts` - Payment signing logic
+- `src/lib/eip3009.ts` - EIP-3009 typed data structure
+- `src/__tests__/payment.test.ts` - Payment tests
+
+### Modify
+- `src/index.ts` - Add payment handling to execute_agent and register_agent tools
+- `README.md` - Document wallet configuration
+
+## USDC Contract Info
+- Base Mainnet: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
+- EIP-3009 domain: { name: "USD Coin", version: "2", chainId: 8453, verifyingContract: <address> }
+
+## Reference
+- x402 spec: https://github.com/coinbase/x402
+- Server payment middleware: nullpath repo `packages/mcp/src/middleware/payment.ts`
+- Existing x402 lib: nullpath repo `packages/mcp/src/lib/x402.ts`
+
+## Success Criteria
+- [ ] User can execute paid tools with just NULLPATH_WALLET_KEY env var
+- [ ] Payment signing is automatic and transparent
+- [ ] Clear error messages if wallet not configured or payment fails
+- [ ] Tests pass
+- [ ] Works in Claude Desktop

package/dist/__tests__/payment.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=payment.test.d.ts.map

package/dist/__tests__/payment.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/payment.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/payment.test.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const payment_js_1 = require("../lib/payment.js");
+(0, vitest_1.describe)('payment', () => {
+    (0, vitest_1.describe)('parsePaymentRequired', () => {
+        (0, vitest_1.it)('returns null for non-402 responses', () => {
+            const response = new Response('OK', { status: 200 });
+            (0, vitest_1.expect)((0, payment_js_1.parsePaymentRequired)(response)).toBeNull();
+        });
+        (0, vitest_1.it)('throws if 402 but missing X-PAYMENT-REQUIRED header', () => {
+            const response = new Response('Payment Required', { status: 402 });
+            (0, vitest_1.expect)(() => (0, payment_js_1.parsePaymentRequired)(response)).toThrow(payment_js_1.PaymentRequiredError);
+        });
+        (0, vitest_1.it)('parses valid 402 response with payment header', () => {
+            const requirements = {
+                recipient: '0x1234567890123456789012345678901234567890',
+                amount: '1000000', // 1 USDC
+                network: 8453,
+                validAfter: 0,
+                validBefore: Math.floor(Date.now() / 1000) + 300,
+            };
+            const encoded = Buffer.from(JSON.stringify(requirements)).toString('base64');
+            const response = new Response('Payment Required', {
+                status: 402,
+                headers: { 'X-PAYMENT-REQUIRED': encoded },
+            });
+            const parsed = (0, payment_js_1.parsePaymentRequired)(response);
+            (0, vitest_1.expect)(parsed).not.toBeNull();
+            (0, vitest_1.expect)(parsed.recipient).toBe(requirements.recipient);
+            (0, vitest_1.expect)(parsed.amount).toBe(BigInt(requirements.amount));
+            (0, vitest_1.expect)(parsed.network).toBe(8453);
+        });
+        (0, vitest_1.it)('handles string amounts', () => {
+            const requirements = {
+                recipient: '0x1234567890123456789012345678901234567890',
+                amount: '500000',
+                validBefore: Math.floor(Date.now() / 1000) + 300,
+            };
+            const encoded = Buffer.from(JSON.stringify(requirements)).toString('base64');
+            const response = new Response('', {
+                status: 402,
+                headers: { 'X-PAYMENT-REQUIRED': encoded },
+            });
+            const parsed = (0, payment_js_1.parsePaymentRequired)(response);
+            (0, vitest_1.expect)(parsed.amount).toBe(500000n);
+        });
+        (0, vitest_1.it)('rejects expired validBefore', () => {
+            const requirements = {
+                recipient: '0x1234567890123456789012345678901234567890',
+                amount: '1000000',
+                validBefore: Math.floor(Date.now() / 1000) - 100, // In the past
+            };
+            const encoded = Buffer.from(JSON.stringify(requirements)).toString('base64');
+            const response = new Response('', {
+                status: 402,
+                headers: { 'X-PAYMENT-REQUIRED': encoded },
+            });
+            (0, vitest_1.expect)(() => (0, payment_js_1.parsePaymentRequired)(response)).toThrow(/expired/);
+        });
+    });
+    (0, vitest_1.describe)('encodePaymentHeader', () => {
+        (0, vitest_1.it)('encodes signed authorization as base64 JSON', () => {
+            const signed = {
+                from: '0x1111111111111111111111111111111111111111',
+                to: '0x2222222222222222222222222222222222222222',
+                value: 1000000n,
+                validAfter: 0n,
+                validBefore: 9999999999n,
+                nonce: '0x' + '00'.repeat(32),
+                signature: '0x' + 'ab'.repeat(65),
+                v: 27,
+                r: '0x' + 'ab'.repeat(32),
+                s: '0x' + 'cd'.repeat(32),
+            };
+            const encoded = (0, payment_js_1.encodePaymentHeader)(signed);
+            // Should be valid base64
+            const decoded = JSON.parse(Buffer.from(encoded, 'base64').toString('utf-8'));
+            (0, vitest_1.expect)(decoded.from).toBe(signed.from);
+            (0, vitest_1.expect)(decoded.to).toBe(signed.to);
+            (0, vitest_1.expect)(decoded.value).toBe('1000000');
+            (0, vitest_1.expect)(decoded.signature).toBe(signed.signature);
+        });
+    });
+    (0, vitest_1.describe)('formatUsdcAmount', () => {
+        (0, vitest_1.it)('formats small amounts correctly', () => {
+            (0, vitest_1.expect)((0, payment_js_1.formatUsdcAmount)(1000n)).toBe('$0.001000 USDC');
+            (0, vitest_1.expect)((0, payment_js_1.formatUsdcAmount)(10000n)).toBe('$0.010000 USDC');
+            (0, vitest_1.expect)((0, payment_js_1.formatUsdcAmount)(100000n)).toBe('$0.100000 USDC');
+        });
+        (0, vitest_1.it)('formats whole dollar amounts', () => {
+            (0, vitest_1.expect)((0, payment_js_1.formatUsdcAmount)(1000000n)).toBe('$1.000000 USDC');
+            (0, vitest_1.expect)((0, payment_js_1.formatUsdcAmount)(10000000n)).toBe('$10.000000 USDC');
+        });
+        (0, vitest_1.it)('handles zero', () => {
+            (0, vitest_1.expect)((0, payment_js_1.formatUsdcAmount)(0n)).toBe('$0.000000 USDC');
+        });
+        (0, vitest_1.it)('preserves precision for large amounts', () => {
+            // This would lose precision with Number conversion
+            const largeAmount = 9007199254740993n; // > Number.MAX_SAFE_INTEGER
+            const formatted = (0, payment_js_1.formatUsdcAmount)(largeAmount);
+            (0, vitest_1.expect)(formatted).toContain('9007199254');
+        });
+    });
+});
+//# sourceMappingURL=payment.test.js.map

package/dist/__tests__/payment.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment.test.js","sourceRoot":"","sources":["../../src/__tests__/payment.test.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -17,6 +17,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const payment_js_1 = require("./lib/payment.js");
+const wallet_js_1 = require("./lib/wallet.js");
 const NULLPATH_API_URL = process.env.NULLPATH_API_URL || 'https://nullpath.com/api/v1';
 // Tool definitions
 const TOOLS = [
@@ -160,38 +162,157 @@ async function handleCheckReputation(args) {
     };
 }
 async function handleExecuteAgent(args) {
-    // Note: This would need x402 payment handling for production
-    // For now, return info about what would happen
-    const walletKey = process.env.NULLPATH_WALLET_KEY;
-    if (!walletKey) {
+    // Check wallet configuration upfront for better error messages
+    if (!(0, payment_js_1.isWalletConfigured)()) {
         return {
-            error: 'NULLPATH_WALLET_KEY environment variable not set. Payment required for execution.',
-            info: 'Set your wallet private key to enable paid agent execution.',
+            error: 'Wallet not configured',
+            message: 'Set NULLPATH_WALLET_KEY environment variable with your private key to execute paid agents.',
+            hint: 'Add to Claude Desktop config: "env": { "NULLPATH_WALLET_KEY": "0x..." }',
         };
     }
-    // TODO: Implement full x402 payment flow
-    return apiCall('/execute', {
-        method: 'POST',
-        body: JSON.stringify({
-            targetAgentId: args.agentId,
-            capabilityId: args.capabilityId,
-            input: args.input,
-        }),
+    // Validate wallet key is valid before making request
+    try {
+        (0, wallet_js_1.createWallet)();
+    }
+    catch (error) {
+        if (error instanceof payment_js_1.InvalidPrivateKeyError) {
+            return {
+                error: 'Invalid wallet key',
+                message: error.message,
+                hint: 'Ensure NULLPATH_WALLET_KEY is a valid 64-character hex string (with or without 0x prefix).',
+            };
+        }
+        throw error;
+    }
+    const url = `${NULLPATH_API_URL}/execute`;
+    const body = JSON.stringify({
+        targetAgentId: args.agentId,
+        capabilityId: args.capabilityId,
+        input: args.input,
     });
+    try {
+        // Use fetchWithPayment for automatic 402 handling
+        const response = await (0, payment_js_1.fetchWithPayment)(url, {
+            method: 'POST',
+            body,
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`API error (${response.status}): ${error}`);
+        }
+        const result = await response.json();
+        // Add wallet info to response for transparency
+        const walletAddress = (0, wallet_js_1.getWalletAddress)() ?? 'unknown';
+        return {
+            ...result,
+            _payment: {
+                status: 'paid',
+                from: walletAddress,
+            },
+        };
+    }
+    catch (error) {
+        if (error instanceof payment_js_1.WalletNotConfiguredError) {
+            return {
+                error: 'Wallet not configured',
+                message: error.message,
+                hint: 'Add NULLPATH_WALLET_KEY to your environment variables.',
+            };
+        }
+        if (error instanceof payment_js_1.PaymentRequiredError) {
+            return {
+                error: 'Payment failed',
+                message: error.message,
+                requirements: error.requirements ? {
+                    recipient: error.requirements.recipient,
+                    amount: (0, payment_js_1.formatUsdcAmount)(error.requirements.amount),
+                } : undefined,
+            };
+        }
+        if (error instanceof payment_js_1.PaymentSigningError) {
+            return {
+                error: 'Payment signing failed',
+                message: error.message,
+                hint: 'Check that your wallet has sufficient USDC balance on Base.',
+            };
+        }
+        throw error;
+    }
 }
 async function handleRegisterAgent(args) {
-    const walletKey = process.env.NULLPATH_WALLET_KEY;
-    if (!walletKey) {
+    // Check wallet configuration upfront for better error messages
+    if (!(0, payment_js_1.isWalletConfigured)()) {
         return {
-            error: 'NULLPATH_WALLET_KEY environment variable not set. Payment required for registration.',
-            info: 'Registration costs $0.10 USDC. Set your wallet private key to proceed.',
+            error: 'Wallet not configured',
+            message: 'Set NULLPATH_WALLET_KEY environment variable to register agents.',
+            hint: 'Registration costs $0.10 USDC. Add to Claude Desktop config: "env": { "NULLPATH_WALLET_KEY": "0x..." }',
         };
     }
-    // TODO: Implement full x402 payment flow
-    return apiCall('/agents', {
-        method: 'POST',
-        body: JSON.stringify(args),
-    });
+    // Validate wallet key is valid before making request
+    try {
+        (0, wallet_js_1.createWallet)();
+    }
+    catch (error) {
+        if (error instanceof payment_js_1.InvalidPrivateKeyError) {
+            return {
+                error: 'Invalid wallet key',
+                message: error.message,
+                hint: 'Ensure NULLPATH_WALLET_KEY is a valid 64-character hex string (with or without 0x prefix).',
+            };
+        }
+        throw error;
+    }
+    const url = `${NULLPATH_API_URL}/agents`;
+    const body = JSON.stringify(args);
+    try {
+        // Use fetchWithPayment for automatic 402 handling
+        const response = await (0, payment_js_1.fetchWithPayment)(url, {
+            method: 'POST',
+            body,
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`API error (${response.status}): ${error}`);
+        }
+        const result = await response.json();
+        // Add wallet info to response for transparency
+        const walletAddress = (0, wallet_js_1.getWalletAddress)() ?? 'unknown';
+        return {
+            ...result,
+            _payment: {
+                status: 'paid',
+                from: walletAddress,
+                cost: '$0.10 USDC',
+            },
+        };
+    }
+    catch (error) {
+        if (error instanceof payment_js_1.WalletNotConfiguredError) {
+            return {
+                error: 'Wallet not configured',
+                message: error.message,
+                cost: '$0.10 USDC required for registration',
+            };
+        }
+        if (error instanceof payment_js_1.PaymentRequiredError) {
+            return {
+                error: 'Payment failed',
+                message: error.message,
+                requirements: error.requirements ? {
+                    recipient: error.requirements.recipient,
+                    amount: (0, payment_js_1.formatUsdcAmount)(error.requirements.amount),
+                } : undefined,
+            };
+        }
+        if (error instanceof payment_js_1.PaymentSigningError) {
+            return {
+                error: 'Payment signing failed',
+                message: error.message,
+                hint: 'Ensure your wallet has at least $0.10 USDC on Base.',
+            };
+        }
+        throw error;
+    }
 }
 // Main server
 async function main() {