{
  "openapi": "3.1.0",
  "info": {
    "title": "Veriql Risk API",
    "version": "1.0.0",
    "description": "Read-only crypto risk API: wallet approval-risk, token security, and a transparent 0-100 launch-safety score. Same engine as the free Veriql scanner; every verdict returns its itemised drivers. Prepaid credits: 1 credit per successful call (get a free instant key at /api/checkout?pack=free); failed requests are free. Not financial advice.",
    "contact": { "name": "Veriql", "url": "https://veriql.pages.dev/api" }
  },
  "servers": [{ "url": "https://veriql.pages.dev/api/v1" }],
  "security": [{ "ApiKeyAuth": [] }],
  "paths": {
    "/scan": {
      "get": {
        "operationId": "scanWallet",
        "summary": "Wallet approval-risk scan (5 EVM chains)",
        "description": "Returns a 0-100 Security Score with itemised drivers, every risky approval, and a best-effort USD value-at-risk.",
        "parameters": [
          { "name": "address", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Public EVM address (0x…)." }
        ],
        "responses": {
          "200": { "description": "Enveloped scan result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "402": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" },
          "501": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/token": {
      "get": {
        "operationId": "checkToken",
        "summary": "Token / contract security check (EVM + Tron)",
        "description": "Honeypot, taxes, mintable supply, hidden owner, proxy and more: each surfaced as a plain-English flag.",
        "parameters": [
          { "name": "address", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Token contract address." },
          { "name": "chainId", "in": "query", "required": false, "schema": { "type": "string", "default": "1" }, "description": "Chain id or key (e.g. 1, base, tron). Defaults to Ethereum." }
        ],
        "responses": {
          "200": { "description": "Enveloped token report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "402": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" },
          "501": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/launch": {
      "get": {
        "operationId": "launchSafety",
        "summary": "Transparent 0-100 launch-safety score (EVM + Tron + Solana)",
        "description": "Returns the score, a band, full metrics, and every penalty as an itemised driver.",
        "parameters": [
          { "name": "address", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Token contract / mint address." },
          { "name": "chainId", "in": "query", "required": false, "schema": { "type": "string", "default": "1" }, "description": "Chain id or key (e.g. 1, base, solana). Defaults to Ethereum." }
        ],
        "responses": {
          "200": { "description": "Enveloped launch-safety report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "402": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" },
          "501": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/blocklist": {
      "get": {
        "operationId": "blocklistLookup",
        "summary": "Drain Watch: known drainer/scam address lookup (EVM + BTC + Solana + Tron)",
        "description": "Answered entirely from Veriql's own in-memory Drain Watch index (no upstream call). `listed:false` means no known listing found, not a guarantee of safety. A `listed:true` hit carries its category, a computed confidence, and every contributing source.",
        "parameters": [
          { "name": "address", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The address to look up, in the format native to `chain`." },
          { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "enum": ["evm", "btc", "solana", "tron"], "default": "evm" }, "description": "Chain namespace. Defaults to evm." }
        ],
        "responses": {
          "200": {
            "description": "Enveloped blocklist result",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    { "$ref": "#/components/schemas/Envelope" },
                    {
                      "type": "object",
                      "properties": {
                        "result": {
                          "type": "object",
                          "required": ["listed", "category", "confidence", "first_seen", "sources"],
                          "properties": {
                            "listed": { "type": "boolean" },
                            "category": { "type": ["string", "null"], "enum": ["drainer", "phishing", "scam-token", "sanctioned", "other", null] },
                            "confidence": { "type": ["string", "null"], "enum": ["confirmed", "reported", "heuristic", null] },
                            "first_seen": { "type": ["string", "null"], "format": "date-time" },
                            "sources": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "source": { "type": "string" },
                                  "url": { "type": ["string", "null"] },
                                  "license": { "type": ["string", "null"] }
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "402": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" }
    },
    "schemas": {
      "Envelope": {
        "type": "object",
        "required": ["version", "endpoint", "requestId", "result", "disclaimer"],
        "properties": {
          "version": { "type": "string", "example": "1" },
          "endpoint": { "type": "string", "enum": ["scan", "token", "launch"] },
          "requestId": { "type": "string", "example": "req_2b1e0c…" },
          "result": { "type": "object", "description": "The engine's full report (shape varies by endpoint)." },
          "disclaimer": { "type": "string" }
        }
      },
      "Error": {
        "type": "object",
        "required": ["version", "error"],
        "properties": {
          "version": { "type": "string", "example": "1" },
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": { "type": "string", "example": "unauthorized" },
              "message": { "type": "string" }
            }
          }
        }
      }
    },
    "responses": {
      "Error": { "description": "Error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    }
  }
}