Guide · Advanced · 2026
Two ways to paywall for AI agents: x402 vs on-chain token-gating
When people say “make agents pay,” they usually mean one of two designs. Mixing them up causes broken APIs and frustrated agents.
Option A — Server-side x402
The HTTP API returns 402 Payment Required with price and network details. The client pays (often via a facilitator), retries with proof, and the server returns 200.
- Best for pay-per-request APIs and open agent traffic
- No need for the agent to hold a specific NFT or membership mint
- Price can change per route; discovery is in the 402 body
- Works across many clients that speak HTTP
Option B — On-chain token-gating
The server (or a gateway) checks that the caller’s wallet already holds a token, NFT, or subscription position, then allows access. Payment happened earlier — mint, buy, or stream — not inside this HTTP round-trip.
- Best for membership, clubs, and “holders only” resources
- Agent must already own the asset; no in-request checkout
- Access logic is “do you hold X?” not “pay Y now”
- Often paired with sign-in-with-wallet, not 402
Side-by-side
| x402 | Token-gate | |
|---|---|---|
| Payment timing | Per request (or session in advanced schemes) | Up front / ongoing ownership |
| HTTP signal | 402 + requirements | Usually 401/403 if missing wallet proof |
| Agent UX | Discover price → pay → retry | Already hold token → prove wallet |
| Pricing shape | Micropayments, per route | Membership, tier, NFT seat |
| Refund / replay | Protocol + facilitator concerns | Token transfer / burn rules |
Can you use both?
Yes. Common split: token-gate a dashboard or community, and use x402 for metered API calls. Or sell a token that funds a prepaid balance, then drain with x402-style per-call charges. Keep the agent’s mental model simple: one request should not require three unrelated wallets.
Which should you ship first?
- Open tools and data APIs: start with x402.
- Holder communities and seats: start with token-gating.
- Unsure: prototype x402 on Devnet in an afternoon — if agents only need one cheap call, 402 fits better than minting a membership.
Ship x402 is an independent educational project. Not financial advice.