402-payment¶

Enabling micropayments for the F3L1X marketplace

402-payment implements the HTTP 402 Payment Required protocol, allowing realms to charge for premium tools and services on a per-use basis. It bridges herald's marketplace catalog with blockchain-ready payment infrastructure.

What It Does¶

402-payment sits between the marketplace and payment processing, enabling creators to monetize tools while users pay only for what they use. When a user requests a paid tool from herald, they receive a 402 response with payment details. They settle the payment through 402-payment, then receive tool access.

Think of it as a tollbooth for premium features in your AI infrastructure.

Key Capabilities¶

Payment Processing¶

• Per-Use Pricing: Tools priced per invocation, not subscription
• Instant Settlement: Payments complete in seconds
• Multiple Currencies: Support for USD, EUR, and stablecoin payments
• Receipt Generation: Automatic invoice creation for all transactions

Tool Monetization¶

• Creator Dashboard: Set pricing and monitor earnings
• Usage Analytics: Track tool usage and revenue metrics
• Pricing Rules: Create volume discounts or time-based pricing
• Payment Distribution: Automatic splits between creator and F3L1X platform

Blockchain Integration¶

• Crypto Payments: Accept Bitcoin, Ethereum, Stablecoins
• Smart Contracts: Future support for automated payment verification
• Wallet Integration: Connect external wallets for settlement

x402 Protocol¶

• Standard Compliance: Implements HTTP 402 Payment Required spec
• Seamless Fallback: Non-payment just means tool access denied (no errors)
• Client Libraries: SDKs for common languages to handle payments

Accessing 402-payment¶

Web Dashboard¶

URL: http://127.0.0.1:8086

The 402-payment dashboard shows:
- Transaction history
- Payment methods on file
- Tool pricing and creator earnings
- Usage analytics and reports

API Endpoints¶

WebSocket Endpoints¶

Common Use Cases¶

Use Case 1: Purchase Premium Tool Access¶

Goal: Pay for a specialized AI tool in the marketplace

1. Browse tool in herald marketplace
2. See "402 Payment Required" response
3. Click "Pay Now" in dashboard
4. Select payment method (credit card or crypto)
5. Complete payment in seconds
6. Receive tool access token
7. Tool executes immediately

Use Case 2: Monetize Your Custom Tool¶

Goal: Make your realm tool available for payment

1. Register tool in herald marketplace with pricing
2. Set price per invocation (e.g., $0.10 per call)
3. Monitor earnings in 402-payment creator dashboard
4. Withdraw payments to your preferred wallet
5. Enable volume discounts for loyal users

Use Case 3: Bulk Purchasing & Credits¶

Goal: Pre-purchase tool credits for team usage

1. Open 402-payment dashboard
2. Buy $100 credit bundle
3. Credit balance applies to all marketplace tools
4. Usage deducted from balance
5. Receive notifications when balance low

Important Notes¶

For End Users¶

Billing:
- Only charged when you use paid tools
- Each payment is instant and final
- Invoice sent immediately after transaction
- No subscriptions or hidden fees

Payment Methods:
- Credit/debit cards (Stripe integration)
- Crypto wallets (Bitcoin, Ethereum, stablecoins)
- Bank transfers for large amounts
- Pre-purchased credits

For Tool Creators¶

Earnings:
- 80% of payment goes to creator
- 20% platform fee supports F3L1X infrastructure
- Payments settle daily to your wallet
- Tax reporting tools included

Pricing:
- Set fixed per-use prices
- Or use variable pricing based on usage tiers
- Monitor real-time earnings
- Adjust pricing anytime

Security & Fraud Prevention¶

• PCI Compliance: Credit card processing via Stripe (PCI Level 1)
• Chargeback Protection: Tools locked during dispute periods
• Rate Limiting: Prevents abuse of expensive tools
• Wallet Verification: Multi-sig required for large transfers

Troubleshooting¶

"Payment failed" error¶

Symptom: Card declined or payment rejected
Fix: Try different payment method, check card details, verify sufficient balance

Tool still locked after payment¶

Symptom: Tool shows as unpurchased despite successful payment
Fix: Refresh dashboard, check invoice confirmation email, clear browser cache

Can't see pricing for tool¶

Symptom: Tool shows no price information
Fix: Tool may be free, or pricing not yet configured by creator

Withdrawal failed¶

Symptom: Creator can't transfer earnings to wallet
Fix: Verify wallet address, check if withdrawal threshold met ($5 minimum), check for pending disputes

Related Realms¶

• herald - Exposes marketplace tools that 402-payment monetizes
• f3l1x-dashboard - Displays payment prompts to users
• All premium tools - Can integrate with 402-payment for monetization

Further Reading¶

• x402 Payment Protocol Specification
• Monetizing Custom Tools
• Payment Methods & Wallets