What is x402?
x402 is a gasless payment protocol that enables AI agents and humans to make blockchain transactions without holding native gas tokens (SOL).Gasless Transactions
Facilitator pays Solana fees, voter only needs USDC
AI-Native
Designed for AI agents
Atomic Verification
Payment confirmed before resource access granted
Spec: https://x402.org
Facilitators
x402 requires a facilitator - a third-party service that pays gas fees and broadcasts transactions.| Provider | Devnet | Mainnet | URL |
|---|---|---|---|
| PayAI (Primary) | ✅ | ✅ | https://facilitator.payai.network |
| Coinbase (Backup) | ✅ | ❌ | https://x402.org/facilitator |
Vote Payment Flow
Step-by-Step Breakdown
1
1. Initial Vote Request
User requests to vote without payment proof
2
2. API Returns 402 Payment Required
Server calculates dynamic entry fee and returns payment requirementsResponse:
402 Payment RequiredHeaders:3
3. Build Transaction
Client builds USDC SPL token transfer
4
4. Sign Transaction
User signs transaction (wallet approval)
Voter signs the transaction but does NOT pay gas fees - facilitator pays SOL costs
5
5. Submit Signed Transaction
Client submits signed transaction with
X-Payment header6
6. Payment Verification & Settlement
API verifies and settles payment via facilitator
7
7. Record Vote
After successful settlement, API records vote in database
8
8. Return Confirmation
API returns vote confirmation to client
Payment Requirements Structure
TheX-Payment-Required header contains the following information:
- payTo: The recipient address (poll wallet public key)
- amount: The entry fee in base units (e.g., “769000” for 0.769 USDC)
- currency: The SPL token mint address (USDC)
- resource: The API endpoint URL being accessed
- extra.feePayer: The x402 facilitator’s fee payer address (pays SOL gas fees)
Security Considerations
Transaction Verification
Transaction Verification
API verifies transaction structure before settlement:
- Correct recipient (poll wallet)
- Correct amount (dynamic entry fee)
- Correct currency (USDC)
- Valid signature from voter
On-Chain Confirmation
On-Chain Confirmation
After settlement, API waits for blockchain confirmation before recording vote.Benefit: Prevents double-voting and ensures payment actually executed
Facilitator Trust
Facilitator Trust
System trusts facilitator to:
- Broadcast transactions honestly
- Pay gas fees
- Not censor transactions
Error Handling
| Error Code | Reason | Solution |
|---|---|---|
| 402 | Payment required / invalid | Build and submit proper x402 payment |
| 400 | Poll expired / already voted | Check poll status, verify voter hasn’t voted |
| 500 | Facilitator down / settlement failed | Retry or use backup facilitator |