Adding x402 Micro-Payments to Any Gaia Node

Turn your self-hosted LLM into a revenue stream—no user accounts, no Stripe keys, just one HTTP call.

Why a Payment Layer Matters for Open-Source AI

Running an LLM on your own Gaia Node is powerful, but GPU time isn’t free. Until now, most hobby projects either:

• exposed the endpoint for nothing (and hoped traffic stayed tiny), or
• hide it behind an API-key system that required custom billing logic.

x402 fixes that. It’s an open payment standard built around the long-ignored HTTP 402 Payment Required status code. With x402:

1. A client hits your endpoint → server replies 402 with a price and a payment pointer.
2. The client signs and broadcasts a small on-chain transaction.
3. The same HTTP request is retried—this time the server verifies payment and returns the LLM response.

No sessions, no OAuth, no wallets on your server.

What We Built

Gais’s Developer Relations Lead, Harish Kotra spun up a demo that turns any Gaia Node into a paid API:

• Backend – a tiny server.js proxy that:
  • exposes three /chat-style routes, each with its own price in test-USDC
  • forwards paid requests to the local client  (localhost:4021/v1) which takes care of calling the Gaia Node’s OpenAI compatible API
• Client – a CLI script that:
  • generates a burner wallet with viem
  • pays in Base Sepolia USDC via x402
  • prints the LLM answer and the transaction hash

🔗 Code & quick-start: https://github.com/GaiaNet-AI/gaia-cookbook/tree/main/js/gaia-x402

Why x402 + Gaia Makes Sense

• No gas fees - users don’t have to worry about paying gas fees but simply interact with applications with ease
• Fine-grained pricing – decide how you want to price your API requests. Example showcases multiple options from 0.01 USDC, 0.008 USDC, etc.
• Chain-agnostic – works on any EVM network; we chose Base Sepolia to showcase this as an example .
• Fits Gaia’s open-source ethos – the whole repo is MIT-licensed; swap in your own prompts or models.

Trying the Demo Yourself (≈ 10 min)

1. Clone & Install git clone https://github.com/GaiaNet-AI/gaia-cookbook.git

cd js/gaia-x402 && npm i

2. Fire up a local Gaia Nodegaianet init

gaianet start

3. Configure Environment Variables

• Copy the .env.example file to a new file named .env
  • cp .env.example .env
• Open .env and fill in the required values
  • PORT: Port for the server (e.g., 4021).
  • RECEIVING_WALLET_ADDRESS: Your wallet address to receive API payments.
  • GAIA_API_KEY: Your API key for the Llama/Gaia service.
  • GAIA_API_URL: The base URL for the Llama/Gaia API.
  • NETWORK: The blockchain network (e.g., base-sepolia).
  • FACILITATOR_URL: The x402 facilitator URL for the chosen network.
  • PRICE_FULL_COMPLETION, PRICE SUMMARY, PRICE_ONE_WORD: Prices for each service.
  • BURNER_WALLET_PRIVATE_KEY: The private key for the client's burner wallet (must start with @x).
  • BASE_SEPOLIA_RPC_URL: RPC URL for the client to interact with Base Sepolia.
  • CLIENT_TARGET_SERVER_BASE_URL: URL where the client will find your server.js.
  • CLIENT_DISPLAY_PRICE_FULL, etc.: Prices shown to the client (should match server).

IMPORTANT: Never commit your .env file with sensitive data to a public repository. The .gitignore file should already be configured to ignore it.

4. Run the server

node server.js

5. Run the client, fund the burner wallet, and pick an option from the menu.

node client.js

You’ll see:

• price quote → automatic on-chain payment
• JSON response from your LLM
• Tx hash to verify on https://sepolia.basescan.org

What You Can Build Next

Next Steps

• 🚀 Fork the repo – https://github.com/GaiaNet-AI/gaia-cookbook/tree/main/js/gaia-x402
• 🛠️ Launch your own Gaia Node – quick-start docs at https://docs.gaianet.ai/node-guide/quick-start
• 🌐 Grab a Gaia Domain – give your paid endpoint a memorable name: https://www.gaianet.ai/gaia-domain-name

Have questions or want your build featured? Drop into our Discord or tag @Gaianet_AI on X. Let’s see what you monetize next!