{
  "openapi": "3.0.3",
  "info": {
    "title": "Archalis Radar API",
    "version": "1.0",
    "description": "Rug pull and scam ratings for BNB Chain tokens. Ratings are automated assessments of structural risk based on public blockchain data, not investment advice. Documentation: https://docs.archalis.com"
  },
  "servers": [{ "url": "https://api.archalis.com" }],
  "components": {
    "securitySchemes": {
      "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" },
      "bearer": { "type": "http", "scheme": "bearer" }
    },
    "parameters": {
      "address": { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } }
      },
      "Token": {
        "type": "object",
        "properties": {
          "chain": { "type": "string", "example": "bsc" },
          "token": { "type": "string" },
          "symbol": { "type": "string", "nullable": true },
          "name": { "type": "string", "nullable": true },
          "rating": {
            "type": "object",
            "nullable": true,
            "properties": {
              "grade": { "type": "string", "enum": ["AAA", "AA", "A", "BBB", "BB", "B", "CCC", "CC", "C", "D", "SCAM"] },
              "label": { "type": "string" },
              "class": { "type": "string", "enum": ["investment", "speculative", "junk", "default", "scam"] },
              "provisional": { "type": "boolean" },
              "outlook": { "type": "string", "nullable": true },
              "score": { "type": "number", "nullable": true }
            }
          },
          "risk": { "type": "object", "properties": { "score": { "type": "number", "nullable": true }, "reasons": { "type": "array", "items": { "type": "string" } } } },
          "flags": { "type": "array", "items": { "type": "string" } },
          "market": { "type": "object", "nullable": true, "additionalProperties": true },
          "createdAt": { "type": "string", "format": "date-time", "nullable": true },
          "contract": { "type": "object", "additionalProperties": true },
          "liquidity": { "type": "object", "nullable": true, "additionalProperties": true },
          "distribution": { "type": "object", "additionalProperties": true },
          "creator": { "type": "object", "nullable": true, "additionalProperties": true },
          "launch": { "type": "object", "nullable": true, "additionalProperties": true },
          "collapse": {
            "type": "object",
            "nullable": true,
            "properties": {
              "kind": { "type": "string", "enum": ["liquidity_pulled", "insider_dump", "unverified", "market_crash", "coordinated_selling"] },
              "isRugPull": { "type": "boolean" },
              "liquidityDropPct": { "type": "number" },
              "minutesAfterLaunch": { "type": "number", "nullable": true },
              "pulledPct": { "type": "number", "nullable": true },
              "insiderSoldPct": { "type": "number", "nullable": true },
              "marketSoldPct": { "type": "number", "nullable": true }
            }
          },
          "analyzedAt": { "type": "string", "format": "date-time", "nullable": true },
          "source": { "type": "string", "enum": ["archive", "fresh", "stream"] }
        }
      }
    }
  },
  "security": [{}, { "apiKey": [] }, { "bearer": [] }],
  "paths": {
    "/v1/token/{address}": {
      "get": {
        "summary": "Rating of a token",
        "parameters": [
          { "$ref": "#/components/parameters/address" },
          { "name": "fresh", "in": "query", "schema": { "type": "boolean" }, "description": "Analyze now instead of reading the archive (counts as a fresh analysis)." }
        ],
        "responses": {
          "200": { "description": "Token rating", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Token" } } } },
          "400": { "description": "Invalid address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "description": "Rate limit or quota", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/v1/tokens": {
      "post": {
        "summary": "Ratings of up to 50 tokens (archive only)",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tokens": { "type": "array", "maxItems": 50, "items": { "type": "string" } } } } } } },
        "responses": { "200": { "description": "Results in the same order", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Token" } } } } } } } }
      }
    },
    "/v1/creator/{address}": {
      "get": {
        "summary": "Launch history, funding and network of a creator wallet",
        "parameters": [{ "$ref": "#/components/parameters/address" }],
        "responses": { "200": { "description": "Creator profile", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }
      }
    },
    "/v1/stream": {
      "get": {
        "summary": "Real-time events (Server-Sent Events): new, rating, rug, crash",
        "parameters": [{ "name": "key", "in": "query", "schema": { "type": "string" }, "description": "API key, for clients that cannot set headers." }],
        "responses": { "200": { "description": "text/event-stream; each event's data is {type, at, token}" } }
      }
    },
    "/v1/usage": {
      "get": { "summary": "Plan, limits and today's usage", "responses": { "200": { "description": "Usage" } } }
    },
    "/v1/stats/default-rates": {
      "get": { "summary": "Default rate by initial grade (public, no quota)", "security": [{}], "responses": { "200": { "description": "Default rates" } } }
    }
  }
}