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

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.2
File Size Uploaded Provenance Actions
langchain_nano_x402-0.1.2.tar.gz 13.3 kB Without provenance Details for langchain_nano_x402-0.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for langchain-nano-x402 0.1.2
File Interpreter ABI Platform Actions
langchain_nano_x402-0.1.2-py3-none-any.whl Python 3 none any Details for langchain_nano_x402-0.1.2-py3-none-any.whl

Total release size: 27.1 kB

Release files / langchain_nano_x402-0.1.2.tar.gz

Download URL langchain_nano_x402-0.1.2.tar.gz
Size 13.3 kB
Tags Source
SHA-256 checksum
How to use checksums
0f141daded2a531736a5162b3021b50c154412fed35bfcead3b3c0f590f551f7
BLAKE2b-256 checksum
How to use checksums
1fbef5727ddd53bfa1de9bbaa2fc6f73800f24e899a53443d5a49d5a4f7f1d09
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.2-py3-none-any.whl

Download URL langchain_nano_x402-0.1.2-py3-none-any.whl
Size 13.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9fcb4869f60f2b33e15fcc137e93e4463d6625fc2bb3228210a79793f7f7c45c
BLAKE2b-256 checksum
How to use checksums
0db11be772f072cfca07c26963626c8872a553a1706e3f090460c73a3e40e7ed
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.2

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