{
  "openapi": "3.1.0",
  "info": {
    "title": "DailyDrop Shield API",
    "version": "1.2.0",
    "description": "Proof of Presence API — verify real humans by on-chain daily streak on Celo and Base. Free public endpoints for single verification; batch verification requires x402 payment (0.01 USDC on Base).",
    "contact": {
      "name": "DailyDrop",
      "url": "https://dailydrop-five.vercel.app",
      "email": "wkalidev@gmail.com"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    },
    "termsOfService": "https://dailydrop-five.vercel.app/terms",
    "x-logo": { "url": "https://dailydrop-five.vercel.app/icon-512.png" }
  },
  "servers": [
    { "url": "https://dailydrop-five.vercel.app", "description": "Production" }
  ],
  "security": [],
  "components": {
    "securitySchemes": {
      "x402": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Payment",
        "description": "HTTP 402 payment protocol. The endpoint returns 402 with an X-Payment-Required header containing USDC payment details (network: base, asset: USDC, amount: 0.01). Include a signed X-Payment proof on retry."
      }
    },
    "schemas": {
      "StreakResult": {
        "type": "object",
        "properties": {
          "address": { "type": "string", "example": "0xABC..." },
          "passed": { "type": "boolean" },
          "minStreak": { "type": "integer" },
          "streak": {
            "type": "object",
            "properties": {
              "current": { "type": "integer" },
              "bestChain": { "type": "string", "enum": ["celo", "base"] },
              "celo": { "type": "integer" },
              "base": { "type": "integer" }
            }
          },
          "badges": {
            "type": "object",
            "properties": {
              "level": { "type": "integer", "minimum": 0, "maximum": 3 },
              "label": { "type": "string" },
              "weekly": { "type": "boolean" },
              "monthly": { "type": "boolean" },
              "century": { "type": "boolean" }
            }
          },
          "shield": { "type": "string" },
          "meta": { "type": "object" }
        }
      }
    }
  },
  "paths": {
    "/api/verify": {
      "get": {
        "operationId": "verifyStreak",
        "summary": "Verify wallet streak (Proof of Presence)",
        "description": "Returns pass/fail for a minimum streak threshold, current streaks on Celo and Base, and badge tier. Free, public, no auth required.",
        "tags": ["verification"],
        "parameters": [
          {
            "name": "address",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" },
            "description": "EVM wallet address (0x...)"
          },
          {
            "name": "minStreak",
            "in": "query",
            "schema": { "type": "integer", "default": 7, "minimum": 1, "maximum": 365 },
            "description": "Minimum consecutive-day streak required to pass"
          }
        ],
        "responses": {
          "200": {
            "description": "Verification result",
            "headers": {
              "Cache-Control": { "schema": { "type": "string" }, "description": "public, max-age=60, stale-while-revalidate=300" },
              "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "description": "*" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/StreakResult" }
              }
            }
          },
          "400": { "description": "Invalid address or minStreak" },
          "500": { "description": "On-chain read failed" }
        }
      }
    },
    "/api/stats": {
      "get": {
        "operationId": "getStats",
        "summary": "Protocol-wide check-in statistics",
        "description": "Returns total check-ins and unique wallet counts across Celo and Base. Sourced from Celoscan + Basescan. Cached 5 minutes.",
        "tags": ["stats"],
        "responses": {
          "200": {
            "description": "Global stats",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "totalCheckIns": { "type": "integer" },
                    "uniqueWallets": { "type": "integer" },
                    "celoWallets": { "type": "integer" },
                    "baseWallets": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/leaderboard": {
      "get": {
        "operationId": "getLeaderboard",
        "summary": "Top streak holders on Celo and Base",
        "description": "Returns the most active wallets sorted by total check-ins. Includes per-chain breakdown.",
        "tags": ["stats"],
        "responses": {
          "200": { "description": "Leaderboard data" }
        }
      }
    },
    "/api/agent": {
      "get": {
        "operationId": "getStreakCoach",
        "summary": "AI streak coach",
        "description": "Returns personalized motivation and action tips for a wallet based on its on-chain streak. Powered by Claude Haiku when ANTHROPIC_API_KEY is set; falls back to deterministic heuristics.",
        "tags": ["agent"],
        "parameters": [
          {
            "name": "address",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" },
            "description": "EVM wallet address"
          }
        ],
        "responses": {
          "200": {
            "description": "Streak coaching response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "streak": { "type": "integer" },
                    "totalCheckIns": { "type": "integer" },
                    "canCheckIn": { "type": "boolean" },
                    "canClaim": { "type": "boolean" },
                    "riskLevel": { "type": "string", "enum": ["low", "medium", "high"] },
                    "message": { "type": "string" },
                    "tip": { "type": "string" },
                    "aiPowered": { "type": "boolean" }
                  }
                }
              }
            }
          },
          "400": { "description": "Invalid address" }
        }
      }
    },
    "/api/mcp": {
      "get": {
        "operationId": "mcpDiscover",
        "summary": "MCP server discovery",
        "description": "Returns server info and available tool list for MCP clients.",
        "tags": ["mcp"],
        "responses": {
          "200": { "description": "MCP server metadata and tool list" }
        }
      },
      "post": {
        "operationId": "mcpCall",
        "summary": "MCP tool invocation (JSON-RPC 2.0)",
        "description": "Invoke MCP tools: verify_streak, get_profile, get_stats are free. verify_batch requires x402 payment (0.01 USDC on Base).",
        "tags": ["mcp"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["method"],
                "properties": {
                  "method": {
                    "type": "string",
                    "enum": ["tools/list", "tools/call", "initialize", "ping"]
                  },
                  "id": {},
                  "params": {
                    "type": "object",
                    "properties": {
                      "name": { "type": "string", "enum": ["verify_streak", "get_profile", "verify_batch", "get_stats"] },
                      "arguments": { "type": "object" }
                    }
                  }
                }
              },
              "examples": {
                "verify_streak": {
                  "value": {
                    "method": "tools/call",
                    "id": 1,
                    "params": { "name": "verify_streak", "arguments": { "address": "0xABC...", "minStreak": 7 } }
                  }
                },
                "verify_batch": {
                  "value": {
                    "method": "tools/call",
                    "id": 2,
                    "params": { "name": "verify_batch", "arguments": { "addresses": ["0xABC...", "0xDEF..."], "minStreak": 7 } }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC 2.0 result"
          },
          "402": {
            "description": "Payment required — verify_batch tool requires 0.01 USDC on Base",
            "headers": {
              "X-Payment-Required": {
                "schema": { "type": "string" },
                "description": "JSON object with x402 payment details (scheme, network, asset, amount, payTo)"
              }
            }
          },
          "429": { "description": "Rate limit exceeded (10 req/min per IP)" }
        },
        "security": [{ "x402": [] }]
      }
    }
  },
  "tags": [
    { "name": "verification", "description": "Proof of Presence verification endpoints" },
    { "name": "stats", "description": "Protocol analytics" },
    { "name": "agent", "description": "AI streak coaching" },
    { "name": "mcp", "description": "Model Context Protocol server" }
  ],
  "x-agent-card": "https://dailydrop-five.vercel.app/.well-known/agent-card.json",
  "x-oasf": {
    "version": "1.0",
    "skills": ["tool_interaction", "analytical_skills"],
    "domains": ["technology/blockchain", "trust_and_safety/fraud_prevention"]
  }
}