{
  "openapi": "3.0.3",
  "info": {
    "title": "Raven Hosted Verifier",
    "description": "Signed, fail-closed Solana token-launch verification. Server-side RPC; callers never supply infrastructure. Verdicts: pass | pass_with_info_finding | warning | risk | unknowable. Every response lists coverageGaps. Not financial advice.",
    "version": "v2",
    "contact": { "url": "https://raven-launch-console.vercel.app/request-access.html" }
  },
  "servers": [{ "url": "https://raven-hosted-verifier.onrender.com" }],
  "paths": {
    "/verify": {
      "post": {
        "summary": "Verify a Solana token launch and return a signed deliverable",
        "security": [{ "ApiKey": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["mintAddress", "tokenProgramAddress"],
                "properties": {
                  "mintAddress": { "type": "string", "description": "Token mint address (base58)." },
                  "tokenProgramAddress": { "type": "string", "description": "Owning token program: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA (SPL) or TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb (Token-2022)." },
                  "metadataAddress": { "type": "string", "description": "Optional Metaplex metadata account." },
                  "poolAddress": { "type": "string", "description": "Optional Raydium CPMM pool for liquidity/vault evidence." },
                  "commitment": { "type": "string", "enum": ["finalized", "confirmed"], "default": "finalized" }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Signed deliverable",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "verdict": { "type": "string", "enum": ["pass", "pass_with_info_finding", "warning", "risk", "unknowable"] },
                    "engineOutcome": { "type": "string", "nullable": true },
                    "reason": { "type": "string" },
                    "findingCodes": { "type": "array", "items": { "type": "string" } },
                    "findings": { "type": "array", "items": { "type": "object" } },
                    "coverageGaps": { "type": "array", "items": { "type": "string" }, "description": "Surfaces NOT evaluated for this verdict. Always present, always honest." },
                    "engineVersion": { "type": "string" },
                    "replayHash": { "type": "string", "description": "sha256 over the canonical replay input." },
                    "officialAttestationHash": { "type": "string" },
                    "keyId": { "type": "string", "example": "rvk_c2997e90215279c2" },
                    "signature": { "type": "string", "description": "ed25519 over domain-separated preimage; verify against GET /pubkey." },
                    "signatureAlg": { "type": "string", "example": "ed25519" },
                    "issuedAt": { "type": "string", "format": "date-time" },
                    "rpc": { "type": "object", "description": "Observed slot + request echo for replay." }
                  }
                }
              }
            }
          },
          "400": { "description": "invalid_request (bad addresses, forbidden fields rpcUrl/issuerIdentity)" },
          "401": { "description": "unauthorized (missing/unknown API key)" },
          "429": { "description": "rate limited (alpha: 10/min per key, burst 4)" },
          "502": { "description": "engine_error" },
          "503": { "description": "signer_unavailable (fail-closed: an official verifier that cannot sign does not serve)" }
        }
      }
    },
    "/pubkey": {
      "get": {
        "summary": "Published attestation key(s)",
        "responses": { "200": { "description": "keys[] with keyId, publicKeyBase64 (ed25519 SPKI), domain raven-official-attestation, version v2" } }
      }
    },
    "/healthz": {
      "get": {
        "summary": "Liveness + signer presence",
        "responses": { "200": { "description": "{\"status\":\"ok\",\"signer\":true}" } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Invite-gated alpha. Request at https://raven-launch-console.vercel.app/request-access.html. Bearer auth also accepted." }
    }
  }
}