langchain-x402-nano
A native LangChain tool that lets an agent pay for HTTP
resources with x402 exact on nano:mainnet (XNO). A payment guard runs before anything is signed.
The tool is nano_x402_pay, a langchain_core.tools.BaseTool (langchain_x402_nano.NanoX402PayTool).
Give it to any LangChain agent: create_agent(model, tools=[NanoX402PayTool()]).
- Pinned:
langchain==1.4.7,langchain-core==1.7.2,langgraph==1.2.18,langgraph-prebuilt==1.1.1,nanopy==28.0.1.post26(block building, blake2b, ed25519, CPU work),x402-nano-exact==0.1.2(scheme constants and address validation),requests==2.33.0. Python 3.11–3.13. - Wire format: reads the base64
PAYMENT-REQUIREDheader (or the body'sx402field). It answers withPAYMENT-SIGNATURE= base64{x402Version: 2, resource, accepted, payload: {block}}and decodesPAYMENT-RESPONSE. - Signing: a real Nano state send block signed with ed25519 by
nanopy, from the key in the environment (or a signer the operator injects). No placeholder signer. - Proof of work: when
extra.workOptionalis nottrue(false or absent), work for the block'spreviousatextra.workThresholdis attached. The threshold is never easier than the send threshold. Work comes fromNANO_WORK_URL(node-RPCwork_generateshape) if set, else is computed locally. WhenworkOptionalistrue, the placeholder0000000000000000is sent.
Install (one command, no install scripts)
pip install --only-binary :all: "langchain-x402-nano[test]==0.1.0"
--only-binary :all: installs wheels only, so no package build or install script runs. Every
dependency ships a wheel. With uv: uv pip install --no-build "langchain-x402-nano[test]==0.1.0".
Configure (environment only; nothing secret is in the package)
| variable | meaning |
|---|---|
NANO_SEED (+ NANO_INDEX, default 0) or NANO_PRIVATE_KEY |
the paying account. Read lazily, never logged, printed or returned |
NANO_X402_ALLOWED_PAYTO |
comma list of payTo addresses that may be paid. Empty = every payment refused |
NANO_X402_MAX_PER_CALL_XNO |
per-call cap, default 0.001 |
NANO_X402_MAX_TOTAL_XNO |
cumulative cap for this process, default 0.01 |
NANO_X402_ALLOWED_ORIGINS |
optional comma list of origins that may be paid |
NANO_RPC / NANO_ACCOUNT_INFO_API |
where the confirmed frontier and balance are read: a node RPC, else https://pursekeeper.dev/v1/account_info |
NANO_WORK_URL |
optional work server; local CPU otherwise (NANO_WORK_LOCAL=0 disables local work) |
You can inject a signer instead of using the environment: build NanoX402Client(policy, signer=...) with
any object that has .address and .sign_send(state, pay_to, amount_raw, work), then use
NanoX402PayTool(client=...) (or langchain_x402_nano.set_shared_client(...)). Every NanoX402PayTool()
without a client shares one env-configured client per process, so the cumulative cap covers all of them.
A fresh account has to receive (open) before it can send. After funding the address, run
langchain-x402-nano-receive once. It publishes receive/open blocks only and never sends.
Example: one paid call from LangChain's agent loop (Ӿ0.001 at pursekeeper.dev)
export NANO_SEED=... # throwaway wallet, funded with ~Ӿ0.01 and opened
export NANO_X402_ALLOWED_PAYTO=nano_1xug1q5t7nxoj3ywwzokiea9jz8fq8qfgzp8pbyfr3co3e5xgj755uofu8ue
langchain-x402-nano-demo https://pursekeeper.dev/v1/hash --method POST --body hello
langchain-x402-nano-demo (source: langchain_x402_nano/agent_example.py) is, in short:
from langchain.agents import create_agent
from langchain_x402_nano import NanoX402PayTool
from langchain_x402_nano.scripted_model import ScriptedToolCallModel
model = ScriptedToolCallModel(tool_args={"url": "https://pursekeeper.dev/v1/hash",
"method": "POST", "body": "hello", "content_type": "text/plain"})
agent = create_agent(model, tools=[NanoX402PayTool()])
state = agent.invoke({"messages": [{"role": "user", "content": "Fetch https://pursekeeper.dev/v1/hash ..."}]})
print(state["messages"][-1].content)
LangChain's own create_agent loop (LangGraph) binds the tool to the model (bind_tools), runs the
model's tool call through its tool node and feeds the result back to the model for the final answer.
By default the model is ScriptedToolCallModel, a local BaseChatModel that supports bind_tools, so
no LLM key is needed: its first turn calls nano_x402_pay once, its second reports the result. To let
a real model decide, pass --model provider:name (e.g. --model openai:gpt-4.1-mini, with
langchain-openai installed and OPENAI_API_KEY set). The demo prints the status, amount, block hash
and body. It exits 0 only when the paid request returned 2xx.
Also free to try: langchain-x402-nano-demo "https://pursekeeper.dev/v1/fetch?url=https://example.com" --method GET.
The guard (all before signing)
- scheme
exactonnano:mainnet, assetXNO; anything else →wrong_network payTomust be inNANO_X402_ALLOWED_PAYTO; an empty allowlist fails closed →pay_to_not_allowed- amount ≤ per-call cap →
over_per_call_cap - spent + reserved + amount ≤ cumulative cap (in memory, per process; a signed block always counts) →
over_total_cap - a request already reserved or signed (same
request_id, or same method + URL + body) is never signed again →duplicate_request - redirects: an unsigned probe follows same-origin redirects only; a cross-origin redirect stops the call unpaid
(
cross_origin_redirect); the signed request goes to the URL that answered 402 with redirects off; a quote whoseresource.urlnames another origin is refused - malformed quotes (wrong
x402Version, bad base64/JSON, missing or non-integer amount, badpayTo, badmaxTimeoutSeconds,extraorworkThreshold) →malformed_quote - freshness: if the quote is older than
maxTimeoutSeconds(less a 2 s margin) when it is time to sign, it is thrown away and re-fetched, and the new quote goes through the guard again; a quote is never re-used - one send block per call, built from the confirmed frontier (an unconfirmed frontier is refused), with
balance = balance − amountandlink = payTo - no automatic paid retry: a non-2xx (or a network error) after the payment is returned to the agent with the block hash. A 402 "not confirmed" answer is returned, not re-presented
Offline tests
python -m pytest -p no:cacheprovider --pyargs langchain_x402_nano.tests
The tests ship inside the package (from a checkout, python -m pytest also works). They make no network
connections (any non-loopback connect fails the test) and use a mocked 402 seller. They cover every
guard rule above, block correctness (hash and signature), the PoW paths, the receive command, the tool's
LangChain schema, and full create_agent runs through the scripted model (the tool is called exactly once
and one block is signed). They also check that the seed and key appear in no tool output, log or captured stream.
Licence
MIT
Metadata
Release files for langchain-x402-nano 0.1.0
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_x402_nano-0.1.0.tar.gz | 26.9 kB | Without provenance | Details for langchain_x402_nano-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| langchain_x402_nano-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for langchain_x402_nano-0.1.0-py3-none-any.whl |
Total release size: 62.3 kB
Release files / langchain_x402_nano-0.1.0.tar.gz
| Download URL | langchain_x402_nano-0.1.0.tar.gz |
|---|---|
| Size | 26.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6eaf6221a7cf30c280f5ca86dde41c294369f27a23cfec50fb9929a9ae40087e
|
|
BLAKE2b-256 checksum How to use checksums |
0674cfe26f0e40b0fcdcbaed26cc55d16ac22168827cbd9ef674d0bab8b21149
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.5
|
Release files / langchain_x402_nano-0.1.0-py3-none-any.whl
| Download URL | langchain_x402_nano-0.1.0-py3-none-any.whl |
|---|---|
| Size | 35.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
152ed91e3ece8239fab6f0fed755373696aac2127363265d972390ac1d27ca6d
|
|
BLAKE2b-256 checksum How to use checksums |
fea614411b488686d258d230eee6adcce4fc5dbd12bf203b95dfff280c76a092
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.5
|
Security for langchain-x402-nano 0.1.0
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.