Metadata-Version: 2.5
Name: langchain-nano-x402
Version: 0.1.2
Summary: LangChain integration tool for autonomous Nano x402 resource purchasing with local payment guards
Author-email: BountyHunter AI <dextermos@users.noreply.github.com>
License: MIT
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: langchain-core==1.7.2
Requires-Dist: pydantic>=2.0
Provides-Extra: agent
Requires-Dist: langchain-openai>=0.3.0; extra == 'agent'
Requires-Dist: langchain==1.4.7; extra == 'agent'
Provides-Extra: dev
Requires-Dist: pynacl>=1.5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# langchain-nano-x402

Framework-native LangChain tool enabling autonomous AI agents to buy and consume pay-per-call HTTP resources over the **Nano (XNO) x402 protocol** (`nano:mainnet`), secured by strict client-side spend guards and zero-double-sign protections.

Published for **Initiative #13 (Slot 1: LangChain)** under the [pursekeeper integrations bounty](https://pursekeeper.dev/integrations).

---

## Features

- **Framework-Native**: Exposes `NanoX402Tool` deriving directly from LangChain's `BaseTool`.
- **Payment Guard**: Every payment quote must satisfy 7 offline security invariants before any block is signed:
  1. `network == "nano:mainnet"` (foreign networks rejected).
  2. `payTo` allowlist verification (optional operator pin).
  3. Per-call amount cap enforcement.
  4. Cumulative session spend cap enforcement.
  5. Deterministic request deduplication (never signs twice for the same request).
  6. Origin redirect protection (never pays cross-origin redirects).
  7. Quote expiration and structural validation.
- **Zero Secrets Leakage**: Private keys and seeds are injected via environment variables (`NANO_SEED` or `NANO_PRIVATE_KEY`) or passed as custom signers — never hardcoded, printed, or logged.
- **Pure Python Nano Cryptography**: Native Ed25519-Blake2b signing and address encoding in Python without external C compiler requirements.
- **Deterministic Driver**: Includes `example_run.py` to drive the tool through the loop without requiring an external model or OpenAI API key.

---

## Installation

```bash
pip install langchain-nano-x402
```

Or with `uv`:
```bash
uv add langchain-nano-x402
```

---

## Deterministic Execution (No LLM Required)

You can drive `NanoX402Tool` directly without an OpenAI API key using the included scripted runner:

```bash
export NANO_SEED=<64_hex_chars>
python example_run.py "https://pursekeeper.dev/v1/echo?msg=hello"
```

Or programmatically in Python:

```python
import os
from langchain_nano_x402 import NanoX402Tool, PaymentGuardConfig

# Configure local spend bounds
guard_config = PaymentGuardConfig(
    max_amount_raw_per_call=10**28,  # Cap: 0.01 XNO per call
    cumulative_cap_raw=10**29,       # Cap: 0.1 XNO cumulative session spend
    allowed_network="nano:mainnet",
)

# Instantiate tool
tool = NanoX402Tool(guard_config=guard_config)

# Execute paid call directly
result = tool.invoke({"url": "https://pursekeeper.dev/v1/echo?msg=hello", "method": "GET"})
print("Response:", result)
```

---

## Usage in a LangChain Agent Loop

```python
import os
from langchain.agents import AgentExecutor, create_react_agent
from langchain_core.prompts import PromptTemplate
from langchain_openai import ChatOpenAI
from langchain_nano_x402 import NanoX402Tool, PaymentGuardConfig

# 1. Configure local spend bounds
guard_config = PaymentGuardConfig(
    max_amount_raw_per_call=10**27,      # Cap: 0.001 XNO per call
    cumulative_cap_raw=10**28,           # Cap: 0.01 XNO cumulative session spend
    allowed_network="nano:mainnet",
)

# 2. Instantiate framework-native tool
tool = NanoX402Tool(guard_config=guard_config)
tools = [tool]

# 3. Bind to an agent loop
llm = ChatOpenAI(model="gpt-4o", temperature=0)
prompt = PromptTemplate.from_template(
    "Answer the question using tools: {tools}\n{tool_names}\nQuestion: {input}\n{agent_scratchpad}"
)
agent = create_react_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

# 4. Agent autonomously executes paid x402 fetch
result = executor.invoke({
    "input": "Fetch the echo verification message from https://pursekeeper.dev/v1/echo?msg=hello"
})
print("Result:", result["output"])
```

---

## Offline Security Tests

Run the complete offline test suite (100% mocked, 0 network access):

```bash
pytest tests/ -v
```

All 15 test cases assert strict rejection of malformed quotes, network mismatches, allowlist bypasses, per-call and cumulative cap breaches, duplicate invocations, redirect origin mismatches, and verify Nano cryptography and 402 challenge negotiation.

---

## License

MIT © Dexter Mos / BountyHunter AI
