x402 Fast Monetization Template

March 14, 2026 · View on GitHub

Turn any Python function into a zero-gas AI Agent API — monetized with USDC, live in 3 steps.

What is this?

This template lets you monetize any Python function as a pay-per-call API using USDC and the x402 protocol. One decorator is all it takes. No subscription logic, no API keys to manage for your callers, no billing infrastructure.

The killer feature: SKALE on Base is the default chain. SKALE on Base has ultra-low gas fees (~$0.0007/tx via CREDITS) — AI agents and bots can make hundreds of micro-payments per minute without burning money on gas. On Base you pay ~$0.001 per transaction; on SKALE on Base you pay a fraction of a cent.

Quick Start (3 Steps)

1. Clone and install

git clone https://github.com/Wintyx57/x402-fast-monetization-template.git
cd x402-fast-monetization-template
pip install -r requirements.txt

2. Set your wallet

cp .env.example .env

Open .env and set your wallet address:

Need USDC? Bridge from any chain → SKALE in 1 click: x402bazaar.org/fund

WALLET_ADDRESS=0xYOUR_ACTUAL_WALLET_ADDRESS

3. Run

python main.py

Your API is live at http://localhost:8000/docs — open it to see the interactive Swagger UI.

How It Works

The x402 protocol reuses the HTTP 402 status code ("Payment Required") to create a machine-readable payment flow that AI agents can navigate autonomously:

Client / AI Agent                 Your API                      Chain (SKALE or Base)
        |                              |                                  |
        |  1. GET /generate_qr         |                                  |
        |----------------------------->|                                  |
        |                              |                                  |
        |  2. 402 + payment_details    |                                  |
        |    (amount, wallet, network) |                                  |
        |<-----------------------------|                                  |
        |                              |                                  |
        |  3. Send USDC on SKALE       |                                  |
        |---------------------------------------------------------------->|
        |                              |                                  |
        |  4. GET /generate_qr         |                                  |
        |    + X-Payment-TxHash: 0x... |                                  |
        |    + X-Payment-Chain: skale  |                                  |
        |----------------------------->|                                  |
        |                              |  5. Verify tx on-chain           |
        |                              |--------------------------------->|
        |                              |                                  |
        |  6. 200 + result             |                                  |
        |<-----------------------------|                                  |

Client calls your API without payment
Server responds 402 with payment details (amount, recipient, USDC contract, all supported networks)
Client sends USDC on the chain of its choice
Client retries with X-Payment-TxHash and optionally X-Payment-Chain headers
Server verifies the on-chain transaction (correct recipient, sufficient amount, not replayed)
Access granted — your function executes and returns the result

Supported Networks

Chain	Gas Cost	USDC Contract	Chain ID
Base	~$0.001	`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`	8453
SKALE on Base (default)	~$0.0007 (CREDITS gas token)	`0x85889c8c714505E0c94b30fcfcF64fE3Ac8FCb20`	1187947933
Polygon	~$0.001 (MATIC)	`0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359`	137

All chains are listed in the 402 response under payment_details.networks so agents can pick the cheapest option automatically.

To change the default chain, set DEFAULT_CHAIN=base or DEFAULT_CHAIN=polygon in your .env.

The @x402_paywall Decorator

One decorator turns any Python function into a paid FastAPI endpoint:

@x402_paywall(price=0.05, description="My paid API", tags=["cool"])
def my_function(param: str) -> dict:
    return {"result": f"You sent: {param}"}

What happens automatically:

The function name becomes the endpoint path (/my_function)
Function parameters become URL query parameters (?param=hello)
The return type hint controls the response format:
- dict -- JSON response
- bytes -- Binary response (e.g., PNG image)
- str -- Plain text response
Callers without a valid payment get a 402 with full payment instructions
Callers with a valid X-Payment-TxHash get the function result

The 402 response body that agents receive:

{
  "error": "Payment Required",
  "payment_details": {
    "amount": "0.05",
    "currency": "USDC",
    "network": "SKALE on Base",
    "chain_id": 1187947933,
    "recipient": "0xYOUR_WALLET_ADDRESS",
    "usdc_contract": "0x85889c8c714505E0c94b30fcfcF64fE3Ac8FCb20",
    "networks": [
      { "chain": "base", "label": "Base", "chain_id": 8453, "gas": "~\$0.001", ... },
      { "chain": "skale", "label": "SKALE on Base", "chain_id": 1187947933, "gas": "~\$0.0007 (CREDITS)", ... }
    ],
    "instructions": "Send USDC on SKALE on Base to the recipient address, then retry with headers X-Payment-TxHash: 0x... and X-Payer-Address: 0x... Optionally add X-Payment-Chain: base|skale to select the network."
  }
}

Add Your Own API

Open main.py and go to Section 5. Adding a new paid endpoint is 3 lines:

@x402_paywall(price=0.02, description="Search my database", tags=["search", "data"])
def my_api(query: str, limit: int = 10) -> dict:
    results = do_something(query, limit)
    return {"data": results}

Restart the server — your endpoint is live at GET /my_api?query=hello&limit=5 and visible in /docs.

Decorator parameters:

Parameter	Type	Required	Description
`price`	`float`	Yes	Price in USDC per call
`description`	`str`	No	Shown in Swagger UI and marketplace
`tags`	`list[str]`	No	Used for categorization

Included Examples

The template ships with 3 working endpoints, no external API keys required:

Endpoint	Price (USDC)	Description	Returns
`/generate_qr`	0.05	Generate a QR code image from text	PNG image
`/summarize`	0.03	Summarize text (extractive, word-freq)	JSON
`/random_joke`	0.01	Get a random programming joke	JSON

Environment Variables

Variable	Required	Default	Description
`WALLET_ADDRESS`	Yes	--	Your Ethereum address to receive USDC payments
`DEFAULT_CHAIN`	No	`skale`	Default payment chain: `skale` or `base`
`BASE_RPC_URL`	No	chain default	Override the Base RPC endpoint
`BAZAAR_REGISTRY_URL`	No	--	x402 Bazaar URL for auto-registering your endpoints
`API_BASE_URL`	No	`http://localhost:8000`	Public URL of your API (used for marketplace)
`PORT`	No	`8000`	Server listening port

Deploy

Replit (one-click):

Click the button above
Set WALLET_ADDRESS in the Replit Secrets tab
Hit Run — your API is live with a public URL

Railway / Render:

# Set environment variables in the dashboard, then deploy:
git push

Both platforms detect Python automatically. Set WALLET_ADDRESS and optionally DEFAULT_CHAIN in the environment variables panel.

Links

Resource	URL
x402 Bazaar marketplace	x402bazaar.org
Backend API	x402-api.onrender.com
CLI (`npx x402-bazaar`)	x402-bazaar-cli
TypeScript SDK	x402-sdk
LangChain tools	x402-langchain
MCP Server	x402-backend

License

MIT — Use it, fork it, monetize with it.