Skip to main content

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 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

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)

Source distribution for langchain-nano-x402 0.1.1
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)

Table of built distributions (wheels) for langchain-nano-x402 0.1.1
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page