Skip to main content

Overview

NanoGPT supports accountless API calls for selected endpoints. To request an accountless x402 quote, send the API request without Authorization or x-api-key, and include x-x402: true. NanoGPT will return 402 Payment Required with available payment options. After paying, call the quoted completeUrl, replay the original endpoint with X-PAYMENT, or replay the original endpoint with Authorization: L402 <token>:<preimage> for Lightning L402. An unauthenticated API request without x-x402: true is treated as a normal unauthenticated request and returns 401 missing_api_key. NanoGPT does not generate x402 quotes for every unauthenticated request. Live demo: https://nano-gpt.com/x402 Only endpoints returned by GET /api/v1/x402/endpoints should be treated as public accountless x402 endpoints. Treat broad x402 support claims as release-gated by live smoke tests against localhost and production. Streaming chat/responses and long-running video generation have implementation coverage but are not the stable public contract yet.

API Host

Use https://api.nano-gpt.com for accountless requests, as the examples below do. Quotes name the host you called, so use the statusUrl and completeUrl from your quote as given. IPv6-only clients can use https://nano-gpt.com with the same paths; see API Hosts. Every public endpoint below returns quotes on https://api.nano-gpt.com. Quotes there are paid in XNO (nano, nano-exact) or, when configured, with Lightning (lightning-l402).

Endpoint Matrix

The supported endpoint matrix is machine-readable. Its schemes list reflects the payment rails enabled in the current deployment.
As of 2026-06-14, production advertises lightning-l402 on the public endpoints listed below. Continue to use GET /api/v1/x402/endpoints as the source of truth because enabled rails can be deployment-gated. Use ?supported=all to include beta and deferred routes:
If x402 is disabled, payment storage is unavailable, or completion replay is not configured, the default supported list is empty. The matrix is generated from lib/x402/publicEndpointContract.ts, which is also used by the runnable smoke test examples. Current public accountless endpoints: Only endpoints that return a valid 402 quote in smoke tests should be listed as supported. Do not assume other API endpoints support accountless payment until they appear as supported in the matrix and have passed live smoke tests.

Payment Schemes

Production 402 quotes currently advertise these schemes when enabled: XNO (nano, nano-exact) and Lightning L402 (lightning-l402) are the x402 payment options. x402 payments in USDC on Base and Solana (x402-exact, base-usdc, x402-solana-usdc) were removed on 2026-11-20. A signed Base or Solana X-PAYMENT now gets HTTP 410 with payment_method_removed.

Working Quote Examples

All initial quote examples below intentionally omit Authorization and x-api-key and include x-x402: true.

Text Chat

Image Generation

URL Scrape

Flow 1: Quote, Pay, Complete

To request an accountless x402 quote, send the API request without Authorization or x-api-key, and include x-x402: true. NanoGPT will return 402 Payment Required with available payment options.
For accountless payment challenges, key off the stable top-level payment object. The error object is kept for OpenAI-compatible error handling and may vary by endpoint. The legacy accepts, x402Version, and top-level requestHash fields may still appear for backwards compatibility and advanced protocol clients.
Treat the presence of payment as the accountless payment signal; do not depend on a single legacy error.code value. Top-level payment.statusUrl and payment.completeUrl mirror the primary advertised payment option when that option is a polling-style rail. When choosing a specific payment scheme, prefer the fields inside that option in payment.accepted[]. The exact replay option nano-exact has a statusUrl but no completeUrl: replay the original request with the signed block in X-PAYMENT, and the settlement marks the original quote record completed, so its statusUrl shows the result. Lightning L402 options also do not use completeUrl; successful completion is the replay of the original endpoint with the Authorization: L402 <token>:<preimage> header. After paying a nano quote, call:
Completion replays the stored original request. A payment is bound to the original method, path, body hash, quoted amount, and expiration. Expired, underpaid, already processing, or already completed payments are rejected. Nano quote-and-complete rails use scheme: "nano" and a unique payTo Nano address. Clients should copy the option-specific amountFormatted, payTo, statusUrl, and completeUrl from payment.accepted[].

Flow 2: x402 Exact Replay

For nano-exact, sign the advertised exact payment requirement and replay the original endpoint with:
Successful exact-settlement responses include X-PAYMENT-RESPONSE when a settlement hash is available. The exact replay request must use the same method, path, and JSON body that produced the quote:
NanoGPT validates exact X-PAYMENT replay against the quoted resource, amount, and expiration. Clients should replay the same request they quoted unless endpoint docs state otherwise.

Flow 3: Lightning L402 Replay

NanoGPT also supports Lightning L402 for accountless API payments. Instead of signing an X-PAYMENT payload, the client pays a Lightning invoice and proves payment by replaying the original request with the invoice preimage. To request an accountless Lightning L402 quote, send the original request without Authorization or x-api-key, and include x-x402: true:
When lightning-l402 is enabled, the 402 Payment Required response advertises a Lightning quote in payment.accepted[], with sats, USD price, discount, payment ID, expiration and invoiceUrl. Legacy accepts[] exposes extra.invoiceUrl. The quote contains no BOLT11 invoice, payment hash, token or Lightning WWW-Authenticate header. Its payTo is the invoice URL, not a BOLT11 string. The NanoGPT server creates no BTCPay invoice until the client requests one. Example Lightning option:
POST the option’s invoiceUrl with no body. Possession of the payment ID authorizes this call; no NanoGPT account or API key is required. Keep the payment ID and invoice URL private.
The response contains:
The invoice response also includes the WWW-Authenticate challenge with the same token in id="<token>" and a base64-encoded request value:
After decoding the request value, the JSON contains the Lightning invoice:
Pay the returned invoice with a Lightning wallet, node, or payment API that returns the payment preimage. Some consumer Lightning wallets do not expose the payment preimage; L402 clients need a wallet, node, or payment API that returns it after payment. Replay the exact original request with the same method, path, and JSON body, adding:
For chat completions, keep accountless L402 requests non-streaming:
Retrying the same invoiceUrl returns the published invoice and token, including concurrent requests. A 409 invoice_pending or 503 invoice_unavailable means creation or recovery is pending or uncertain: retry the same URL with backoff, respecting Retry-After and increasing the delay. Do not start another purchase merely to retry an ambiguous invoice. A claim becomes stale after 45 seconds (two 20-second BTCPay HTTP timeouts plus a 5-second margin). One caller atomically takes over and looks up GET /invoices?orderId=<paymentId> using the metadata.orderId assigned at creation. If multiple invoices exist, the server adopts the oldest New, unexpired invoice with matching BTC amount and quote identity, fetches its payment methods, and logs a diagnostic. Only a successful empty lookup allows a new invoice; failed or incomplete lookups retain the claim and return a retryable error. Existing paid, expired or mismatched invoices are not replaced. A 410 means start a new purchase with a fresh quote and Idempotency-Key: the quote expired or cannot fit a new invoice. Terminal payments return 409. New invoice creation is refused in the last 90 seconds of a quote. The server rounds the BTCPay lifetime down and reserves transport time, so the invoice may expire earlier than the quoted deadline; use the invoice response’s expiresAt (Unix seconds). Invoice requests are limited to 30 per minute per IP. Idempotency-Key on the original request continues to reuse the Lightning quote. A fresh quote key means a new purchase. Invoice creation and recovery are guarded by payment ID, even without an idempotency header. A fresh claim stops this server from starting a second creation while the first may still be in flight, and stale recovery reconciles BTCPay before considering another POST. BTCPay can still finish a request after our 20-second timeout, so a recovery may occasionally create a second invoice; only one invoice is ever published per payment ID, and an unpublished one expires unpaid. The L402 token is bound to the original method, path, request body hash, amount, and expiration. The token/preimage pair is single-use and expires with the quote. Lightning L402 quotes currently receive a 10% discount versus the normal accountless quote; when present, the Lightning option exposes discountRate and undiscountedAmountUsd. Minimal client logic:

Status Polling

For the nano quote-and-complete rail, use the quoted statusUrl to watch payment state:
Known statuses:
  • pending
  • underpaid
  • paid
  • processing
  • completed
  • failed
  • refunded
  • expired
Status responses include pollAfterSeconds, plus Retry-After and X-Poll-After headers. Async media status URLs are not documented as stable accountless x402 behavior until signed unauthenticated status and media URL behavior is smoke-tested and expiration is explicitly documented.

Troubleshooting

If you receive 401 missing_api_key immediately, check that the initial quote request includes x-x402: true. Without that header, NanoGPT does not enter the x402 quote flow.

Reconciliation

Image and data endpoint quotes are deterministic for the submitted request parameters. Chat Completions and Responses quotes are estimates and are reconciled after the provider returns usage. If provider execution fails after direct x402 settlement, the endpoint-specific failure path attempts the documented refund or failed-fee reconciliation. For completeUrl, NanoGPT replays the stored original request, so the completed request is bound to the quoted method, path, and body. For exact X-PAYMENT replay, NanoGPT validates the payment against the quoted resource, amount, and expiration. For Lightning L402 replay, NanoGPT validates the token and preimage against the quoted method, path, request body hash, amount, and expiration. Clients should replay the same request they quoted unless endpoint docs state otherwise. A tool follow-up, a request that sends back results for tool calls a paid response returned, is quoted and paid like any other request. Sending the earlier payment’s ID in x-x402-payment-id links the follow-up to those tool calls but does not pay for it. The link requires a completed payment, and each tool call can be continued by only one follow-up request; re-sending that same request, for example to pay its quote, still counts as that follow-up. Any wallet can pay for a follow-up: on /v1/responses it continues the same stored conversation, and its own payment ID links the next follow-up in the same way. Keep payment IDs private, because a payment ID is what lets a follow-up continue the conversation. Do not assume every accountless x402 payment is an exact final charge.

Helper Examples And Smoke Tests

Helper examples live in examples/x402. They cover:
  • quote request
  • choosing a payment rail
  • status polling
  • completeUrl
  • exact replay with X-PAYMENT
  • Lightning L402 replay with Authorization: L402 <token>:<preimage>
  • expired, underpaid, and failed completion handling via status/complete responses
Run the smoke tests against localhost or production:
Paid smoke paths are opt-in because the payment payload is wallet-specific:

Safety Notes

  • completeUrl payments are bound to the original request method, path, body hash, quote amount, and expiration.
  • Exact X-PAYMENT replay is validated against the quoted resource, amount, and expiration.
  • Lightning L402 replay is validated against the quoted method, path, request body hash, amount, and expiration.
  • Authorization: L402 <token>:<preimage> is bearer payment proof. Do not log full L402 authorization headers.
  • Expired payments cannot be completed.
  • Underpaid payments cannot be completed.
  • Completed or processing payments cannot be completed twice.
  • Store the original request only as long as needed for payment completion.
  • Do not log X-PAYMENT payloads, private keys, provider credentials, or full request bodies beyond existing request logging policy.