arczk-agent 0.1.0__tar.gz

arczk_agent-0.1.0/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: arczk-agent
+Version: 0.1.0
+Summary: Autonomous AI Agent SDK for ArcNano Shielded Zero-Knowledge Nanopayments on Arc
+Author-email: Trymbak Mahant <trymbakmahant@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Trymbakmahant/arcnano
+Project-URL: Documentation, https://github.com/Trymbakmahant/arcnano
+Project-URL: Repository, https://github.com/Trymbakmahant/arcnano
+Project-URL: Bug Tracker, https://github.com/Trymbakmahant/arcnano/issues
+Keywords: arcnano,zk-proofs,x402,ai-agents,langchain,crewai,micropayments,arc-network,groth16,zero-knowledge,autonomous-agents
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Security :: Cryptography
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.1.0; extra == "crewai"
+
+# arczk-agent
+
+> **Autonomous AI Agent SDK for ArcNano Shielded Zero-Knowledge Nanopayments on Arc.**
+
+[![PyPI version](https://img.shields.io/pypi/v/arczk-agent.svg?color=emerald)](https://pypi.org/project/arczk-agent/)
+[![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://pypi.org/project/arczk-agent/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Arc Testnet](https://img.shields.io/badge/Arc_Testnet-5042002-blue.svg)](https://testnet.arcscan.io)
+[![Latency](https://img.shields.io/badge/ZK_Proof_Gen-<10ms-brightgreen.svg)](https://github.com/Trymbakmahant/arcnano)
+
+---
+
+## ⚡ Overview
+
+`arczk-agent` empowers autonomous AI agents (**LangChain**, **CrewAI**, **AutoGPT**, **LlamaIndex**) to execute instant, privacy-preserving micro-payments over standard **HTTP 402 Payment Required** protocols with complete identity unlinkability on the **Arc Network**.
+
+### Why use `arczk-agent`?
+
+- 🛡️ **Zero Signer Exposure**: The calling AI agent never broadcasts on-chain transactions or exposes private keys. API providers cannot link prompt requests to any on-chain wallet balance.
+- ⚡ **Autonomous X402 Negotiation**: Automatically intercepts `402 Payment Required` responses, extracts cryptographic invoice parameters, generates Groth16 spend proofs in RAM, and retries in single-digit milliseconds.
+- 🔐 **Shielded Note Vault**: Client-side note generation (`secret`, `nullifier_seed`, Poseidon commitments) with local encrypted JSON persistence.
+- 🤖 **Agent Framework Ready**: Drop-in tool adapters for **LangChain** and **CrewAI** multi-agent pipelines.
+- ⛽ **Zero Gas Overhead**: Note settlement is batched and sponsored by API providers via Circle Gas Station (ERC-4337) on Arc L1.
+
+---
+
+## 🔄 How Autonomous X402 Negotiation Works
+
+```
+ Autonomous Agent (Python)                 Protected API Gateway (X402)               Arc L1
+           |                                              |                             |
+           |  1. POST /v1/inference (no credentials)      |                             |
+           |--------------------------------------------->|                             |
+           |                                              |                             |
+           |  2. 402 Payment Required                     |                             |
+           |     WWW-Authenticate: X402 pool=...          |                             |
+           |<---------------------------------------------|                             |
+           |                                              |                             |
+           |  -- Parse X402 Invoice                       |                             |
+           |  -- Retrieve Note from Vault                 |                             |
+           |  -- Generate Groth16 Proof in RAM            |                             |
+           |                                              |                             |
+           |  3. POST /v1/inference                       |                             |
+           |     Authorization: X402 {"proof": ...}       |                             |
+           |--------------------------------------------->|                             |
+           |                                              |-- Verify Proof (<8ms)       |
+           |                                              |-- Check Nullifier Cache     |
+           |  4. 200 OK (Stream LLM Response)             |                             |
+           |<---------------------------------------------|                             |
+           |                                              |  5. batchSpend (Sponsored)  |
+           |  -- Mark Note Spent in Vault                 |---------------------------->|
+```
+
+---
+
+## 📦 Installation
+
+```bash
+# Standard installation
+pip install arczk-agent
+
+# Using uv (recommended for ultra-fast installs)
+uv pip install arczk-agent
+
+# With LangChain support
+pip install "arczk-agent[langchain]"
+
+# With CrewAI support
+pip install "arczk-agent[crewai]"
+```
+
+---
+
+## 🚀 Quickstart
+
+### 1. Direct Python Client with Transparent X402 Handling
+
+The `ArcAgentClient` behaves like standard `requests`, but transparently intercepts HTTP 402 challenges and fulfills them:
+
+```python
+from arczk import ArcAgentClient, NoteVault
+
+# 1. Initialize local shielded note vault
+vault = NoteVault("~/.arcnano/agent_vault.json")
+
+# 2. Fund/initialize an unspent note (0.01 USDC = 10,000 micro-units)
+vault.create_note(denomination=10000)
+
+print(f"Active unspent balance: {vault.unspent_balance()} micro-units")
+
+# 3. Create autonomous agent HTTP client
+client = ArcAgentClient(vault=vault)
+
+# 4. Request any X402-enabled API endpoint:
+# The client automatically handles HTTP 402, generates a ZK proof, and fulfills payment!
+response = client.post(
+    "https://api.inference.ai/v1/generate",
+    json={"prompt": "Analyze autonomous financial markets on Arc"}
+)
+
+print("Status:", response.status_code)
+print("Response:", response.json())
+```
+
+---
+
+### 2. LangChain Autonomous Agent Integration
+
+Plug `ArcNanoLangChainTool` into any LangChain agent executor:
+
+```python
+from langchain.agents import AgentExecutor, create_openai_tools_agent
+from langchain_openai import ChatOpenAI
+from langchain_core.prompts import ChatPromptTemplate
+from arczk.integrations import ArcNanoLangChainTool
+
+# Initialize tool
+payment_tool = ArcNanoLangChainTool()
+
+tools = [payment_tool]
+llm = ChatOpenAI(model="gpt-4o", temperature=0)
+
+prompt = ChatPromptTemplate.from_messages([
+    ("system", "You are an autonomous research agent. Use the arcnano tool to pay for external compute APIs."),
+    ("human", "{input}"),
+    ("placeholder", "{agent_scratchpad}"),
+])
+
+agent = create_openai_tools_agent(llm, tools, prompt)
+agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
+
+agent_executor.invoke({
+    "input": "Call https://api.inference.ai/v1/generate to retrieve specialized market intelligence."
+})
+```
+
+---
+
+### 3. CrewAI Autonomous Agent Tool
+
+```python
+from crewai import Agent, Task, Crew
+from arczk.integrations import ArcNanoPaymentTool
+
+payment_tool = ArcNanoPaymentTool()
+
+researcher = Agent(
+    role="Autonomous Intelligence Scout",
+    goal="Gather paid API data on Arc without leaking signer identity",
+    backstory="Specialized in zero-knowledge agent transactions",
+    tools=[payment_tool.run],
+    verbose=True,
+)
+
+task = Task(
+    description="Fetch data from https://api.inference.ai/v1/generate using shielded payment.",
+    expected_output="JSON data returned from the paid inference endpoint.",
+    agent=researcher,
+)
+
+crew = Crew(agents=[researcher], tasks=[task])
+result = crew.kickoff()
+print(result)
+```
+
+---
+
+## 📚 Core Modules Reference
+
+### `ArcAgentClient`
+Autonomous HTTP client with session pooling and automated payment retry:
+- `client.request(method, url, headers=None, auto_pay=True, **kwargs)`
+- `client.get(url, **kwargs)`
+- `client.post(url, **kwargs)`
+- `client.parse_invoice(response)`: Extracts `recipient`, `pool`, `root`, and `denomination` from RFC `WWW-Authenticate` headers or JSON body.
+
+### `NoteVault`
+Encrypted local note manager storing client-side shielded notes:
+- `vault.create_note(denomination=10000)`: Generates cryptographically secure random `secret` and `nullifier_seed` scalars in the BN254 field and computes Poseidon commitments.
+- `vault.get_unspent_note(denomination=None)`: Retrieves the first unspent note with sufficient value.
+- `vault.mark_spent(nullifier_hash)`: Marks note as consumed to prevent client-side replays.
+- `vault.unspent_balance()`: Total available unspent units.
+- `vault.save(filepath)` / `vault.load(filepath)`: JSON file persistence.
+
+### `Groth16Prover`
+RAM-based Groth16 spend proof generator:
+- Binds public signals `[root, nullifierHash, recipient, aspRoot]` to the provider's wallet.
+- Prevents frontrunning: proof is cryptographically tied to the exact recipient address specified in the invoice.
+
+---
+
+## 🌐 Network & Contract Reference
+
+| Parameter | Value |
+| :--- | :--- |
+| **Network** | Arc Testnet (Circle L1) |
+| **Chain ID** | `5042002` |
+| **Gas & Settlement Asset** | USDC (Native Gas & Denomination) |
+| **RPC Endpoint** | `https://rpc.testnet.arc.network` |
+| **Explorer** | [https://testnet.arcscan.io](https://testnet.arcscan.io) |
+| **ArcNanoPool Contract** | [`0xa40d68FDEa3B6fb01c966A9d29A6fc341AE476Ca`](https://testnet.arcscan.io/address/0xa40d68FDEa3B6fb01c966A9d29A6fc341AE476Ca) |
+| **Standard Denominations** | `1000` (0.001 USDC), `10000` (0.01 USDC), `100000` (0.1 USDC) |
+
+---
+
+## 🧪 Testing
+
+```bash
+# Run test suite
+pytest tests/ -v
+```
+
+---
+
+## 📄 License
+
+MIT © [Trymbak Mahant](https://github.com/Trymbakmahant)

arczk_agent-0.1.0/README.md

@@ -0,0 +1,217 @@
+# arczk-agent
+
+> **Autonomous AI Agent SDK for ArcNano Shielded Zero-Knowledge Nanopayments on Arc.**
+
+[![PyPI version](https://img.shields.io/pypi/v/arczk-agent.svg?color=emerald)](https://pypi.org/project/arczk-agent/)
+[![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://pypi.org/project/arczk-agent/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Arc Testnet](https://img.shields.io/badge/Arc_Testnet-5042002-blue.svg)](https://testnet.arcscan.io)
+[![Latency](https://img.shields.io/badge/ZK_Proof_Gen-<10ms-brightgreen.svg)](https://github.com/Trymbakmahant/arcnano)
+
+---
+
+## ⚡ Overview
+
+`arczk-agent` empowers autonomous AI agents (**LangChain**, **CrewAI**, **AutoGPT**, **LlamaIndex**) to execute instant, privacy-preserving micro-payments over standard **HTTP 402 Payment Required** protocols with complete identity unlinkability on the **Arc Network**.
+
+### Why use `arczk-agent`?
+
+- 🛡️ **Zero Signer Exposure**: The calling AI agent never broadcasts on-chain transactions or exposes private keys. API providers cannot link prompt requests to any on-chain wallet balance.
+- ⚡ **Autonomous X402 Negotiation**: Automatically intercepts `402 Payment Required` responses, extracts cryptographic invoice parameters, generates Groth16 spend proofs in RAM, and retries in single-digit milliseconds.
+- 🔐 **Shielded Note Vault**: Client-side note generation (`secret`, `nullifier_seed`, Poseidon commitments) with local encrypted JSON persistence.
+- 🤖 **Agent Framework Ready**: Drop-in tool adapters for **LangChain** and **CrewAI** multi-agent pipelines.
+- ⛽ **Zero Gas Overhead**: Note settlement is batched and sponsored by API providers via Circle Gas Station (ERC-4337) on Arc L1.
+
+---
+
+## 🔄 How Autonomous X402 Negotiation Works
+
+```
+ Autonomous Agent (Python)                 Protected API Gateway (X402)               Arc L1
+           |                                              |                             |
+           |  1. POST /v1/inference (no credentials)      |                             |
+           |--------------------------------------------->|                             |
+           |                                              |                             |
+           |  2. 402 Payment Required                     |                             |
+           |     WWW-Authenticate: X402 pool=...          |                             |
+           |<---------------------------------------------|                             |
+           |                                              |                             |
+           |  -- Parse X402 Invoice                       |                             |
+           |  -- Retrieve Note from Vault                 |                             |
+           |  -- Generate Groth16 Proof in RAM            |                             |
+           |                                              |                             |
+           |  3. POST /v1/inference                       |                             |
+           |     Authorization: X402 {"proof": ...}       |                             |
+           |--------------------------------------------->|                             |
+           |                                              |-- Verify Proof (<8ms)       |
+           |                                              |-- Check Nullifier Cache     |
+           |  4. 200 OK (Stream LLM Response)             |                             |
+           |<---------------------------------------------|                             |
+           |                                              |  5. batchSpend (Sponsored)  |
+           |  -- Mark Note Spent in Vault                 |---------------------------->|
+```
+
+---
+
+## 📦 Installation
+
+```bash
+# Standard installation
+pip install arczk-agent
+
+# Using uv (recommended for ultra-fast installs)
+uv pip install arczk-agent
+
+# With LangChain support
+pip install "arczk-agent[langchain]"
+
+# With CrewAI support
+pip install "arczk-agent[crewai]"
+```
+
+---
+
+## 🚀 Quickstart
+
+### 1. Direct Python Client with Transparent X402 Handling
+
+The `ArcAgentClient` behaves like standard `requests`, but transparently intercepts HTTP 402 challenges and fulfills them:
+
+```python
+from arczk import ArcAgentClient, NoteVault
+
+# 1. Initialize local shielded note vault
+vault = NoteVault("~/.arcnano/agent_vault.json")
+
+# 2. Fund/initialize an unspent note (0.01 USDC = 10,000 micro-units)
+vault.create_note(denomination=10000)
+
+print(f"Active unspent balance: {vault.unspent_balance()} micro-units")
+
+# 3. Create autonomous agent HTTP client
+client = ArcAgentClient(vault=vault)
+
+# 4. Request any X402-enabled API endpoint:
+# The client automatically handles HTTP 402, generates a ZK proof, and fulfills payment!
+response = client.post(
+    "https://api.inference.ai/v1/generate",
+    json={"prompt": "Analyze autonomous financial markets on Arc"}
+)
+
+print("Status:", response.status_code)
+print("Response:", response.json())
+```
+
+---
+
+### 2. LangChain Autonomous Agent Integration
+
+Plug `ArcNanoLangChainTool` into any LangChain agent executor:
+
+```python
+from langchain.agents import AgentExecutor, create_openai_tools_agent
+from langchain_openai import ChatOpenAI
+from langchain_core.prompts import ChatPromptTemplate
+from arczk.integrations import ArcNanoLangChainTool
+
+# Initialize tool
+payment_tool = ArcNanoLangChainTool()
+
+tools = [payment_tool]
+llm = ChatOpenAI(model="gpt-4o", temperature=0)
+
+prompt = ChatPromptTemplate.from_messages([
+    ("system", "You are an autonomous research agent. Use the arcnano tool to pay for external compute APIs."),
+    ("human", "{input}"),
+    ("placeholder", "{agent_scratchpad}"),
+])
+
+agent = create_openai_tools_agent(llm, tools, prompt)
+agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
+
+agent_executor.invoke({
+    "input": "Call https://api.inference.ai/v1/generate to retrieve specialized market intelligence."
+})
+```
+
+---
+
+### 3. CrewAI Autonomous Agent Tool
+
+```python
+from crewai import Agent, Task, Crew
+from arczk.integrations import ArcNanoPaymentTool
+
+payment_tool = ArcNanoPaymentTool()
+
+researcher = Agent(
+    role="Autonomous Intelligence Scout",
+    goal="Gather paid API data on Arc without leaking signer identity",
+    backstory="Specialized in zero-knowledge agent transactions",
+    tools=[payment_tool.run],
+    verbose=True,
+)
+
+task = Task(
+    description="Fetch data from https://api.inference.ai/v1/generate using shielded payment.",
+    expected_output="JSON data returned from the paid inference endpoint.",
+    agent=researcher,
+)
+
+crew = Crew(agents=[researcher], tasks=[task])
+result = crew.kickoff()
+print(result)
+```
+
+---
+
+## 📚 Core Modules Reference
+
+### `ArcAgentClient`
+Autonomous HTTP client with session pooling and automated payment retry:
+- `client.request(method, url, headers=None, auto_pay=True, **kwargs)`
+- `client.get(url, **kwargs)`
+- `client.post(url, **kwargs)`
+- `client.parse_invoice(response)`: Extracts `recipient`, `pool`, `root`, and `denomination` from RFC `WWW-Authenticate` headers or JSON body.
+
+### `NoteVault`
+Encrypted local note manager storing client-side shielded notes:
+- `vault.create_note(denomination=10000)`: Generates cryptographically secure random `secret` and `nullifier_seed` scalars in the BN254 field and computes Poseidon commitments.
+- `vault.get_unspent_note(denomination=None)`: Retrieves the first unspent note with sufficient value.
+- `vault.mark_spent(nullifier_hash)`: Marks note as consumed to prevent client-side replays.
+- `vault.unspent_balance()`: Total available unspent units.
+- `vault.save(filepath)` / `vault.load(filepath)`: JSON file persistence.
+
+### `Groth16Prover`
+RAM-based Groth16 spend proof generator:
+- Binds public signals `[root, nullifierHash, recipient, aspRoot]` to the provider's wallet.
+- Prevents frontrunning: proof is cryptographically tied to the exact recipient address specified in the invoice.
+
+---
+
+## 🌐 Network & Contract Reference
+
+| Parameter | Value |
+| :--- | :--- |
+| **Network** | Arc Testnet (Circle L1) |
+| **Chain ID** | `5042002` |
+| **Gas & Settlement Asset** | USDC (Native Gas & Denomination) |
+| **RPC Endpoint** | `https://rpc.testnet.arc.network` |
+| **Explorer** | [https://testnet.arcscan.io](https://testnet.arcscan.io) |
+| **ArcNanoPool Contract** | [`0xa40d68FDEa3B6fb01c966A9d29A6fc341AE476Ca`](https://testnet.arcscan.io/address/0xa40d68FDEa3B6fb01c966A9d29A6fc341AE476Ca) |
+| **Standard Denominations** | `1000` (0.001 USDC), `10000` (0.01 USDC), `100000` (0.1 USDC) |
+
+---
+
+## 🧪 Testing
+
+```bash
+# Run test suite
+pytest tests/ -v
+```
+
+---
+
+## 📄 License
+
+MIT © [Trymbak Mahant](https://github.com/Trymbakmahant)

arczk_agent-0.1.0/arczk/__init__.py

@@ -0,0 +1,26 @@
+"""
+ArcNano: Shielded Zero-Knowledge Nanopayments on Arc
+Autonomous AI Agent SDK (LangChain, AutoGPT, CrewAI)
+"""
+
+from .types import ShieldedNote, X402Invoice, SpendProofPayload
+from .crypto import poseidon, derive_commitment, derive_nullifier_hash, BN254_FIELD_PRIME
+from .vault import NoteVault
+from .prover import Groth16Prover
+from .client import ArcAgentClient
+from .integrations import ArcNanoPaymentTool
+
+__version__ = "0.1.0"
+__all__ = [
+    "ShieldedNote",
+    "X402Invoice",
+    "SpendProofPayload",
+    "poseidon",
+    "derive_commitment",
+    "derive_nullifier_hash",
+    "BN254_FIELD_PRIME",
+    "NoteVault",
+    "Groth16Prover",
+    "ArcAgentClient",
+    "ArcNanoPaymentTool",
+]

arczk_agent-0.1.0/arczk/client.py

@@ -0,0 +1,162 @@
+import json
+import logging
+import re
+from typing import Optional, Dict, Any, Union
+import requests
+
+from .types import ShieldedNote, X402Invoice, SpendProofPayload
+from .vault import NoteVault
+from .prover import Groth16Prover
+
+logger = logging.getLogger("arczk.client")
+
+
+class ArcAgentClient:
+    """
+    Autonomous AI Agent HTTP client with automatic X402 payment handling.
+    Intercepts HTTP 402 Payment Required, generates zero-knowledge spend proofs in memory,
+    and retries transparently with standardized X-Payment and Authorization headers.
+    """
+
+    def __init__(
+        self,
+        vault: Optional[NoteVault] = None,
+        prover: Optional[Groth16Prover] = None,
+        max_payment_per_call: int = 50000,  # 0.05 USDC max limit per call
+        session: Optional[requests.Session] = None,
+    ):
+        self.vault = vault or NoteVault()
+        self.prover = prover or Groth16Prover()
+        self.max_payment_per_call = max_payment_per_call
+        self.session = session or requests.Session()
+
+    def parse_invoice(self, response: requests.Response) -> X402Invoice:
+        """Parses X402 challenge from response headers, WWW-Authenticate, or JSON body."""
+        headers = response.headers
+        recipient = headers.get("x402-recipient")
+        pool = headers.get("x402-pool", "0xa40d68FDEa3B6fb01c966A9d29A6fc341AE476Ca")
+        root = headers.get("x402-root")
+        asp_root = headers.get("x402-asp-root")
+        denomination = int(headers.get("x402-denomination", "10000"))
+        chain_id = int(headers.get("x402-chain-id", "5042002"))
+
+        # Parse standard RFC-style WWW-Authenticate: X402 ... header
+        auth_header = headers.get("www-authenticate", "")
+        if "X402" in auth_header:
+            pool_match = re.search(r'pool=["\']([^"\']+)["\']', auth_header)
+            if pool_match and not recipient:
+                pool = pool_match.group(1)
+            denom_match = re.search(r'denomination=["\']?(\d+)["\']?', auth_header)
+            if denom_match:
+                try:
+                    denomination = int(denom_match.group(1))
+                except ValueError:
+                    pass
+
+        # Parse response JSON body if present
+        raw_challenge = {}
+        try:
+            body = response.json()
+            raw_challenge = body
+            invoice_data = body.get("invoice") or body
+            if isinstance(invoice_data, dict):
+                recipient = recipient or invoice_data.get("recipient")
+                pool = pool or invoice_data.get("pool")
+                root = root or invoice_data.get("root")
+                asp_root = (
+                    asp_root
+                    or invoice_data.get("aspRoot")
+                    or invoice_data.get("asp_root")
+                )
+                if "denomination" in invoice_data:
+                    try:
+                        denomination = int(invoice_data["denomination"])
+                    except (ValueError, TypeError):
+                        pass
+                if "chainId" in invoice_data or "chain_id" in invoice_data:
+                    try:
+                        chain_id = int(invoice_data.get("chainId") or invoice_data.get("chain_id"))
+                    except (ValueError, TypeError):
+                        pass
+        except Exception:
+            pass
+
+        if not recipient or not root:
+            raise ValueError(f"Incomplete X402 payment invoice from server: {headers}")
+
+        return X402Invoice(
+            pool=pool,
+            denomination=denomination,
+            recipient=recipient,
+            root=root,
+            asp_root=asp_root or "0",
+            chain_id=chain_id,
+            raw_challenge=raw_challenge,
+        )
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        headers: Optional[Dict[str, str]] = None,
+        auto_pay: bool = True,
+        **kwargs,
+    ) -> requests.Response:
+        """
+        Executes HTTP request with autonomous X402 negotiation.
+        """
+        req_headers = dict(headers or {})
+
+        # 1. Dispatch initial request
+        resp = self.session.request(method, url, headers=req_headers, **kwargs)
+
+        # 2. If 402 Payment Required and auto_pay enabled, negotiate ZK proof
+        if resp.status_code == 402 and auto_pay:
+            logger.info("Received HTTP 402 Payment Required from %s. Negotiating proof...", url)
+            invoice = self.parse_invoice(resp)
+
+            if invoice.denomination > self.max_payment_per_call:
+                raise PermissionError(
+                    f"Invoice denomination ({invoice.denomination}) exceeds agent spending limit ({self.max_payment_per_call})"
+                )
+
+            # Retrieve unspent note from vault
+            note = self.vault.get_unspent_note(invoice.denomination)
+            if not note:
+                # If no note exists, create one for demonstration/testnet flow
+                note = self.vault.create_note(denomination=invoice.denomination)
+                logger.info("Generated note %s for invoice", note.nullifier_hash[:16])
+
+            # Generate Groth16 spend proof in RAM
+            proof_payload = self.prover.generate_proof(note, invoice)
+
+            # Attach standard X402 payment headers and retry
+            payload_json = json.dumps(proof_payload.to_dict())
+            req_headers["X-Payment"] = payload_json
+            req_headers["X-PAYMENT"] = payload_json
+            req_headers["Authorization"] = f"X402 {payload_json}"
+
+            retry_resp = self.session.request(method, url, headers=req_headers, **kwargs)
+
+            if retry_resp.status_code in (200, 201, 204):
+                # Mark note as spent upon successful fulfillment
+                self.vault.mark_spent(note.nullifier_hash)
+                logger.info("Payment verified and fulfilled. Note %s marked spent.", note.nullifier_hash[:16])
+                return retry_resp
+            else:
+                logger.warning("Payment retry failed with status %d: %s", retry_resp.status_code, retry_resp.text)
+                return retry_resp
+
+        return resp
+
+    def get(self, url: str, **kwargs) -> requests.Response:
+        return self.request("GET", url, **kwargs)
+
+    def post(self, url: str, **kwargs) -> requests.Response:
+        return self.request("POST", url, **kwargs)
+
+    def put(self, url: str, **kwargs) -> requests.Response:
+        return self.request("PUT", url, **kwargs)
+
+    def delete(self, url: str, **kwargs) -> requests.Response:
+        return self.request("DELETE", url, **kwargs)