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.
Features
- Framework-Native: Exposes
NanoX402Toolderiving directly from LangChain'sBaseTool. - Payment Guard: Every payment quote must satisfy 7 offline security invariants before any block is signed:
network == "nano:mainnet"(foreign networks rejected).payToallowlist verification (optional operator pin).- Per-call amount cap enforcement.
- Cumulative session spend cap enforcement.
- Deterministic request deduplication (never signs twice for the same request).
- Origin redirect protection (never pays cross-origin redirects).
- Quote expiration and structural validation.
- Zero Secrets Leakage: Private keys and seeds are injected via environment variables (
NANO_SEEDorNANO_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.pyto drive the tool through the loop without requiring an external model or OpenAI API key.
Installation
pip install langchain-nano-x402
Or with uv:
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:
export NANO_SEED=<64_hex_chars>
python example_run.py "https://pursekeeper.dev/v1/echo?msg=hello"
Or programmatically in 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
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):
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
Metadata
Release files for langchain-nano-x402 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| langchain_nano_x402-0.1.1.tar.gz | 13.7 kB | Without provenance | Details for langchain_nano_x402-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| langchain_nano_x402-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for langchain_nano_x402-0.1.1-py3-none-any.whl |
Total release size: 28.0 kB
Release files / langchain_nano_x402-0.1.1.tar.gz
| Download URL | langchain_nano_x402-0.1.1.tar.gz |
|---|---|
| Size | 13.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
73f56484f5f31c9e0d46baa2863416e468a89c49230afb76b7675bbc2cf8ec1e
|
|
BLAKE2b-256 checksum How to use checksums |
8329b9237a81cbe0b40f9b529732b00a428f26e8ac472402eba519db91de7e10
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.13
|
Release files / langchain_nano_x402-0.1.1-py3-none-any.whl
| Download URL | langchain_nano_x402-0.1.1-py3-none-any.whl |
|---|---|
| Size | 14.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b89310e3990f1665ab23cd30f654a74ff85caaac3e17b3af10f504b4b96f0019
|
|
BLAKE2b-256 checksum How to use checksums |
5f070917322c5242c59f4a4332ccabb6b63b78d618fb804a13798240070af019
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.13
|
Security for langchain-nano-x402 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.