Index Client APIs

For AI platforms, search engines, and content consumers

Content Discovery

Discover Content

GET /clients/discover?query=artificial intelligence&category=education&min_price=1000000000000000000&max_price=10000000000000000000&chain=ethereum&sort_by=relevance&page=1&size=20

Response:

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Premium AI Tutorial Series",
      "description": "Comprehensive guide to modern AI development",
      "type": "course",
      "category": "education",
      "price": "5000000000000000000",
      "currency": "ETH",
      "payment_scheme": "exact",
      "thumbnail_url": "https://example.com/thumbnails/ai-course.jpg",
      "rating": 4.85,
      "purchase_count": 89,
      "provider": {
        "id": "provider-123",
        "name": "AI Education Hub",
        "verified": true
      },
      "access_info": {
        "duration": 86400,
        "max_accesses": null,
        "content_type": "video/series"
      }
    }
  ],
  "total": 156,
  "page": 1,
  "size": 20,
  "filters_applied": {
    "query": "artificial intelligence",
    "category": "education",
    "price_range": ["1000000000000000000", "10000000000000000000"]
  },
  "suggestions": ["machine learning", "deep learning", "neural networks"]
}

Get Content Information

GET /clients/content/{product_id}

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Premium AI Tutorial Series",
  "description": "Comprehensive guide covering neural networks, deep learning...",
  "type": "course", 
  "category": "education",
  "price": "5000000000000000000",
  "currency": "ETH",
  "payment_scheme": "exact",
  "preview_content": "Module 1: Introduction to AI - What is artificial intelligence...",
  "payment_options": [
    {
      "chain": "ethereum",
      "address": "0x742d35cc6cf25a8a8c498d0b3045fc22b2b8f7f9",
      "estimated_fee": "50000000000000000"
    },
    {
      "chain": "base", 
      "address": "0x742d35cc6cf25a8a8c498d0b3045fc22b2b8f7f9",
      "estimated_fee": "1000000000000000"
    }
  ],
  "provider": {
    "name": "AI Education Hub",
    "website": "https://aieducationhub.com",
    "verified": true,
    "rating": 4.9
  },
  "statistics": {
    "view_count": 1250,
    "purchase_count": 89,
    "rating": 4.85,
    "review_count": 67
  }
}

Browse Categories

GET /clients/categories?include_count=true

Trending Content

GET /clients/trending?period=24h&limit=10&category=ai

Content Access (x402 Protocol)

Request Content Access

GET /clients/access/{product_id}
User-Agent: AI-Platform/1.0
Referer: https://ai-platform.com/search

Response (Payment Required - 402):

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "ethereum",
      "maxAmountRequired": "5000000000000000000",
      "resource": "/clients/access/550e8400-e29b-41d4-a716-446655440000",
      "description": "Premium AI Tutorial Series",
      "mimeType": "video/series",
      "payTo": "0x742d35cc6cf25a8a8c498d0b3045fc22b2b8f7f9",
      "maxTimeoutSeconds": 900,
      "asset": "ETH"
    }
  ],
  "error": "Payment required to access this content"
}

Access with Payment

GET /clients/access/{product_id}
X-PAYMENT: v402.1.0:0xsignature:payload:metadata
User-Agent: AI-Platform/1.0

Response (Access Granted - 200):

{
  "status": "success",
  "content_url": "https://secure-content.example.com/ai-tutorial-series?token=abc123",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-01-16T10:45:00Z",
  "payment_info": {
    "amount": "5000000000000000000",
    "transaction_hash": "0xdef456...",
    "network": "ethereum",
    "confirmations": 3
  }
}

Payment Processing

Create Payment

POST /clients/payments
Content-Type: application/json

{
  "product_id": "550e8400-e29b-41d4-a716-446655440000",
  "payer_address": "0x123...",
  "payee_address": "0x742d35cc6cf25a8a8c498d0b3045fc22b2b8f7f9",
  "amount": "5000000000000000000",
  "chain": "ethereum",
  "currency": "ETH",
  "payment_scheme": "exact",
  "external_reference": "ai-platform-order-123"
}

Response:

{
  "id": "pay-456",
  "transaction_hash": null,
  "chain": "ethereum",
  "payer_address": "0x123...",
  "payee_address": "0x742d35cc6cf25a8a8c498d0b3045fc22b2b8f7f9",
  "product_id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "5000000000000000000",
  "facilitator_fee": "125000000000000000",
  "status": "pending",
  "created_at": "2024-01-15T10:45:00Z",
  "expires_at": "2024-01-15T11:00:00Z"
}

Check Payment Status

GET /clients/payments/{payment_id}

Confirm Payment

POST /clients/payments/{payment_id}/confirm
Content-Type: application/json

{
  "transaction_hash": "0xdef456...",
  "block_number": 18750000,
  "gas_used": 21000,
  "gas_price": "20000000000"
}

Report Payment Failure

POST /clients/payments/{payment_id}/fail
Content-Type: application/json

{
  "reason": "Insufficient funds",
  "error_code": "INSUFFICIENT_PAYMENT_TOKENS"
}

User Management

User Profile

GET /clients/profile
Authorization: Bearer {jwt_token}

Payment History

GET /clients/payment-history?page=1&size=20&status=confirmed
Authorization: Bearer {jwt_token}

Blockchain Information

Supported Chains

GET /clients/chains

Response:

[
  {
    "name": "ethereum",
    "display_name": "Ethereum",
    "chain_id": 1,
    "currency": "ETH", 
    "status": "active",
    "average_fee": "50000000000000000",
    "confirmation_time": "3-5 minutes"
  },
  {
    "name": "base",
    "display_name": "Base",
    "chain_id": 8453,
    "currency": "ETH",
    "status": "active", 
    "average_fee": "1000000000000000",
    "confirmation_time": "10-30 seconds"
  }
]