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 /healthPrometheus Metrics
GET /metricsVersion Information
GET /versionx402 Protocol Discovery
GET /.well-known/x402Response:
{
"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');
});
Last updated