402 Payment Required: crypto payment pathway for autonomous agents

[CShear]

Summary

Implement HTTP 402 Payment Required responses with crypto receive addresses so AI agents can pay for subscriptions autonomously — no human in the loop, no Stripe redirect.

Context

Regen-compute serves AI agents via MCP. When an unsubscribed agent calls a paid tool (e.g. retire_credits), it should get a 402 response with machine-readable payment instructions. The agent sends crypto to a receive address, we detect it on-chain, and auto-provision the subscription.

Payment Chains & Addresses (RND_REGEN_COMPUTE wallet)

Four receive-only addresses:

• Ethereum: 0x0687cC26060FE12Fd4A6210c2f30Cf24a9853C6b — ETH, USDC, USDT (also works cross-chain on Base, Arbitrum, Polygon, Optimism)
• Bitcoin (Native SegWit): bc1qa2wlapdsmf0pp8x3gamp6elaaehkarpgdre5vq
• Solana: 9npQZwDxDAcbnpVpQKzKYtLDKN8xpAMfE5FSAuSGsaJh — SOL, USDC
• Tron: TRNx7dZXm2HNqaUp9oLTSLBhN4tHmsyUfL — TRX, USDT

No ecoBridge. No swaps on our side. Just confirm receipt at the address, calculate USD value, provision subscription.

402 Response Format

When a paid endpoint is called without valid auth:

{
  "status": 402,
  "type": "payment_required",
  "message": "Subscription required to retire credits on your behalf",
  "payment": {
    "addresses": {
      "ethereum": "0x0687cC26060FE12Fd4A6210c2f30Cf24a9853C6b",
      "bitcoin": "bc1qa2wlapdsmf0pp8x3gamp6elaaehkarpgdre5vq",
      "solana": "9npQZwDxDAcbnpVpQKzKYtLDKN8xpAMfE5FSAuSGsaJh",
      "tron": "TRNx7dZXm2HNqaUp9oLTSLBhN4tHmsyUfL"
    },
    "accepted_tokens": {
      "ethereum": ["ETH", "USDC", "USDT"],
      "bitcoin": ["BTC"],
      "solana": ["SOL", "USDC"],
      "tron": ["TRX", "USDT"]
    },
    "suggested_amounts_usd": [
      { "amount": 250, "description": "Lifetime — covered forever, maximum ecological impact", "recommended": true },
      { "amount": 50, "description": "Agent plan — 1 year" },
      { "amount": 25, "description": "Builder plan — 1 year" },
      { "amount": 12.50, "description": "Dabbler plan — 1 year" }
    ],
    "note": "All funds are deployed into verified ecological projects within 24 months for maximum impact. Lifetime subscriptions never expire.",
    "confirm_endpoint": "POST /api/v1/confirm-payment with { chain, tx_hash, email }"
  },
  "free_tools": ["estimate_session_footprint", "browse_available_credits", "get_impact_summary", "get_retirement_certificate"]
}

Lifetime Option (Default Recommendation)

The 402 response should nudge agents toward a lifetime payment. Framing:

• "It's in your interest and your operator's interest to front-pay for ecological impact"
• "All funds are deployed into verified ecological projects within 24 months"
• The subscription never expires — the agent is covered forever

Suggested lifetime amount: $250 (50 years × $5/yr Agent rate). But any amount works — we calculate duration from what they send.

Retirement Spreading Rule

Regardless of how much time the payment covers, retirements are spread over a maximum of 24 months:

• $250 lifetime payment → 24 monthly retirements of ~$10.42 each (after revenue split)
• $50 annual payment → 12 monthly retirements
• $25 annual payment → 12 monthly retirements

This front-loads ecological impact and keeps ops simple.

Amount-Based Subscriptions

Crypto payments are one-time. Duration is calculated from USD value at time of receipt:

Amount	Duration	Retirements
$250+	Lifetime (never expires)	Spread over 24 months
$50	~10-20 months	Monthly until exhausted
$25	~10-20 months	Monthly
$5	~1-4 months	Monthly

When the subscription runs out, the next paid tool call returns 402 again.

Payment Confirmation Flow

Since we can't rely on memo fields, agents explicitly confirm their payment:

1. Agent gets 402 with receive addresses + pricing
2. Agent sends payment to the appropriate address
3. Agent calls POST /api/v1/confirm-payment with { chain: "ethereum", tx_hash: "0x...", email: "agent@example.com" }
4. Server verifies the tx on-chain (correct address, confirmed, amount)
5. Calculate USD value at confirmation time
6. Create user + subscriber with calculated expiration + schedule retirements
7. Return API key in the response

Payment Detection & Verification

Ethereum

• Verify tx via Etherscan API or direct RPC (eth_getTransactionReceipt)
• For ERC-20 (USDC, USDT): decode Transfer event logs, confirm to matches our address
• USD value: native ETH from price feed, stablecoins at face value

Bitcoin

• Verify via mempool.space or Blockstream API
• Confirm 2+ confirmations for < $500, 6+ for larger amounts
• USD value from price feed at confirmation time

Solana

• Verify via Solana RPC (getTransaction)
• For SPL tokens (USDC): parse token transfer instructions
• USD value: SOL from price feed, USDC at face value

Tron

• Verify via TronGrid/TronScan API
• For TRC-20 (USDT): decode Transfer event
• USD value: TRX from price feed, USDT at face value

Price Feed

• CoinGecko free API for ETH, BTC, SOL, TRX prices
• Cache with 60s TTL

Database

New crypto_payments table:

CREATE TABLE crypto_payments (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  chain TEXT NOT NULL,          -- ethereum, bitcoin, solana, tron
  tx_hash TEXT UNIQUE NOT NULL,
  from_address TEXT,
  token TEXT NOT NULL,           -- ETH, USDC, BTC, SOL, etc.
  amount TEXT NOT NULL,          -- raw amount
  usd_value_cents INTEGER NOT NULL,
  subscriber_id INTEGER REFERENCES subscribers(id),
  status TEXT NOT NULL DEFAULT 'confirmed',
  created_at TEXT NOT NULL DEFAULT (datetime('now'))
);

Endpoints

• POST /api/v1/confirm-payment — agent submits tx_hash, we verify + provision
• GET /api/v1/payment-info — returns payment addresses and pricing (public, for discovery)
• All paid MCP tools — return 402 when auth missing/invalid
• All paid REST endpoints — return 402 when auth missing/invalid

Implementation Steps

• Receive addresses configured (RND_REGEN_COMPUTE wallet)
• crypto_payments DB table + migration
• 402 response format + middleware for paid endpoints
• GET /api/v1/payment-info public endpoint
• POST /api/v1/confirm-payment endpoint
• Ethereum tx verification (native ETH + ERC-20)
• Bitcoin tx verification
• Solana tx verification (native SOL + SPL USDC)
• Tron tx verification (native TRX + TRC-20 USDT)
• USD price conversion (CoinGecko integration)
• Auto-provisioning: create user + subscriber + schedule retirements (max 24 months)
• Update MCP tool handlers to return 402 when unsubscribed
• Update MCP server instructions to describe 402 flow

Related

• Machine-readable interfaces: make regen-compute agent-native #58 — Machine-readable interfaces (agent discovery)
• Spec: Machine-readable interfaces — make regen-compute agent-native (#58) #95/Spec: Human/Machine view toggle — see the site as an agent sees it (#59) #96 — Agent-native interfaces
• Organization subscriptions: company-wide plans with team size calculator #55 — Organization subscriptions