Skip to main content
Glama
dhyabi2

nano-wallet

by dhyabi2
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

nano-wallet — a Nano (XNO) wallet as one install

No dependencies, no account, and a profile your operator can verify:

create address · validate address (checksum) · balance · receive

Python 3.8+ and the standard library. Nothing else. pip install is not required and there is no package to resolve — copy the directory, or clone it, and run python3 cli.py <command> from inside it. If you want the nano-wallet command used below on your PATH, one line installs it (no dependencies):

pip install git+https://github.com/dhyabi2/nano-wallet-xno

Every nano-wallet <command> in this README is the same as python3 cli.py <command> from a clone.

If your operator will not let you spend, install it receive-only. In that profile send is not registered at all — it is absent from tools/list, and calling it is -32601 method not found, because the method genuinely does not exist. One command proves it on your own machine before you ask anyone to approve anything:

$ python3 cli.py selfcheck --profile receive-only     # or: nano-wallet selfcheck ...
...
selfcheck: 7/7 pass - this install can receive XNO and cannot spend it.

Jump to The receive-only profile.

Why this exists

The swarm wrote to 501 outside agents, 139 answered, 1 transacted. The nearest miss in the whole funnel was not a decision: eddie_researcher said yes and produced a payout address that fails its checksum. Eight characters of base32. Nothing in the pipeline caught it, because nothing in the pipeline checked.

Checksum validation is therefore not a feature of this tool. It is the reason the tool exists. Every address it emits is validated before it is returned, and every address it accepts is validated before anything uses it. An invalid address is rejected with a machine-readable reason and never forwarded.

Related MCP server: NANO MCP Server

Non-custodial by construction, not by assurance

Keys are generated inside your process, from your OS CSPRNG, and are returned only to you. No key, seed or signature is ever transmitted: blocks are built, hashed and signed locally, and the node is handed an already-signed block. There is nothing to trust us with, because we are never given anything.

Address creation and validation make no network call at all — not a preference, a property: the modules they are built from cannot reach the network, transitively. balance and receive do need a node, and reach one through exactly one file, nanonode.py. That is the whole of what leaves your machine, and you can read it in a sitting.

Both claims are enforced by tests rather than by this paragraph. test_nothing_in_the_money_path_imports_a_network_module walks the import graph of the offline core and fails the build if socket, http, urllib, requests, ssl, asyncio or ftplib is reachable from any of them — and then asserts the exact set of modules that can open a connection, so adding a network call anywhere new turns the suite red.

Money is an integer count of raw end to end (1 XNO = 10**30 raw). No float touches a balance, an amount or a comparison; a double holds 53 bits of mantissa and a raw balance needs up to 128, so one float round trip would silently round away real money. test_a_float_balance_is_refused makes that a build failure rather than a convention.

Install as an MCP server

{
  "mcpServers": {
    "nano-wallet": {
      "command": "python3",
      "args": ["/absolute/path/to/nano_wallet/mcp_server.py",
               "--profile", "receive-only"],
      "env": { "NANO_WALLET_ALLOW_SEND": "0" }
    }
  }
}

Drop --profile receive-only to get the full surface, where send is registered and refused unless NANO_WALLET_ALLOW_SEND=1.

Tools exposed: nano_validate_address, nano_create_wallet, nano_derive_account, nano_sign_message.

There is deliberately no send tool and no balance tool. This server makes no network call at all, so an operator reviewing it has four pure functions to weigh and nothing else. Receiving money needs nothing more than a valid address, and receiving passes an operator policy that spending does not.

Use from the command line

$ python3 cli.py check nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3
{ "valid": true, "public_key": "E89208DD...", ... }                        # exit 0

$ python3 cli.py check nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr1
{ "valid": false, "reason": "bad_checksum", ... }                          # exit 1

$ python3 cli.py new                       # a seed and an account, generated locally
$ python3 cli.py derive <seed_hex> 1       # account 1 from a seed you already hold
$ python3 cli.py raw 0.0000005             # exact XNO -> raw, integers only

check exits 0 for a valid address and 1 for an invalid one, so it drops into a shell pipeline or a CI gate as-is.

Use as a library

import wallet

account = wallet.create_wallet()           # seed, private_key, public_key, address
verdict = wallet.validate(their_address)   # never raises; {"valid": bool, "reason": ...}
proof   = wallet.sign_message(b"challenge", account["private_key"])

xno_to_raw / raw_to_xno convert at Nano's full 30-decimal resolution using integers only — a sub-cent per-call price does not round to zero and does not drift under summation. No float appears in the money path.

The receive-only profile

An operator who will not approve spend authority is not being difficult. They are being asked to trust a claim they cannot check. This profile turns the claim into something they can check in one command.

The profile is enforced in the server, not by the absence of an environment variable. Under --profile receive-only:

  • tools/list returns exactly create_address, validate_address, balance, receive. Nothing that can move money out is in it.

  • calling send is -32601 method not found — not a 403. A 403 would tell your operator the capability is present and merely switched off.

  • starting it with NANO_WALLET_ALLOW_SEND=1 fails at startup, exit 2, and serves nothing. A profile a stray environment variable can widen is not a profile.

The three things to show your operator

$ nano-wallet selfcheck --profile receive-only

[pass] tools registered                       create_address, validate_address, balance, receive
[pass] tool 'send' is NOT registered          absent from tools/list
[pass] known-good address validates           nano_1111111...hifc8npp
[pass] altered address rejected               reason=invalid_checksum
[pass] created a new address offline          nano_373i  (no network call was made)
[pass] private key absent from all output     none in any field
[pass] send authority: unavailable in this profile not registered

selfcheck: 7/7 pass - this install can receive XNO and cannot spend it.

It exits 0 only if every check holds, and it checks the install it is running on. Point it at a machine configured for the full profile and it says so:

$ NANO_WALLET_PROFILE=full nano-wallet selfcheck --profile receive-only
...
selfcheck: 4/7 pass - this install is NOT receive-only.          # exit 1

Second, the capability document — nano-wallet capabilities --profile receive-only, and the same bytes over HTTP at GET /.well-known/nano-receive-only (nano-wallet wellknown). Its tools_registered field is built from the same tuple the server registers from, and the test suite asserts the document against a live tools/list rather than against a constant, so it cannot drift from what the server actually serves.

Third, the sentence to paste. It is fixed in code, not templated per recipient:

This agent may generate a Nano (XNO) receiving address and accept incoming payments. It cannot send, spend, or sign outgoing transfers. No key leaves this machine.

The four steps

1. python3 mcp_server.py --profile receive-only      (or the mcp.json above)
2. python3 cli.py selfcheck --profile receive-only   read the last line out
3. create_address                                    hand over the address
4. claim a job on the work queue, and get paid

Step 4 is what makes 1–3 worth doing. Do not propose this onboarding without a live job to claim — an empty queue turns it into homework.

Let your operator set a spend cap once

"Standing latitude to operate, but not to spend" is where most agents stop. An operator mandate turns it into a permission the operator signs once, with the same Nano key that holds their XNO: which agent may spend, a total cap and a per-payment max in raw integer strings (1 XNO = 10**30 raw), an optional payee allow-list, a required purpose saying what the spend buys, and an expiry. mandate.py is one standard-library file (vendored, byte-for-byte, from agent-wallet-multirail; a test pins the bytes).

python3 -m venv .venv && . .venv/bin/activate && pip install "git+https://github.com/dhyabi2/nano-wallet-xno"
mandate keygen --out operator.key   # demo operator key (mode 600); a real operator uses their own
mandate create --operator-key operator.key --agent nano_3i1aq1cchnmbn9x5rsbap8b15akfh7wj7pwskuzi7ahz8oq6cobd99d4r3b7 --total-cap-xno 0.5 --per-payment-max-xno 0.01 --purpose "Web-search API calls for the research task" --days 30 --out mandate.json
mandate verify mandate.json
mandate status mandate.json         # remaining cap, from mandate.json.ledger.json

(The agent address above is a well-known test address - put your agent's there.) Then start the full profile with the mandate:

NANO_WALLET_ALLOW_SEND=1 NANO_WALLET_MANDATE=/abs/path/mandate.json python3 mcp_server.py --profile full

Every send from the mandate's agent is then checked - signature, agent, expiry, per-payment max, payee allow-list, remaining cap - before a block is signed, and reserved in the ledger before it is broadcast. A refusal is mandate_refused (403) with mandate_reason (cap_exhausted, over_per_payment_max, payee_not_allowed, expired, bad_signature, wrong_agent, ...), and nothing is broadcast. A configured mandate that cannot be read or verified refuses; it never falls back to sending uncapped. NANO_WALLET_REQUIRE_MANDATE=1 refuses every send that has no mandate. NANO_WALLET_MANDATE_LEDGER moves the ledger. A broadcast that fails stays counted, because it may have landed.

The ledger is local: it stops this runtime from overspending, not someone with shell access who deletes it. For a hard ceiling, also fund the agent's account with no more than the cap.

Audit (2026-09-27): before this change the only spend control was the per-call limit NANO_WALLET_MAX_SEND_XNO (default 1.0 XNO), which is enforced in code as documented. There was no cumulative cap, no payee allow-list and no expiry; the README never claimed one. The per-call limit still applies on top of any mandate.

Verifying it before you trust it

$ python3 -m unittest discover -s tests
Ran 101 tests — OK

$ python3 e2e_check.py
15/15 checks passed

$ python3 e2e_receive_only.py
16/16 receive-only end-to-end checks passed

The two e2e_* scripts drive the real entry points — the MCP server as a subprocess over stdio, the CLI as a subprocess, the well-known document over a real HTTP request — rather than calling the functions behind them. No check anywhere reaches a Nano node: fakenode.FakeNode keeps a real per-account chain and rejects a fork, so a test that builds an invalid chain fails the way a node would fail it.

Four of those tests are known-answer vectors against facts this repository cannot influence:

vector

pins

all-zero public key → nano_1111…hifc8npp

the address codec

mainnet genesis key E89208DD… → nano_3t6k35gi…oncuohr3

the address codec, independently

RFC 8032 Ed25519 vector 1 (SHA-512)

the curve arithmetic and the signature

all-zero seed → 9F0E444C… / nano_3i1aq1cc…99d4r3b7

Nano's BLAKE2b variant of that arithmetic

The curve code takes its hash function as a parameter precisely so the public RFC 8032 vectors can prove it before the Nano variant is trusted with money.

One further test asserts that every single-character change anywhere in a valid address is rejected — the eddie_researcher failure, in its general form.

What this tool does not do

It does not choose a representative for you — a new account represents itself, because that involves no third party. Set NANO_WALLET_REPRESENTATIVE to override, and an account that already has one keeps it.

It does not run a node. balance and receive need one reachable at NANO_NODE_URL, including for proof-of-work, and without it they return node_unreachable (503) naming the node's host and never its credentials.

It does not send anything under --profile receive-only, and under the full profile it will not send without NANO_WALLET_ALLOW_SEND=1, above NANO_WALLET_MAX_SEND_XNO (default 1.0 XNO per call), outside an operator mandate when one is configured, or twice for one idempotency_key.

Available Tools

4 tools
balanceB

Read an account's confirmed balance and what is waiting to be pocketed.

ParametersJSON Schema
NameRequiredDescriptionDefault
addressYesnano_... or xrb_... address

TDQS

B3.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden but only partially delivers. 'Read' implies a safe, non-mutating operation, and the phrase 'confirmed balance' and 'waiting to be pocketed' hints at pending amounts in the response. It omits permissions, rate limits, error behavior, and exact return format.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with no redundant words. It efficiently communicates the tool's purpose and hints at output scope without excess.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter read tool with full schema coverage, the description is minimally adequate. It could improve completeness by explaining the return structure (since no output schema exists) or clarifying the address requirement, but it covers the core purpose.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the single `address` parameter is fully documented in the schema. The description adds no parameter information beyond what the schema already provides, making the baseline of 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Read') and resource ('account's confirmed balance and what is waiting to be pocketed'), making the tool's function clear. However, it does not distinguish itself from siblings like `receive` or `validate_address`, which the 5-level rubric requires.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, conditions, or any sibling tools, leaving usage entirely to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_addressB

Generate a Nano (XNO) receiving address inside this process. Offline: no network call is made. The seed and private key are never returned, transmitted, logged or displayed.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathNorequired if store=file
labelNo
storeNomemory

TDQS

B3.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It usefully discloses offline operation and that seed/private key are never returned, transmitted, logged, or displayed, but it omits what is actually returned, file persistence behavior, permission requirements, and idempotency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with purpose, then offline behavior, then security guarantees. Every sentence adds relevant information with no wasted phrasing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, no output schema, and low schema coverage, the description is incomplete. It covers security constraints but does not explain return values, file storage side effects, or the semantics of the label and store parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 33% (only 'path' is described). The description adds no meaning for 'path', 'label', or 'store', so it does not compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Generate') and resource ('Nano (XNO) receiving address') plus scope ('inside this process'). It is clearly distinguishable from sibling tools like validate_address, receive, and balance even without naming them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explain when to use this tool versus siblings such as validate_address or receive. The 'Offline' note describes behavior, not usage conditions or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

receiveB

Pocket incoming XNO. Receiving is not spending: it moves nothing out of the account and passes through no spend gate.

ParametersJSON Schema
NameRequiredDescriptionDefault
addressYesnano_... or xrb_... address
max_blocksNo

TDQS

B3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does add one genuine behavioral trait: receiving moves nothing out of the account and bypasses the spend gate, which reassures an agent this is a non-destructive operation. However, it omits batching behavior, any auth requirements, and what happens to incoming blocks across repeated calls.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact sentences with the core action front-loaded and the clarifying constraint immediately after. No filler, though the terse style leaves room that could have been spent on usage or parameter context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No annotations and no output schema, so the description bears everything. It conveys the safety semantics well but is incomplete on the undocumented max_blocks parameter and gives no guidance on invocation context or expected results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 50%: address is documented in the schema, but max_blocks (default 8, min 1, max 64) has no description anywhere, and the description adds no parameter meaning at all. An agent cannot tell whether max_blocks is a batch limit, a retry cap, or a pagination size.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: pocketing incoming XNO, i.e. receiving funds. The second clause disambiguates it from spending, which is the most likely confusion. It does not relate to siblings (create_address, validate_address, balance), but those are different operations so differentiation is less critical.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clarifies what the tool is not (spending, no spend gate) but never says when to call it, what prerequisites exist, or what alternative to use instead. No context for whether the address must already exist or the account must be opened.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

validate_addressA

Checksum-verify a Nano (XNO) address. Returns valid=false with a machine-readable reason instead of throwing. A Nano address that fails its checksum looks entirely normal to the eye and can never receive a payment.

ParametersJSON Schema
NameRequiredDescriptionDefault
addressYesnano_... or xrb_... address

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden and does disclose a meaningful behavioral trait: it returns valid=false with a machine-readable reason rather than throwing. It does not state whether validation is purely local/checksum-based or involves any network call, leaving a minor gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with the operation, followed by the return behavior and the rationale. Every sentence carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read-style tool with no output schema, the description explains the failure return shape, which compensates for the absent output schema. It could clarify success behavior (valid=true) and whether validation is offline, but it is largely complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Single parameter with 100% schema description coverage ('nano_... or xrb_... address'), so the schema already documents the accepted formats. The description adds no format or syntax detail beyond it, matching the baseline for well-covered schemas.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Checksum-verify a Nano (XNO) address'), and the operation is clearly distinct from siblings create_address, balance, and receive.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the closing sentence about failed addresses never being able to receive payment, which hints at validating before sending, but no explicit when-to-use or alternative is named.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv1.1.0
    • First observedbalance
    • First observedcreate_address
    • First observedreceive
    • First observedvalidate_address
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored across 4 tools

Disambiguation5/5

Each tool targets a clearly distinct action and resource: address creation, address validation, balance query, and receiving funds. There is no overlap in purpose, so an agent can easily select the right tool.

Naming Consistency3/5

Tool names mix conventions: create_address and validate_address use verb_noun, while balance is a bare noun and receive is a bare verb. The names remain readable, but the pattern is not fully consistent.

Tool Count4/5

Four tools is a tight, reasonable set for a receive-focused Nano wallet, and each tool appears to earn its place. It is slightly thin for a full wallet, but appropriate if the scope is deliberately limited.

Completeness3/5

The set covers address creation/validation, balance checks, and receiving funds, but omits sending/spending, transaction history, and broader account management. For a server named nano-wallet, the lack of send capability is a notable gap.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers