Verify once, pay instantly, access everything
Selfx402 combines Self Protocol (zero-knowledge passport verification) with x402 (HTTP-native crypto micropayments) to create a decentralized marketplace where verified humans pay 1000-2000x less than bots.
- Identity Friction: Traditional marketplaces require lengthy KYC for each vendor
- Bot Attacks: Vendors can't distinguish humans from bots without invasive verification
- Payment Complexity: Crypto payments require accounts, wallets, complex setup
- Micropayment Inefficiency: Traditional rails make small transactions ($0.001-$1) uneconomical
One-time verification (Self Protocol) + Instant micropayments (x402) + Deferred settlement = Tiered pricing without gas overhead
Bot Request: $1.00 per API call
Human Request: $0.001 per API call (1000x cheaper)
Premium Human: $0.0005 per API call (2000x cheaper)
Key Innovations:
- Cryptographic proof of unique humanity (not just "I'm human", but "I'm a unique human with a real passport")
- Instant USDC micropayments on Celo blockchain using x402 protocol
- Deferred payment scheme (NEW!) - Aggregate micro-payments to reduce gas costs from 2000% to 2%
- Mobile-first verification (NEW!) - Deep link polling for seamless mobile Self app integration
The Selfx402 marketplace where consumers discover and access services with proof-of-human discounts
Service catalog and vendor listings with tiered pricing visualization
- Selfx402Pay/ - Next.js consumer frontend with Self Protocol QR verification
- Vendors/Places-x402-Api/ - Express.js vendor API with x402 payment middleware
- Selfx402Facilitator/ - Payment verification and settlement service
graph TB
subgraph Client["CLIENT (Selfx402Pay Frontend)"]
Consumer[π€ Consumer]
Browser[π Next.js Web App]
SelfApp[π± Self Mobile App]
Wallet[π Crypto Wallet]
end
subgraph SelfMiddleware["SELF PROTOCOL MIDDLEWARE"]
QRGen[π± QR Code Generator<br/>@selfxyz/qrcode]
ProofCache[πΎ Proof Cache<br/>localStorage/90 days]
ClientSDK[π§ Pay Widget<br/>selfx402-pay-widget]
end
subgraph Facilitator["SELFX402 FACILITATOR"]
VerifyBackend[π Verification Service<br/>@selfxyz/backend]
PaymentFacilitator[π³ Payment Service<br/>EIP-712/3009]
NullifierDB[(ποΈ Nullifier DB<br/>PostgreSQL)]
end
subgraph Vendors["VENDOR ENDPOINTS"]
VendorMiddleware[π‘οΈ Selfx402 Framework<br/>selfx402-framework]
VendorAPI[π Vendor API Logic]
VendorServices[βοΈ Services<br/>AI, Data, Compute]
end
subgraph Blockchain["CELO BLOCKCHAIN"]
SelfContract[π Self Verifier<br/>0xe57F...5BF]
USDCContract[π΅ USDC Token<br/>0xcebA...118C]
end
Consumer -->|1. Browse| Browser
Browser -->|2. Request QR| QRGen
QRGen -->|3. Display QR| SelfApp
SelfApp -->|4. ZK Proof| ProofCache
ProofCache -->|5. Store 90d| Browser
Browser -->|6. API Request<br/>+ X-Self-Proof| VendorMiddleware
VendorMiddleware -->|7. Verify Proof| VerifyBackend
VerifyBackend -->|8. On-chain Check| SelfContract
VerifyBackend -->|9. Nullifier Check| NullifierDB
VerifyBackend -->|10. Tier Result| VendorMiddleware
VendorMiddleware -->|11. 402 Required| Browser
Browser -->|12. Sign Payment| Wallet
Wallet -->|13. EIP-712 Auth| PaymentFacilitator
PaymentFacilitator -->|14. Settle USDC| USDCContract
PaymentFacilitator -->|15. Proof| VendorMiddleware
Browser -->|16. Retry + Payment| VendorMiddleware
VendorMiddleware -->|17. Process| VendorAPI
VendorAPI -->|18. Execute| VendorServices
VendorServices -->|19. Response| Browser
style Client fill:#e3f2fd
style SelfMiddleware fill:#fff3e0
style Facilitator fill:#f3e5f5
style Vendors fill:#e8f5e9
style Blockchain fill:#fff9c4
style VerifyBackend fill:#ce93d8
style PaymentFacilitator fill:#ce93d8
style VendorMiddleware fill:#81c784
graph TB
subgraph "Consumer Side"
Consumer[π€ Consumer]
Browser[π Browser/Web App]
SelfApp[π± Self Mobile App]
Wallet[π MetaMask Wallet]
end
subgraph "Selfx402 Platform"
Marketplace[πͺ Marketplace Portal]
VerifyBackend[π Verification Backend<br/>Self Protocol SDK]
Facilitator[π³ Payment Facilitator<br/>EIP-712/3009]
DB[(ποΈ PostgreSQL<br/>Nullifier DB)]
end
subgraph "Vendor Side"
VendorDashboard[π Vendor Dashboard]
VendorAPI[π Vendor API<br/>+ Selfx402 Middleware]
VendorService[βοΈ Vendor Service<br/>Image Gen, LLM, etc.]
end
subgraph "Blockchain (Celo Mainnet)"
Celo[βοΈ Celo Mainnet<br/>Chain ID: 42220]
SelfContract[π Self Protocol<br/>0xe57F...5BF]
USDCContract[π΅ USDC Token<br/>0xcebA...118C]
end
Consumer -->|1. Browse| Marketplace
Marketplace -->|2. QR Code| SelfApp
SelfApp -->|3. ZK Proof| Browser
Browser -->|4. Request| VendorAPI
VendorAPI -->|5. Verify| VerifyBackend
VerifyBackend -->|6. Validate| SelfContract
VerifyBackend -->|7. Check| DB
VendorAPI -->|8. 402 Response| Browser
Browser -->|9. Sign| Wallet
Wallet -->|10. Authorization| Facilitator
Facilitator -->|11. Settle| USDCContract
Wallet -->|12. Payment| VendorAPI
VendorAPI -->|13. Service| VendorService
VendorService -->|14. Response| Browser
VendorDashboard -->|Register| VendorAPI
VendorDashboard -->|Monitor| DB
style Celo fill:#fcff52
style SelfContract fill:#a8dadc
style USDCContract fill:#a8dadc
style Marketplace fill:#457b9d
style VerifyBackend fill:#457b9d
style Facilitator fill:#457b9d
sequenceDiagram
actor Consumer
participant Browser
participant Marketplace
participant SelfApp as Self Mobile App
participant VendorAPI as Vendor API
participant VerifyBackend as Selfx402 Verification
participant Facilitator as Selfx402 Facilitator
participant Wallet as MetaMask
participant Celo as Celo Blockchain
rect rgb(240, 248, 255)
Note over Consumer,SelfApp: Stage 0: One-Time Passport Enrollment
Consumer->>SelfApp: 1. Download Self app
Consumer->>SelfApp: 2. Scan passport NFC (30s)
SelfApp->>SelfApp: 3. Verify chip signature
SelfApp->>SelfApp: 4. Store encrypted data locally
Note over SelfApp: Passport data NEVER uploaded
end
rect rgb(255, 250, 240)
Note over Consumer,Celo: Stage 1: First-Time Vendor Verification
Consumer->>Browser: 5. Browse marketplace
Browser->>Marketplace: 6. Select service
Marketplace->>Browser: 7. Display QR code
Note over Marketplace: Requirements: ageβ₯18,<br/>nationality safe, OFAC
Consumer->>SelfApp: 8. Scan QR code
SelfApp->>Consumer: 9. Request consent
Consumer->>SelfApp: 10. Approve
SelfApp->>SelfApp: 11. Generate ZK proof
Note over SelfApp: Output: {ageValid: true,<br/>nullifier: "0xabc..."}
SelfApp->>Browser: 12. Send proof
Browser->>Browser: 13. Cache proof (90 days)
Browser->>VendorAPI: 14. API request + X-Self-Proof
VendorAPI->>VerifyBackend: 15. Validate ZK proof
VerifyBackend->>Celo: 16. Verify on-chain
VerifyBackend->>VerifyBackend: 17. Check nullifier DB
VerifyBackend->>VendorAPI: 18. Return tier: verified_human
VendorAPI->>Browser: 19. 402 Payment Required ($0.001)
Browser->>Wallet: 20. Request payment
Wallet->>Consumer: 21. Review & approve
Consumer->>Wallet: 22. Sign EIP-712
Wallet->>Facilitator: 23. Payment authorization
Facilitator->>Facilitator: 24. Verify signature
Facilitator->>Celo: 25. Execute USDC transfer (EIP-3009)
Facilitator->>Wallet: 26. Settlement proof
Wallet->>VendorAPI: 27. Retry with X-Payment
VendorAPI->>VendorAPI: 28. Process request
VendorAPI->>Browser: 29. Service response
Browser->>Consumer: 30. β Success! Saved $0.999 vs bot
end
sequenceDiagram
actor Vendor
participant Dashboard as Vendor Dashboard
participant Selfx402 as Selfx402 Platform
participant VendorAPI as Vendor API
participant Middleware as Selfx402 Middleware
participant Consumers as Consumers
rect rgb(240, 255, 240)
Note over Vendor,Selfx402: Registration & Setup
Vendor->>Dashboard: 1. Sign up
Vendor->>Dashboard: 2. Connect wallet
Vendor->>Dashboard: 3. Select membership tier
Note over Dashboard: Starter: $29/mo<br/>50k transactions
Vendor->>Dashboard: 4. Register API endpoint
Dashboard->>Selfx402: 5. Create vendor account
Selfx402->>Dashboard: 6. Generate API key
Vendor->>Dashboard: 7. Configure pricing
Note over Dashboard: Bot: $1.00<br/>Human: $0.001<br/>Premium: $0.0005
Vendor->>Dashboard: 8. Set verification requirements
Note over Dashboard: minimumAge: 18<br/>excludedCountries: [IRN, PRK]<br/>ofac: true
Dashboard->>Selfx402: 9. Save configuration
end
rect rgb(255, 245, 240)
Note over Vendor,Consumers: Integration
Vendor->>VendorAPI: 10. Install middleware
Note over VendorAPI: npm install selfx402-framework
Vendor->>VendorAPI: 11. Add middleware code
VendorAPI->>Middleware: 12. Initialize with API key
Middleware->>Selfx402: 13. Register endpoint
Note over VendorAPI,Middleware: Middleware handles:<br/>β’ Self proof validation<br/>β’ x402 payment processing<br/>β’ Transaction quota enforcement
end
rect rgb(245, 245, 255)
Note over Vendor,Consumers: Operations
Consumers->>VendorAPI: 14. API requests
VendorAPI->>Middleware: 15. Process via middleware
Middleware->>Selfx402: 16. Verify + settle
Middleware->>VendorAPI: 17. Allow/deny request
VendorAPI->>Consumers: 18. Service response
Selfx402->>Dashboard: 19. Update analytics
Vendor->>Dashboard: 20. Monitor usage
Note over Dashboard: 23,456 / 50,000<br/>transactions used
Dashboard->>Vendor: 21. Quota warning (80%)
Vendor->>Dashboard: 22. Upgrade tier or add credits
end
-
Enroll passport (one-time, 30 seconds):
# Download Self app (iOS/Android) # Scan passport NFC chip # Data stored encrypted on your device (never uploaded)
-
Browse marketplace β Scan QR code β Approve verification
-
Connect wallet β Sign payment β Access service
-
Enjoy 1000x cheaper pricing for 90 days (no re-scan needed)
Payment Options:
- Immediate: On-chain settlement per request (best for high-value transactions)
- Deferred: Off-chain vouchers, batch settlement (best for micro-payments <$0.01)
-
Sign up at
https://selfx402.com/vendors -
Select membership tier:
- Starter: $29/month, 50k transactions
- Professional: $99/month, 500k transactions
- Enterprise: $499/month, 5M transactions
-
Install framework:
npm install selfx402-framework
-
Add 5 lines of code:
import { Facilitator } from 'selfx402-framework'; app.use('/api', selfx402Middleware({ apiKey: process.env.SELFX402_API_KEY, network: 'celo', // Celo mainnet only (Phase 1) pricing: { bot: '1.00', // Your prices human: '0.001', premium: '0.0005' }, verification: { minimumAge: 18, excludedCountries: ['IRN', 'PRK'], ofac: true } }));
-
Deploy β Start accepting payments
Zero-Knowledge Proofs:
- Passport scanned once in Self mobile app
- Data encrypted and stored locally on device
- NEVER uploaded to any server (not Self, not Selfx402, not vendors)
What vendors see:
- β
Age requirement met:
true/false - β
Nationality requirement met:
true/false - β
OFAC compliant:
true/false - β Nullifier (unique ID, not traceable to passport)
What vendors CANNOT see:
- β Your name
- β Your actual age (only "β₯18: true")
- β Your actual nationality (only "not sanctioned: true")
- β Your passport number
- β Your photo
Sybil Resistance:
- Each passport generates unique nullifier
- Same passport β same nullifier (always)
- Different passport β different nullifier (always)
- Prevents one person from creating multiple "human" accounts
EIP-712 Signatures:
- Typed data signatures (phishing-resistant)
- Users see exactly what they're signing
- No direct wallet access required
EIP-3009 USDC Transfers:
- Gasless payments (no ETH needed for gas)
transferWithAuthorizationstandard- 2-second settlement on Celo blockchain
Payment Security:
- Nonce-based replay protection
- 1-hour validity window
- Signature verification by facilitator
- On-chain settlement proof
Celo Mainnet ONLY (Chain ID: 42220)
- USDC:
0xcebA9300f2b948710d2653dD7B07f33A8B32118Cβ EIP-3009 - Self Protocol:
0xe57F4773bd9c9d8b6Cd70431117d353298B9f5BF - RPC:
https://forno.celo.org - Explorer:
https://celoscan.io
Why Celo?
- β EIP-3009 USDC support (required for x402)
- β Self Protocol mainnet contract deployed
- β Low fees (<$0.01 per payment)
- β Fast finality (5 seconds)
- β Mobile-first ecosystem
| Tier | Price | Transactions | Features |
|---|---|---|---|
| Free | $0/mo | 1,000/mo | Basic verification, testing |
| Starter | $29/mo | 50,000/mo | Custom requirements, priority routing |
| Professional | $99/mo | 500,000/mo | Multi-tier pricing, advanced analytics |
| Enterprise | $499/mo | 5,000,000/mo | Dedicated instance, white-label, SLAs |
Overage: $0.10 per 1,000 transactions above tier limit
Typical vendor pricing:
- Unverified (Bot): $1.00 per request
- Verified Human: $0.001 per request (1000x cheaper)
- Premium Human: $0.0005 per request (2000x cheaper)
Key principle: Vendors set their own x402 prices. Selfx402 only verifies identity and processes payments.
- Framework: Next.js 14 with App Router
- UI Components: Radix UI primitives with shadcn/ui
- Self Integration:
@selfxyz/qrcodefor QR generation and verification - Payment: Ethers.js v6 for EIP-712 signing
- Styling: Tailwind CSS 4 with custom theme
- State: React hooks with localStorage caching
- Verification Backend: Node.js, Self Protocol SDK (
@selfxyz/backend) - Payment Facilitator: TypeScript, Viem, EIP-712/3009
- Database: PostgreSQL (nullifier deduplication)
- Cache: Redis (proof caching, rate limiting)
- Blockchain: Celo mainnet (Chain ID: 42220)
- Framework: Express.js with TypeScript
- Middleware: Custom Celo x402 payment middleware
- Tools: Viem for blockchain interactions
- Testing: Jest with end-to-end payment flow tests
selfx402-framework: Complete facilitator server framework with x402 + Self Protocol integration β npmselfx402-pay-widget: React payment widget for consumer applications β npm@selfxyz/qrcode: Self Protocol QR code generation (active)@selfxyz/backend: Self Protocol proof verification (active)
Critical Discovery: Self Protocol sends userContextData as hex-encoded bytes with EVM padding:
Raw hex: 000000000000000000000000000000000000000000000000000000000000a4ec000000000000000000000000c2564e41b7f5cb66d2d99466450cfebce9e8228f63623137633835332d353135612d346362622d623030302d6138653966616261306536613a687474703a2f2f6c6f63616c686f73743a33303030
Decoded: cb17c853-515a-4cbb-b000-a8e9faba0e6a:http://localhost:3000
Implementation (Selfx402Facilitator/index.ts:331-387):
- Decode hex to bytes
- Find first sequence of printable ASCII characters (skip padding)
- Extract text portion, remove null bytes
- Parse format:
"sessionId:vendorUrl"for polling, or just"vendorUrl"for QR-only
Mobile-First Architecture: Users can copy a universal link, paste on their phone, complete verification, and have the web UI automatically detect completion.
Key Components:
- Widget (Selfx402PayWidget/src/components/payment-form.tsx:616-633): Starts polling when "Copy Universal Link" is clicked
- Facilitator (Selfx402Facilitator/index.ts:425-452): Creates verification session in database after decoding userContextData
- Polling Endpoint (Selfx402Facilitator/index.ts:528-564): Returns verification status every 2 seconds
Session Format: Simple string "sessionId:vendorUrl" passed in userDefinedData when creating QR code
CRITICAL: Widget disclosure config MUST match vendor .well-known/x402 config or verification will fail:
Widget Config (Selfx402PayWidget/src/components/payment-form.tsx:206-211):
const disclosures = {
minimumAge: 18,
ofac: false,
excludedCountries: [] // MUST match vendor
}Vendor Config (Vendors/Places-x402-Api/src/config/x402.ts:126-131):
requirements: {
minimumAge: 18,
excludedCountries: [], // MUST match widget
ofac: false, // MUST match widget
documentTypes: ["Passport", "EU ID Card", "Aadhaar"]
}Reason: Self Protocol encodes disclosure requirements in the ZK proof circuit. Mismatched configs cause ConfigMismatchError.
- Docs/SELFX402-PRODUCT-DEFINITION.md - Complete product definition with architecture, business model, roadmap
- CLAUDE.md - Developer guide for working with this codebase
- Vendors/Places-x402-Api/README-CELO.md - x402 payment implementation
- Vendors/Places-x402-Api/CELO-X402-ARCHITECTURE.md - Architecture deep-dive
- Selfx402Facilitator/README.md - Payment facilitator service
- Docs/DEFERRED-PAYMENTS.md - Deferred payment scheme guide (NEW! π)
- Self Protocol: https://docs.self.xyz
- x402 Protocol: https://x402.gitbook.io
- Coinbase CDP x402: https://docs.cdp.coinbase.com/x402
- EIP-712: https://eips.ethereum.org/EIPS/eip-712
- EIP-3009: https://eips.ethereum.org/EIPS/eip-3009
- Start: October 14, 2025
- Current: October 17, 2025 (Day 4)
- Deadline: October 31, 2025 (Self ZK Residency)
- β x402 payment system on Celo mainnet
- β CeloFacilitator verification service
- β Custom payment middleware
- β Payment flow testing
- β Product definition and architecture
- β Deferred payment scheme (x402 PR #426 - Option A) π
- β Voucher database and aggregation system π
- β Self Protocol QR code verification π
- β Deep link polling for mobile verification π
- β Hex userContextData decoding π
- β Verification session tracking π
- β Published npm packages (selfx402-framework, selfx402-pay-widget) π
- π§ x402 payment integration with Self verification
- π§ Nullifier database implementation
- π§ Multi-tier pricing engine
- π§ Marketplace frontend MVP
- Working demo: Self verification β x402 payment β tiered pricing
- 3 example vendor integrations
- Consumer demo app with savings visualization
- Technical documentation
- Residency presentation
Self-x402/
βββ Vendors/
β βββ Places-x402-Api/ # Express.js API with x402 middleware (example vendor)
βββ Selfx402Facilitator/ # Payment verification service
βββ Selfx402App/ # Consumer application (planned)
βββ Docs/ # Documentation
β βββ SELFX402-PRODUCT-DEFINITION.md
βββ Media/ # Assets and images
βββ CLAUDE.md # Developer guide
βββ README.md # This file
1. Selfx402Facilitator (Terminal 1):
cd Selfx402Facilitator
PORT=3005 npx tsx index.ts2. Vendor API (Terminal 2):
cd Vendors/Places-x402-Api
npm run dev3. Test Payment Flow (Terminal 3):
cd Vendors/Places-x402-Api
npm run test:celoVendors/Places-x402-Api/.env:
PAYMENT_WALLET_ADDRESS=0x...
NETWORK=celo
PAYMENT_PRICE_USD=0.001
FACILITATOR_URL=http://localhost:3005Selfx402Facilitator/.env:
CELO_MAINNET_PRIVATE_KEY=0x...
CELO_MAINNET_RPC_URL=https://forno.celo.org
# For deferred payments (optional)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your_service_role_keyWe're in active development during Self ZK Residency (Oct 14-31, 2025).
Current priorities:
- Self Protocol integration (frontend + backend)
- Nullifier database and Sybil resistance
- Multi-tier pricing engine
- Marketplace frontend MVP
Get involved:
- Test the demo and provide feedback
- Suggest vendor use cases
- Review integration documentation
- Report bugs or UX issues
[Specify License - MIT, Apache 2.0, etc.]
- Self Protocol - Zero-knowledge passport verification
- x402 Protocol - HTTP-native crypto payments
- Coinbase CDP - Payment infrastructure
- Celo Network - Low-cost blockchain for micropayments
Project: Selfx402 (Self ZK Residency) Timeline: October 14-31, 2025 Status: Active Development
Built with β€οΈ for the Self ZK Residency

