feat: add x402 payment tool example

Demonstrates how to build a payment-enabled tool for NeMo Agent Toolkit
that handles HTTP 402 (Payment Required) responses using the x402 protocol.

When an agent calls a paid API and receives HTTP 402, this tool:
- Parses x402 payment requirements from the response
- Evaluates cost against configurable spending policy
- Signs a payment proof using the agent's wallet (key isolated)
- Retries the request with payment proof attached

Uses @register_function with FunctionBaseConfig, valid NAT workflow
configs (functions/llms/workflow with _type refs), and nat.components
entry point registration.

Tools: fetch_paid_api (402 handling + payment) and get_payment_status
(spending awareness). Includes mock server for e2e testing.

Related: NVIDIA/NeMo-Agent-Toolkit#1806

Signed-off-by: up2itnow0822 <up2itnow0822@users.noreply.github.com>

Author: up2itnow0822

examples/x402_payment_tool/.gitignore

@@ -0,0 +1 @@
+examples/x402_payment_tool/src/nat_x402_payment/configs/payment-agent.yml

examples/x402_payment_tool/README.md

@@ -0,0 +1,209 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# x402 Payment Tool for NeMo Agent Toolkit
+
+## Overview
+
+### The Problem
+
+AI agents increasingly need to interact with paid APIs and services. When an agent encounters an HTTP 402 (Payment Required) response, it needs to evaluate the cost, authorize payment, and retry — all autonomously. Unlike regular API errors, payment operations are **irreversible**, requiring security guarantees beyond standard tool integrations.
+
+### The Solution
+
+This example implements a payment-enabled tool for NeMo Agent Toolkit using `@register_function` that handles [x402](https://github.com/coinbase/x402) payment negotiation within a ReAct agent loop.
+
+### How It Works
+
+```
+Agent receives user query
+    │
+    ▼
+fetch_paid_api tool called with target URL
+    │
+    ▼
+API responds with HTTP 402 + x402 payment requirements
+    │
+    ▼
+Tool checks spending policy (per-tx cap, daily limit, recipient allowlist)
+    │
+    ├── DENIED → Return denial reason to agent
+    │
+    ▼
+Wallet signer (isolated process) signs the payment
+    │
+    ▼
+Tool retries request with X-PAYMENT header
+    │
+    ▼
+Agent receives data and continues reasoning
+```
+
+## Best Practices for x402 Payment Tools
+
+### 1. Isolate Wallet Keys from the Agent Process
+
+Payment tools handle irreversible value transfer. The signing key must never live in the same process as the agent.
+
+| Mode | Key Location | Use Case |
+|------|-------------|----------|
+| **Inline** (dev only) | `WALLET_PRIVATE_KEY` env var | Local testing with mock server |
+| **Remote signer** (production) | Separate process via `WALLET_SIGNER_URL` | Any deployment with real funds |
+
+The remote signer pattern ensures that even if the agent process is compromised, the attacker cannot sign arbitrary transactions — the signer only accepts pre-validated payment requests.
+
+### 2. Enforce Spending Policy Before Signing
+
+Spending limits are checked **before** the wallet is asked to sign, not after. This prevents a compromised or hallucinating agent from constructing valid payment transactions that exceed budget.
+
+```yaml
+# In your NAT workflow config:
+functions:
+  fetch_paid_api:
+    _type: fetch_paid_api
+    max_per_transaction: 0.10    # Max USDC per payment
+    max_daily_spend: 5.00        # Daily cap
+    allowed_recipients:           # Only these addresses can receive funds
+      - "0x..."
+```
+
+### 3. Allowlist Payment Recipients
+
+Never allow an agent to pay arbitrary addresses. Configure `allowed_recipients` with the addresses of your known API providers. Any payment to an unlisted address is rejected before signing.
+
+### 4. Log Every Payment Attempt
+
+The `get_payment_status` tool provides the agent with spending awareness and gives operators a full audit trail. Every payment attempt (successful, denied, or failed) is logged with timestamp, amount, recipient, and transaction hash.
+
+## Prerequisites
+
+- Python >= 3.11
+- NeMo Agent Toolkit >= 1.4.0 (`pip install nvidia-nat[langchain]`)
+- An NVIDIA API key for NIM models (set `NVIDIA_API_KEY`)
+- For testing: no wallet needed (mock server accepts any signature)
+- For production: an Ethereum wallet with USDC on Base network
+
+## Quick Start
+
+### 1. Install the Example
+
+```bash
+cd examples/x402_payment_tool
+pip install -e .
+```
+
+### 2. Start the Mock x402 Server
+
+```bash
+python scripts/mock_x402_server.py &
+# Server runs on http://localhost:8402
+# GET /v1/market-data → 402 (requires payment)
+# GET /v1/market-data + X-PAYMENT header → 200 (mock data)
+```
+
+### 3. Configure and Run
+
+```bash
+# Copy example config
+cp src/nat_x402_payment/configs/payment-agent.example.yml \
+   src/nat_x402_payment/configs/payment-agent.yml
+
+# Set wallet key (any hex string works with mock server)
+export WALLET_PRIVATE_KEY="0x0000000000000000000000000000000000000000000000000000000000000001"
+
+# Set NVIDIA API key for the LLM
+export NVIDIA_API_KEY="your-nvidia-api-key"
+
+# Run the agent
+nat run --config_file src/nat_x402_payment/configs/payment-agent.yml
+```
+
+### 4. Test the Agent
+
+Once the agent is running, try prompts like:
+
+```
+> Fetch the premium market data from http://localhost:8402/v1/market-data
+```
+
+The agent will:
+1. Call `fetch_paid_api` with the URL
+2. Receive a 402 response
+3. Evaluate the cost (0.05 USDC) against the spending policy
+4. Sign payment and retry
+5. Return the market data
+
+```
+> What's my current payment spending status?
+```
+
+The agent will call `get_payment_status` and report daily spend and recent transactions.
+
+## File Structure
+
+```
+x402_payment_tool/
+├── README.md
+├── pyproject.toml
+├── scripts/
+│   └── mock_x402_server.py          # Mock paid API for testing
+└── src/nat_x402_payment/
+    ├── __init__.py
+    ├── register.py                   # NAT tool registration (@register_function)
+    ├── wallet.py                     # Wallet signing abstraction (inline/remote)
+    └── configs/
+        └── payment-agent.example.yml # NAT workflow configuration
+```
+
+## Configuration Reference
+
+### Spending Policy
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `max_per_transaction` | 0.10 | Maximum USDC per single payment |
+| `max_daily_spend` | 5.00 | Daily spending cap in USDC |
+| `allowed_recipients` | [] | Allowlisted addresses (empty = allow all) |
+| `wallet_signer_url` | "" | Remote signer URL (empty = inline mode) |
+| `request_timeout` | 30.0 | HTTP request timeout in seconds |
+
+### Wallet Modes
+
+**Inline (development):**
+```bash
+export WALLET_PRIVATE_KEY="0x..."
+```
+
+**Remote signer (production):**
+```yaml
+functions:
+  fetch_paid_api:
+    _type: fetch_paid_api
+    wallet_signer_url: "http://localhost:8900"
+```
+
+The remote signer exposes three endpoints:
+- `GET /address` — wallet public address
+- `GET /balance?asset=...&network=...` — token balance
+- `POST /sign` — sign a payment request
+
+## References
+
+- [x402 Protocol (Coinbase)](https://github.com/coinbase/x402) — HTTP 402 payment standard
+- [agent-wallet-sdk](https://github.com/up2itnow0822/agent-wallet-sdk) — Non-custodial agent wallets with on-chain spending policies
+- [agentpay-mcp](https://github.com/up2itnow0822/agentpay-mcp) — MCP payment server implementation
+- Related issue: [NVIDIA/NeMo-Agent-Toolkit#1806](https://github.com/NVIDIA/NeMo-Agent-Toolkit/issues/1806)

examples/x402_payment_tool/pyproject.toml

@@ -0,0 +1,41 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+[build-system]
+build-backend = "setuptools.build_meta"
+requires = ["setuptools >= 64", "setuptools-scm>=8"]
+
+[tool.setuptools_scm]
+git_describe_command = "git describe --long --first-parent"
+root = "../.."
+
+[project]
+name = "nat_x402_payment"
+dynamic = ["version"]
+dependencies = [
+    "nvidia-nat[langchain]>=1.4.0a0,<1.5.0",
+    "httpx>=0.27.0",
+    "eth-account>=0.13.0",
+]
+requires-python = ">=3.11,<3.14"
+description = "x402 payment-enabled tool for NeMo Agent Toolkit — handle HTTP 402 payment negotiation in agent loops"
+keywords = ["ai", "payments", "x402", "nvidia", "agents", "wallet"]
+classifiers = ["Programming Language :: Python"]
+
+[project.entry-points.'nat.components']
+nat_x402_payment = "nat_x402_payment.register"
+
+[tool.setuptools.packages.find]
+where = ["src"]

examples/x402_payment_tool/scripts/mock_x402_server.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Mock x402 server for testing the payment tool.
+
+Simulates a paid API that:
+- Returns 402 with x402 payment requirements for unauthenticated requests
+- Returns 200 with mock data when valid payment proof is provided
+
+Usage:
+    python scripts/mock_x402_server.py
+    # Server runs on http://localhost:8402
+"""
+
+import json
+from http.server import HTTPServer, BaseHTTPRequestHandler
+
+MOCK_DATA = {
+    "market_data": {
+        "symbol": "NVDA",
+        "price": 142.50,
+        "volume": 45_000_000,
+        "change_24h": 3.2,
+        "source": "premium-data-provider",
+        "timestamp": "2026-03-18T12:00:00Z",
+    }
+}
+
+PAYMENT_REQUIREMENTS = {
+    "x402Version": 1,
+    "accepts": [
+        {
+            "scheme": "exact",
+            "network": "base",
+            "maxAmountRequired": "50000",  # 0.05 USDC (6 decimals)
+            "resource": "http://localhost:8402/v1/market-data",
+            "description": "Premium market data access",
+            "mimeType": "application/json",
+            "payTo": "0x1234567890abcdef1234567890abcdef12345678",
+            "maxTimeoutSeconds": 300,
+            "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",  # USDC on Base
+        }
+    ],
+}
+
+MOCK_RECIPIENT = "0x1234567890abcdef1234567890abcdef12345678"
+
+
+class X402Handler(BaseHTTPRequestHandler):
+    def do_GET(self):  # noqa: N802
+        if self.path.startswith("/v1/market-data"):
+            payment_header = self.headers.get("X-PAYMENT", "")
+
+            if payment_header:
+                # Validate payment proof (mock: just check it's non-empty JSON)
+                try:
+                    payment = json.loads(payment_header)
+                    if payment.get("payTo") == MOCK_RECIPIENT:
+                        self.send_response(200)
+                        self.send_header("Content-Type", "application/json")
+                        self.end_headers()
+                        self.wfile.write(json.dumps(MOCK_DATA).encode())
+                        return
+                except (json.JSONDecodeError, KeyError):
+                    pass
+
+                # Invalid payment
+                self.send_response(400)
+                self.send_header("Content-Type", "application/json")
+                self.end_headers()
+                self.wfile.write(json.dumps({"error": "Invalid payment proof"}).encode())
+                return
+
+            # No payment — return 402
+            self.send_response(402)
+            self.send_header("Content-Type", "application/json")
+            self.end_headers()
+            self.wfile.write(json.dumps(PAYMENT_REQUIREMENTS).encode())
+            return
+
+        # 404 for unknown paths
+        self.send_response(404)
+        self.send_header("Content-Type", "application/json")
+        self.end_headers()
+        self.wfile.write(json.dumps({"error": "Not found"}).encode())
+
+    def log_message(self, format, *args):
+        """Custom log format."""
+        print(f"[x402-mock] {args[0]}")
+
+
+def main():
+    port = 8402
+    server = HTTPServer(("localhost", port), X402Handler)
+    print(f"Mock x402 server running on http://localhost:{port}")
+    print(f"  GET /v1/market-data → 402 (requires payment)")
+    print(f"  GET /v1/market-data + X-PAYMENT header → 200 (mock data)")
+    print()
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        print("\nShutting down.")
+        server.server_close()
+
+
+if __name__ == "__main__":
+    main()

examples/x402_payment_tool/src/nat_x402_payment/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0