> For the complete documentation index, see [llms.txt](https://voyage-1.gitbook.io/voyage-wiki/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://voyage-1.gitbook.io/voyage-wiki/v402-framework/api/other-components-apis.md). # Other components APIs ### ⚙️ Admin APIs *For system administrators and platform management* #### 👥 User Management **List Users** ``` GET /admin/users?page=1&size=50&role=content_provider&status=active&search=john@example.com Authorization: Bearer {admin_token} ``` **Get User Details** ``` GET /admin/users/{user_id} Authorization: Bearer {admin_token} ``` **Update User Status** ``` PATCH /admin/users/{user_id}/status?reason=Terms violation Authorization: Bearer {admin_token} { "new_status": "suspended" } ``` **Reset User Public Key** ``` POST /admin/users/{user_id}/reset-api-key Authorization: Bearer {admin_token} ``` #### 📊 System Analytics **System Overview** ``` GET /admin/analytics/overview?period=30d Authorization: Bearer {admin_token} ``` **Response:** ``` { "users": { "total": 1250, "active": 890, "new_this_period": 156, "growth_rate": 0.15 }, "content": { "total_products": 5670, "active_products": 4580, "new_this_period": 234 }, "payments": { "total_volume": "125000000000000000000000", "successful_payments": 15678, "failed_payments": 234, "success_rate": 0.985 }, "revenue": { "platform_revenue": "3125000000000000000000", "facilitator_fees": "781250000000000000000", "growth_rate": 0.22 }, "health": { "system_status": "healthy", "uptime": 0.9998, "avg_response_time": 145 } } ``` **Revenue Analytics** ``` GET /admin/analytics/revenue?start_date=2024-01-01&end_date=2024-01-31&group_by=week&chain=ethereum Authorization: Bearer {admin_token} ``` **User Analytics** ``` GET /admin/analytics/users?period=90d&segment=content_providers Authorization: Bearer {admin_token} ``` #### 🏥 System Monitoring **System Health** ``` GET /admin/health Authorization: Bearer {admin_token} ``` **Response:** ``` { "status": "healthy", "version": "1.0.0", "timestamp": "2024-01-15T10:45:00Z", "components": { "database": { "status": "healthy", "response_time": 15, "connections": { "active": 12, "max": 100 } }, "redis": { "status": "healthy", "memory_usage": 0.45, "hit_rate": 0.92 }, "blockchain": { "ethereum": { "status": "healthy", "block_height": 18750000, "sync_status": "synced" }, "base": { "status": "healthy", "block_height": 8920000, "sync_status": "synced" } } }, "uptime": 86400 } ``` **System Metrics** ``` GET /admin/metrics?metric_type=performance&time_range=1h Authorization: Bearer {admin_token} ``` **System Logs** ``` GET /admin/logs?level=ERROR&limit=100&start_time=2024-01-15T00:00:00Z&service=payment_processor Authorization: Bearer {admin_token} ``` #### 💳 Payment Management **List All Payments** ``` GET /admin/payments?page=1&size=100&status=failed&chain=ethereum&min_amount=1000000000000000000 Authorization: Bearer {admin_token} ``` **Process Refund** ``` POST /admin/payments/{payment_id}/refund Authorization: Bearer {admin_token} { "reason": "Content unavailable", "amount": "5000000000000000000", "notify_user": true } ``` #### 📝 Content Moderation **List All Content** ``` GET /admin/products?page=1&size=50&flagged_only=true&status=active Authorization: Bearer {admin_token} ``` **Moderate Content** ``` POST /admin/products/{product_id}/moderate?moderation_action=flag&reason=Inappropriate content Authorization: Bearer {admin_token} ``` *** ### 🔧 Core Service APIs #### 🏥 Health & Status **Service Health** ``` GET /health ``` **Prometheus Metrics** ``` GET /metrics ``` **Version Information** ``` GET /version ``` **x402 Protocol Discovery** ``` GET /.well-known/x402 ``` **Response:** ``` { "version": "1.0", "facilitator": { "name": "v402 Facilitator", "version": "1.0.0", "url": "/api/v1" }, "supported_chains": ["ethereum", "base", "polygon", "arbitrum", "optimism", "bsc", "solana"], "supported_schemes": ["exact", "upto", "dynamic"], "features": [ "payment_verification", "multi_chain_support", "batch_payments", "webhooks", "analytics" ], "endpoints": { "discovery": "/api/v1/clients/discover", "payment": "/api/v1/clients/payments", "access": "/api/v1/clients/access" } } ``` *** ### 🔒 Security & Rate Limiting #### Rate Limits | User Type | Endpoint Category | Rate Limit | | -------------------- | ----------------- | ----------- | | **Anonymous** | Discovery APIs | 20 req/min | | **Authenticated** | General APIs | 100 req/min | | **Content Provider** | Provider APIs | 200 req/min | | **Admin** | Admin APIs | 500 req/min | #### Security Headers All responses include security headers: ``` X-Content-Type-Options: nosniff X-Frame-Options: DENY X-XSS-Protection: 1; mode=block Strict-Transport-Security: max-age=31536000; includeSubDomains Content-Security-Policy: default-src 'self' ``` #### Error Handling Standard error response format: ``` { "error": "VALIDATION_ERROR", "message": "Invalid payment amount", "details": { "field": "amount", "code": "AMOUNT_TOO_LOW" }, "timestamp": "2024-01-15T10:45:00Z" } ``` ### 📝 Integration Examples #### Content Provider Integration ``` // 1. Create product const product = await fetch('/api/v1/providers/products', { method: 'POST', headers: { 'Authorization': 'Bearer your_public_key_here', 'Content-Type': 'application/json' }, body: JSON.stringify({ title: 'Premium Content', content_url: 'https://yoursite.com/premium/content-123', price: '5000000000000000000', // 5 ETH in wei type: 'article' }) }); // 2. Monitor analytics const analytics = await fetch('/api/v1/providers/analytics/dashboard?days=30', { headers: { 'Authorization': 'Bearer v402_your_api_key' } }); // 3. Check unpaid requests const unpaidRequests = await fetch('/api/v1/providers/unpaid-requests?hours=24', { headers: { 'Authorization': 'Bearer v402_your_api_key' } }); ``` #### Index Client Integration ``` import httpx class V402Client: def __init__(self, base_url, public_key=None): self.base_url = base_url self.headers = {'Authorization': f'Bearer {public_key}'} if public_key else {} async def discover_content(self, query, category=None, price_range=None): params = {'query': query} if category: params['category'] = category if price_range: params.update(price_range) async with httpx.AsyncClient() as client: response = await client.get( f'{self.base_url}/clients/discover', params=params, headers=self.headers ) return response.json() async def access_content(self, product_id, payment_header=None): headers = self.headers.copy() if payment_header: headers['X-PAYMENT'] = payment_header async with httpx.AsyncClient() as client: response = await client.get( f'{self.base_url}/clients/access/{product_id}', headers=headers ) return response # Usage client = V402Client('https://facilitator.v402.network/api/v1') content = await client.discover_content('AI tutorials', category='education') ``` #### Webhook Handler Example ``` const express = require('express'); const crypto = require('crypto'); const app = express(); // Webhook endpoint app.post('/webhooks/v402', express.raw({type: 'application/json'}), (req, res) => { const payload = req.body; const signature = req.headers['x-v402-signature']; const secret = 'your_webhook_secret'; // Verify webhook signature const expectedSignature = crypto .createHmac('sha256', secret) .update(payload) .digest('hex'); if (signature !== `sha256=${expectedSignature}`) { return res.status(401).send('Invalid signature'); } const event = JSON.parse(payload); // Handle different event types switch (event.type) { case 'payment.confirmed': console.log('Payment confirmed:', event.data); // Grant access to content break; case 'payment.failed': console.log('Payment failed:', event.data); // Handle failed payment break; case 'product.viewed': console.log('Product viewed:', event.data); // Track analytics break; } res.status(200).send('OK'); }); ``` ***