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=[e-mail]
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');
});

---