x402-bot

Add X402 crypto payments to any Telegram bot in one line of code.

x402-bot makes it trivial to gate bot commands behind USDC micropayments — no custodians, no accounts, no friction. Money flows directly on-chain.

Built on X402 — the open HTTP-native payment standard by Coinbase.

---

Quick Start

pip install x402-bot

from x402_bot import X402Config, x402_required

config = X402Config(
    price_usdc=0.01,
    pay_to="0xYourWalletAddress",
    network="base-mainnet",
)

paid_users = {}

@x402_required(config, payment_store=paid_users)
async def premium(update, context):
    await update.message.reply_text("🎉 Welcome, paying member!")

That's it. Users who haven't paid get payment instructions automatically.

---

Features

• 🔌 One decorator — gate any Telegram handler behind payment
• 💸 Direct on-chain — USDC on Base or Solana, no middleman
• 🛡️ You don't touch the money — pure tooling, no custody
• ⚡ Instant verification — via Coinbase's free Facilitator
• 🤖 Bot-first design — built for Telegram, Discord coming in v2

---

Full Example

See assets/templates/telegram-bot-template.py for a complete working bot with:

• /start (free welcome)
• /premium (X402 gated)
• /verify (submit tx hash)
• /status (check payment)

Generate a customized bot

python scripts/scaffold.py \
  --type telegram \
  --price 0.01 \
  --network base-mainnet \
  --wallet 0xYourWallet \
  --output my_bot.py

---

How X402 Works (for bots)

User: /premium
  ↓
Bot: "Send 0.01 USDC to 0xABC on Base"
  ↓
User: pays on-chain via their wallet
  ↓
User: /verify 0xTXHASH
  ↓
Bot: verifies → grants access
  ↓
User: /premium → 🎉 premium content

See references/x402-protocol.md for the full protocol spec.

---

Networks & Pricing

Network	Asset	Use case
base-mainnet	USDC	Production
base-sepolia	USDC (test)	Development

Minimum meaningful payment: ~$0.001 USDC (near-zero gas on Base).

---

OpenClaw Skill

This repo includes an OpenClaw skill (x402-bot.skill) — load it into any OpenClaw agent and it can scaffold X402 integrations for any bot automatically.

/skill install x402-bot.skill

---

Contributing

PRs welcome. See X402 ecosystem for the broader community.

License

MIT — free to use, modify, and distribute.