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.

Note on outreach: Feeless402 does not open issues, pull requests or proposals on other projects. Posts elsewhere that pitch a "Nano rail" and name Feeless402 come from unaffiliated accounts, not from us. If one lands in your repo, feel free to close it. Questions: open an issue here.

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 hundreds of thousands of calls paid in Nano at true metered prices ($0.0000096/call observed live at nano-gpt.com, confirmed on-ledger). Top up once, micropay forever.

Install

pip install feeless402    # needs Python 3.10+; pulls nanopy + requests
# (from a checkout: pip install -e .)
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. If the merchant's reply is lost or is not a 2xx, the client asks the ledger about the block hash it signed before reporting anything: the receipt's settled is true, false, or "indeterminate", never a guess. A block that landed is never re-paid — re-present the same one. The client now does that re-presentation itself: every payment is journaled next to the wallet (pending-payments.json) before it is sent, and a retry — in the same call or after a crash — re-sends the same signed block with an X-PAYMENT-PROOF header (the payer's signature over the block hash, method and path). The server honors a proven re-presentation for 24 hours, so an observer replaying a public block cannot use up the payer's retries. (v0.2.9; reported privately by giskard09, who also re-verified the fix with an independent harness — see advisory GHSA-cx37-j5vc-c967. v0.2.10 adds two follow-ups from that re-verification: a block of unknown age is never treated as inside the window, and forwarded IP headers are trusted only from a configured proxy.)

v0.2.12 closes the remaining ways a client could pay twice. A ledger that cannot be reached is never read as "not paid"; a refusal gets the same confirmation window as every other outcome; a payment record that cannot be written or read stops the payment instead of being forgotten; and a payment record is tied to the request's body and query, so two different operations at the same price never share one. Also: the receipt checker raises Unreachable instead of NotFound when no node answers, and a blank F402_* setting means "use the default" (a blank top-up stays off). Reported by pyfile-toolkit (#10–#14) and [enricoaboujaoude-droid](https://github.com

... View full README on GitHub