# 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');
});
```

***

<br>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://voyage-1.gitbook.io/voyage-wiki/v402-framework/api/other-components-apis.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.