{
  "openapi": "3.1.0",
  "info": {
    "title": "TriviaQ API",
    "description": "Blockchain quiz game API on Celo & Base. Generate AI trivia questions, get live on-chain stats, leaderboard and duel info. Premium endpoints enforce x402 micropayments.",
    "version": "3.4.0",
    "contact": {
      "name": "wkalidev",
      "url": "https://github.com/wkalidev",
      "email": "wkalidev@gmail.com"
    },
    "license": {
      "name": "MIT",
      "url": "https://github.com/wkalidev/trivia-quest/blob/main/LICENSE"
    }
  },
  "servers": [
    {
      "url": "https://trivia-quest-eight.vercel.app",
      "description": "Production"
    }
  ],
  "components": {
    "securitySchemes": {
      "x402Payment": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Payment",
        "description": "x402 micropayment protocol (https://x402.org). Call the endpoint without this header to receive HTTP 402 with payment requirements, then provide the signed EIP-3009 payment authorization here. Network: Celo Mainnet. Asset: USDC (0xcebA9300f2b948710d2653dD7B07f33A8B32118C). Verified and settled server-side via the Celo x402 facilitator (x402.celo.org)."
      }
    }
  },
  "paths": {
    "/api/ai-question": {
      "get": {
        "operationId": "generateAIQuestion",
        "summary": "Generate AI trivia question",
        "description": "Generates a trivia question using Groq LLaMA 3.1-8b-instant. Returns question text, 4 answer options, correct answer index and category. **Premium endpoint** — external agent access requires x402 payment ($0.001 USDC per call). Rate limited: 10 req/min.",
        "security": [
          { "x402Payment": [] }
        ],
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "African Geography",
                "Web3 & Crypto",
                "History & Culture",
                "Science & Tech",
                "Sports",
                "General Knowledge"
              ]
            },
            "description": "Question category. Random if omitted."
          },
          {
            "name": "health",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "enum": ["1"] },
            "description": "Set to 1 for health check (no payment required)."
          }
        ],
        "responses": {
          "200": {
            "description": "Trivia question generated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "question": { "type": "string" },
                    "options": {
                      "type": "array",
                      "items": { "type": "string" },
                      "minItems": 4,
                      "maxItems": 4
                    },
                    "answer": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 3,
                      "description": "Index of the correct answer in options array"
                    },
                    "category": { "type": "string" },
                    "isAI": { "type": "boolean" }
                  },
                  "required": ["question", "options", "answer", "category"]
                }
              }
            }
          },
          "402": {
            "description": "Payment required — x402 payment details returned",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "x402Version": { "type": "integer" },
                    "accepts": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "scheme": { "type": "string" },
                          "network": { "type": "string" },
                          "maxAmountRequired": { "type": "string" },
                          "resource": { "type": "string" },
                          "payTo": { "type": "string" },
                          "asset": { "type": "string" }
                        }
                      }
                    },
                    "error": { "type": "string" }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded"
          },
          "503": {
            "description": "AI service unavailable"
          }
        }
      }
    },
    "/api/stats": {
      "get": {
        "operationId": "getStats",
        "summary": "Get TriviaQ live on-chain stats",
        "description": "Returns live on-chain statistics: total players, current round, prize pool (wei), total check-ins. Data from Celo and Base mainnets. Free access, no payment required.",
        "responses": {
          "200": {
            "description": "Live stats",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "project": { "type": "string" },
                    "version": { "type": "string" },
                    "live_stats": {
                      "type": "object",
                      "properties": {
                        "players": { "type": "integer" },
                        "round_id": { "type": "integer" },
                        "prize_pool_wei": { "type": "string" },
                        "total_checkins": { "type": "integer" },
                        "last_updated": { "type": "string", "format": "date-time" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/mcp": {
      "post": {
        "operationId": "mcpCall",
        "summary": "MCP Server — Model Context Protocol endpoint",
        "description": "JSON-RPC 2.0 MCP server. Methods: initialize, tools/list, tools/call (generate_question, get_stats, get_leaderboard, get_duel_info), ping.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "jsonrpc": { "type": "string", "enum": ["2.0"] },
                  "method": { "type": "string" },
                  "params": { "type": "object" },
                  "id": {}
                },
                "required": ["jsonrpc", "method"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response"
          }
        }
      },
      "get": {
        "operationId": "mcpHealth",
        "summary": "MCP Server health check",
        "responses": {
          "200": {
            "description": "MCP server info and status"
          }
        }
      }
    },
    "/api/a2a": {
      "post": {
        "operationId": "a2aTask",
        "summary": "A2A Agent endpoint — Agent-to-Agent protocol",
        "description": "Google A2A protocol endpoint. Send tasks to TriviaQ AI Agent. Supports: tasks/send, tasks/get.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "jsonrpc": { "type": "string" },
                  "method": { "type": "string" },
                  "params": { "type": "object" },
                  "id": {}
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A2A task result"
          }
        }
      },
      "get": {
        "operationId": "a2aHealth",
        "summary": "A2A Agent health check",
        "responses": {
          "200": {
            "description": "A2A agent info"
          }
        }
      }
    }
  }
}