Skip to main content

hermes-x402-nano

A Hermes Agent plugin that lets the agent pay for HTTP resources with x402 exact on nano:mainnet (XNO). A payment guard runs before anything is signed.

It adds one tool, nano_x402_pay, in the toolset x402-nano. It is a pip entry-point plugin (hermes_agent.plugins → x402-nano) that registers through ctx.register_tool.

  • Pinned: hermes-agent==0.19.0, 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-REQUIRED header (or the body's x402 field). It answers with PAYMENT-SIGNATURE = base64 {x402Version: 2, resource, accepted, payload: {block}} and decodes PAYMENT-RESPONSE.
  • Proof of work: when extra.workOptional is not true (false or absent), work for the block's previous at extra.workThreshold is attached. The threshold is never easier than the send threshold. Work comes from NANO_WORK_URL (node-RPC work_generate shape) if set, else is computed locally. When workOptional is true, the placeholder 0000000000000000 is sent.

Install (one command, no install scripts)

pip install --only-binary :all: "hermes-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, the equivalent is uv pip install --no-build "hermes-x402-nano[test]==0.1.0".

To use it in your own Hermes setup: hermes plugins enable x402-nano (entry-point plugins are opt-in).

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 pass it to hermes_x402_nano.plugin.set_client(...).

A fresh account has to receive (open) before it can send. After funding the address, run hermes-x402-nano-receive once. It publishes receive/open blocks only and never sends.

Example: one paid call from the Hermes 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
hermes-x402-nano-demo https://pursekeeper.dev/v1/hash --method POST --body hello

hermes-x402-nano-demo (source: hermes_x402_nano/agent_example.py) runs Hermes' own run_agent.AIAgent loop:

  1. It uses a throwaway HERMES_HOME whose config.yaml enables x402-nano.
  2. enabled_toolsets=["x402-nano"], so Hermes discovers the plugin through its entry point and offers the tool.
  3. The model's tool call runs through Hermes' tool executor, and the result goes back to the model.

By default the model is a scripted OpenAI-compatible stand-in on 127.0.0.1, so no LLM key is needed. Its first turn calls nano_x402_pay once, and its second turn reports the result. To let a real model decide, pass --model NAME --base-url URL and set OPENAI_API_KEY. The demo prints the status, amount, block hash and body. It exits 0 only when the paid request returned 2xx.

Also free to try: hermes-x402-nano-demo "https://pursekeeper.dev/v1/fetch?url=https://example.com" --method GET.

The guard (all before signing)

  1. scheme exact on nano:mainnet, asset XNO; anything else → wrong_network
  2. payTo must be in NANO_X402_ALLOWED_PAYTO; an empty allowlist fails closed → pay_to_not_allowed
  3. amount ≤ per-call cap → over_per_call_cap
  4. spent + reserved + amount ≤ cumulative cap (in memory, per process; a signed block always counts) → over_total_cap
  5. a request already reserved or signed (same request_id, or same method + URL + body) is never signed again → duplicate_request
  6. 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 whose resource.url names another origin is refused
  7. malformed quotes (wrong x402Version, bad base64/JSON, missing or non-integer amount, bad payTo, bad maxTimeoutSeconds, extra or workThreshold) → malformed_quote
  8. 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
  9. one send block per call, built from the confirmed frontier (an unconfirmed frontier is refused), with balance = balance − amount and link = payTo
  10. 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 hermes_x402_nano.tests

The tests ship inside the package. 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 plugin's registration, and full AIAgent runs through the scripted model. They also check that the seed and key appear in no tool output, log or captured stream.

Licence

MIT

Metadata

Release files for hermes-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)

Source distribution for hermes-x402-nano 0.1.0
File Size Uploaded Provenance Actions
hermes_x402_nano-0.1.0.tar.gz 27.5 kB Without provenance Details for hermes_x402_nano-0.1.0.tar.gz

Built distribution (wheel)

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

Total release size: 63.1 kB

Release files / hermes_x402_nano-0.1.0.tar.gz

Download URL hermes_x402_nano-0.1.0.tar.gz
Size 27.5 kB
Tags Source
SHA-256 checksum
How to use checksums
87ded0e59bdc0f616329b6531c248abb83d2ad6f1d90a7c3828aab35644abb0e
BLAKE2b-256 checksum
How to use checksums
4ae4ded07ec309d81256cf29104c6d0df31a6ea116f082b069bc95eb119613b8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.5

Release files / hermes_x402_nano-0.1.0-py3-none-any.whl

Download URL hermes_x402_nano-0.1.0-py3-none-any.whl
Size 35.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d7a0ca32ed2fa1a88358d49464d82580f6945c68803f5bcbaa6c618c2161bbca
BLAKE2b-256 checksum
How to use checksums
6a1c559204bf871f3a71b078887b86cb0566b831a4e1e724abaed0aec759beb7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.5

Security for hermes-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.

Release history Release notifications | RSS feed

This release

0.1.0 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