nano-pay · Feeless402

<!-- mcp-name: com.feeless402/nano-pay -->

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 .          # needs Python 3.10+; pulls nanopy + requests
nano-pay init             # creates ~/.nano-pay/wallet.json (chmod 600)

Agent flow

nano-pay topup 5                    # quote: $5 USDC-BASE → ~12.3 XNO (NanSwap)
nano-pay topup 5 --execute          # create order (set NANSWAP_API_KEY)
#   → send USDC to the returned deposit address; XNO arrives in 30-60s
nano-pay receive                    # pocket incoming XNO
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.