nano-pay · Feeless402
Self-custodied Nano (XNO) wallet + x402 payment client and merchant
server, built for AI agents. Client spends; nano-pay serve earns — paid
endpoints, on-ledger verification/settlement (no facilitator), a starter
faucet, and the railHint x402 extension that teaches visiting agents how
to onboard (see SPEC-railhint.md). Site: site/index.html + site/llms.txt.
The pitch, in one number: the same $5 buys 5,000 API calls paid as
per-call USDC-on-Base x402 payments (merchants floor prices at 0.001 USDC),
or ~1.8 million calls paid in Nano at the true metered price
($0.0000027/call observed live at nano-gpt.com). Top up once, micropay
forever.
Install
pip install -e .
nano-pay init
Agent flow
nano-pay topup 5
nano-pay topup 5 --execute
nano-pay receive
nano-pay quote https://nano-gpt.com/api/v1/chat/completions \
--json '{"model":"gpt-5-nano","messages":[{"role":"user","content":"hi"}]}'
nano-pay pay https://nano-gpt.com/api/v1/chat/completions \
--json '{"model":"gpt-5-nano","messages":[{"role":"user","content":"hi"}]}'
pay handles the whole x402 handshake: request → parse the 402 quote
(both the x402nano/PAYMENT-REQUIRED v2 dialect and the NanoGPT/accepts
v1 dialect) → price-cap check → sign a send state block locally → retry
with PAYMENT-SIGNATURE + X-PAYMENT headers. The server settles the
block via its facilitator; nothing is broadcast unless the server accepts.
Design notes
- Self-custody: seed never leaves
~/.nano-pay/wallet.json (0600).
- No node required: public RPC failover (rpc.nano.to, somenano,
rainstorm.city, nanoslo); all signing and PoW happen locally (nanopy
C extension). RPC
work_generate is tried first, local PoW is the
fallback (~25s), and work for the next block is pre-cached after every
transaction so steady-state payments are instant.
- Safety rails: per-payment price cap (
--max-xno, default 0.05);
quote command inspects any endpoint's price without paying;
balance is always re-synced from the network, never trusted locally.
- Top-ups without custody:
topup quotes/creates swaps directly with
NanSwap's API (1,400+ input assets, ~$0.02 minimum). This tool never
holds or routes funds.
Fork-hazard note (x402 payments)
An x402 payment signs a block the server broadcasts. If the server
errors after receiving the block, it may still settle it late. The wallet
re-syncs its frontier from the network before every operation, so a late
settlement is picked up naturally; a competing block signed in the
meantime simply makes one of the two invalid (funds are never at risk,
but don't fire concurrent payments from one wallet).
Status
Beta (v0.2.0). Proven on mainnet with real funds: live paid calls to
NanoGPT ($0.0000096/call, confirmed on-ledger), full merchant loop
(verify → settle → confirm, no facilitator), PoW-gated faucet claims,
and a complete stranger-agent lifecycle (fresh wallet → PoW claim →
paid API call → confirmed) in under 3 minutes. 13-test suite covers the
payment path offline. Not audited — keep only working capital in it.
Security notes (read before holding real funds)
- Self-custody: the seed lives only in
~/.nano-pay/*.json (0600).
No tool or log path ever prints it. Back it up offline.
- Working capital only: this is beta wallet software. Keep a few
dollars in it, not your savings.
- Spend caps:
pay refuses quotes above --max-xno (default 0.05).
MCP x402_pay enforces the same cap parameter.
- railHint is advisory: hints from remote servers are untrusted
input. This client never executes remote bootstrap strings; it only
acts on structured offers that pass its own checks, and
accepts
always binds, never the hint.
- Merchant fork guard: servers cache accepted frontiers and reject
duplicate-frontier blocks; payer balance/frontier/signature are
verified against the live ledger before settlement.
- Not audited. MIT — no warranty.