Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nano-gpt.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

X-402 is an HTTP-native micropayment flow built around 402 Payment Required. With NanoGPT, X-402 lets clients pay for API calls without creating an account or pre-funding a NanoGPT balance:
  1. Client requests an API resource with the X-X402: true header to opt-in to payment flows.
  2. Server replies 402 Payment Required with payment options.
  3. Client pays using one of the offered schemes.
  4. Client retries the original request with X-PAYMENT (exact schemes), or completes the request after an on-chain transfer (polling schemes).
If you send a normal NanoGPT API key with sufficient balance, the request uses standard billing and will not trigger X-402.
Breaking Change (2026-04-05): X-402 payment flows now require explicit opt-in using the X-X402: true header. Without this header, users with insufficient balance will receive standard error responses instead of payment options.Existing clients using X-PAYMENT headers (already in the payment flow) continue to work without changes.

​
Supported Payment Schemes

NanoGPT can offer multiple schemes in a single 402 response:
SchemeNetworkAssetFlow
nanonano-mainnetXNOSend to an ephemeral address, then poll + complete
exactnano:mainnetXNORetry the original request with X-PAYMENT
exactbaseUSDCRetry the original request with X-PAYMENT (EIP-3009)
usdc-basebaseUSDCSend to an ephemeral address, then poll + complete

​
Flow A: Exact Schemes (X-PAYMENT header)

  1. Call an API endpoint with the X-X402: true header to opt-in to payment flows.
  2. Receive 402 with an accepts array that includes an exact option.
  3. Construct a base64-encoded JSON payment payload and retry the same request with the X-PAYMENT header.
  4. On success, the server returns the normal API response and may include X-PAYMENT-RESPONSE with settlement metadata.

​
Flow B: Polling Schemes (Ephemeral Address)

  1. Call an API endpoint with the X-X402: true header to opt-in to payment flows.
  2. Receive 402 with an accepts entry that includes payTo and paymentId.
  3. Send funds to payTo using a wallet.
  4. Poll GET /api/x402/status/{paymentId} until the payment is ready.
  5. Call POST /api/x402/complete/{paymentId} to execute the original request.

​
API Endpoints

​
Get Payment Status

GET /api/x402/status/{paymentId}
Response 
{
  "paymentId": "pay_abc123def456...",
  "status": "pending",
  "amountRequired": "0.05",
  "amountReceived": "0",
  "amountRemaining": "0.05",
  "payTo": "nano_1abc...",
  "expiresAt": 1700000900,
  "pollAfterSeconds": 2,
  "readyToComplete": false
}
Common status values include: pending, underpaid, paid, processing, completed, failed, refunded, expired.

​
Complete a Payment and Execute the Original Request

POST /api/x402/complete/{paymentId}
If the payment has not yet been settled (for example, if you are completing an exact scheme via the complete endpoint), include the same X-PAYMENT header you would use when retrying the original request. On success, the response body is the original endpoint’s response.

​
402 Response Format

When an endpoint returns 402 Payment Required, the body includes:
  • An OpenAI-compatible error object
  • x402Version
  • An accepts array with payment options
Example (shape): 
{
  "error": {
    "message": "Payment required.",
    "type": "insufficient_quota",
    "code": "insufficient_quota"
  },
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "nano",
      "network": "nano-mainnet",
      "maxAmountRequired": "50000000000000000000000000",
      "maxAmountRequiredFormatted": "0.05 XNO",
      "maxAmountRequiredUSD": 0.05,
      "resource": "/v1/chat/completions",
      "description": "Payment required - $0.0500 USD",
      "payTo": "nano_1ephemeral...",
      "paymentId": "pay_abc123...",
      "expiresAt": 1700000900,
      "callbackUrl": "/api/x402/status/pay_abc123...",
      "completeUrl": "/api/x402/complete/pay_abc123...",
      "extra": {}
    }
  ]
}
Some responses also include convenience headers such as X-Payment-Id, X-Payment-Address, and amount hints.

​
Supported Endpoints

The following endpoints support X-402 payment flows when the X-X402: true header is included:

​
Primary Endpoints

  • POST /api/v1/chat/completions
  • POST /api/v1/embeddings
  • POST /api/embeddings
  • POST /api/tts
  • POST /api/transcribe
  • POST /api/youtube-transcribe

​
OpenAI-Compatible Proxy Routes

These routes also support the X-X402 header and proxy to the primary endpoints:
  • POST /api/v1/messages → /api/v1/chat/completions
  • POST /api/v1/audio/speech → /api/tts
  • POST /api/v1/audio/transcriptions → /api/transcribe
  • POST /api/v1/responses → /api/v1/chat/completions

​
Migration Guide for Existing Clients

​
No Changes Required

Existing X-402 clients continue to work without modification because:
  • Requests with X-PAYMENT headers (payment retries) are automatically allowed
  • The core X-402 protocol remains unchanged
  • No changes needed for clients already in the payment flow

​
New Clients Only

Only new X-402 clients need to be updated to include the X-X402: true header on initial requests to opt-in to payment flows.

​
Error Response Changes

Clients may now see different error responses based on the opt-in header: Without X-X402: true header: 
{
  "error": "Insufficient balance",
  "requiredBalance": 0.0035,
  "status": 402
}
With X-X402: true header: 
{
  "error": {
    "message": "Payment required.",
    "type": "insufficient_quota",
    "code": "insufficient_quota"
  },
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "nano",
      "network": "nano-mainnet",
      "maxAmountRequired": "50000000000000000000000000",
      "maxAmountRequiredFormatted": "0.05 XNO",
      "maxAmountRequiredUSD": 0.05,
      "resource": "/v1/chat/completions",
      "description": "Payment required - $0.0500 USD",
      "payTo": "nano_1ephemeral...",
      "paymentId": "pay_abc123...",
      "expiresAt": 1700000900,
      "callbackUrl": "/api/x402/status/pay_abc123...",
      "completeUrl": "/api/x402/complete/pay_abc123...",
      "extra": {}
    }
  ]
}

​
Complete Example Comparison

Before the change (old behavior): 
# Any request without sufficient balance would trigger X-402 automatically
curl -X POST https://nano-gpt.com/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
# → Would return 402 with payment options
After the change (new behavior): 
# Without X-X402 header - returns standard error
curl -X POST https://nano-gpt.com/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini", 
    "messages": [{"role": "user", "content": "Hello"}]
  }'
# → Returns: {"error": "Insufficient balance", "requiredBalance": 0.0035, "status": 402}

# With X-X402 header - enables payment options
curl -X POST https://nano-gpt.com/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-X402: true" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
# → Returns 402 with X-402 payment options (accepts array)

​
Pricing Notes

  • Fixed-cost endpoints (for example, many media endpoints) can quote an exact USD amount in the 402 response.
  • Variable-cost endpoints (for example, chat completions) may quote a maximum based on your input and the requested output limit. If the final cost is lower than the quote, the difference may be refunded automatically.

​
Example: Polling (Nano)

# 1) Request with X-X402 opt-in header
curl -sS -X POST https://nano-gpt.com/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-X402: true" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 100
  }'

# 2) Send XNO to the returned payTo address, then poll status
curl -sS https://nano-gpt.com/api/x402/status/pay_abc123...

# 3) Complete the original request once paid
curl -sS -X POST https://nano-gpt.com/api/x402/complete/pay_abc123...

​
Example: Exact (Base USDC)

# 1) Request with X-X402 opt-in header -> receive 402 with accepts option: scheme=exact, network=base
curl -sS -X POST https://nano-gpt.com/api/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "X-X402: true" \
  -d '{
    "model": "dall-e-3",
    "prompt": "A sunset over mountains",
    "size": "1024x1024"
  }'

# 2) Retry the same request with X-PAYMENT (base64 JSON payload containing your signed authorization)
curl -sS -X POST https://nano-gpt.com/api/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <base64-encoded-payload>" \
  -d '{
    "model": "dall-e-3",
    "prompt": "A sunset over mountains",
    "size": "1024x1024"
  }'