{
  "openapi": "3.1.0",
  "info": {
    "title": "Krypto-Chartanalyse API",
    "version": "1.0.0",
    "description": "Öffentliche, lesende JSON-API für technische Chartanalyse von SOL/EUR, BTC/EUR und ETH/EUR auf Basis öffentlicher Kraken-Marktdaten. Alle Kurse in EUR, alle Zeitstempel in UTC nach ISO 8601. Keine Handelsfunktionen, keine Anlageberatung."
  },
  "servers": [
    {
      "url": "https://DEINE-DOMAIN.TLD",
      "description": "Produktivinstanz. URL nach dem Deployment hier eintragen."
    }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Dienststatus und Datenalter",
        "description": "Liefert den Zustand des Dienstes, den Zeitpunkt der letzten erfolgreichen Kraken-Abfrage und das Datenalter je Markt und Zeitrahmen.",
        "responses": {
          "200": { "description": "Dienst in Ordnung", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } },
          "503": { "description": "Mindestens ein Markt liefert keine frischen Daten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }
        }
      }
    },
    "/api/market": {
      "get": {
        "operationId": "getMarketOverview",
        "summary": "Übersicht aller Handelspaare und Zeitrahmen",
        "description": "Aktueller Kurs, EMA 9/26/200, letzte abgeschlossene Kerze und laufende Kerze für SOL/EUR, BTC/EUR und ETH/EUR in 5m und 1h.",
        "responses": {
          "200": { "description": "Marktübersicht", "content": { "application/json": { "schema": { "type": "object" } } } },
          "502": { "$ref": "#/components/responses/Upstream" }
        }
      }
    },
    "/api/market/candles": {
      "get": {
        "operationId": "getCandles",
        "summary": "Historische Kerzen mit EMA-Werten",
        "parameters": [
          { "$ref": "#/components/parameters/Symbol" },
          { "$ref": "#/components/parameters/Timeframe" },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Anzahl der zurückgelieferten abgeschlossenen Kerzen. Die EMA-Werte werden immer über die volle verfügbare Historie berechnet und erst danach zugeschnitten.",
            "schema": { "type": "integer", "minimum": 1, "maximum": 720, "default": 250 }
          }
        ],
        "responses": {
          "200": { "description": "Kerzen und Indikatoren", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CandlesResponse" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "502": { "$ref": "#/components/responses/Upstream" }
        }
      }
    },
    "/api/analysis": {
      "get": {
        "operationId": "getAnalysis",
        "summary": "Technische Analyse für 5m und 1h",
        "description": "Trend, EMA-Reihenfolge und Steigung, Unterstützungen und Widerstände in EUR, Volatilität, Long- und Short-Szenarien mit erforderlichen Bestätigungen und Invalidierungsbedingungen. BTC/EUR dient als übergeordneter Richtungsfilter für ETH/EUR und SOL/EUR, ETH/EUR zusätzlich als Bestätigung für SOL/EUR.",
        "parameters": [ { "$ref": "#/components/parameters/Symbol" } ],
        "responses": {
          "200": { "description": "Analyse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalysisResponse" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "502": { "$ref": "#/components/responses/Upstream" }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "Symbol": {
        "name": "symbol",
        "in": "query",
        "required": true,
        "description": "Handelspaar.",
        "schema": { "type": "string", "enum": ["SOL/EUR", "BTC/EUR", "ETH/EUR"] }
      },
      "Timeframe": {
        "name": "timeframe",
        "in": "query",
        "required": false,
        "description": "Zeitrahmen der Kerzen.",
        "schema": { "type": "string", "enum": ["5m", "1h"], "default": "5m" }
      }
    },
    "responses": {
      "BadRequest": { "description": "Ungültige Parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "RateLimited": { "description": "Zu viele Anfragen", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Upstream": { "description": "Kraken nicht erreichbar", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean", "const": false },
          "error": { "type": "string" },
          "generated_at_utc": { "type": "string", "format": "date-time" }
        },
        "required": ["ok", "error"]
      },
      "Meta": {
        "type": "object",
        "description": "Metadaten, die jede Antwort begleiten.",
        "properties": {
          "data_source": { "type": "string" },
          "symbol": { "type": "string" },
          "quote_currency": { "type": "string", "const": "EUR" },
          "timeframe": { "type": "string" },
          "fetched_at_utc": { "type": "string", "format": "date-time" },
          "generated_at_utc": { "type": "string", "format": "date-time" },
          "last_closed_candle_utc": { "type": ["string", "null"], "format": "date-time" },
          "data_age_seconds": { "type": ["integer", "null"] },
          "data_quality": { "type": "string", "enum": ["ok", "delayed", "stale", "insufficient_history", "no_data"] },
          "warnings": { "type": "array", "items": { "type": "string" } }
        }
      },
      "Candle": {
        "type": "object",
        "properties": {
          "time": { "type": "string", "format": "date-time" },
          "timestamp": { "type": "integer" },
          "open": { "type": "number" },
          "high": { "type": "number" },
          "low": { "type": "number" },
          "close": { "type": "number" },
          "volume": { "type": "number" },
          "trades": { "type": "integer" },
          "ema9": { "type": ["number", "null"] },
          "ema26": { "type": ["number", "null"] },
          "ema200": { "type": ["number", "null"] },
          "complete": { "type": "boolean", "description": "false kennzeichnet die laufende, noch nicht abgeschlossene Kerze." }
        }
      },
      "CandlesResponse": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "meta": { "$ref": "#/components/schemas/Meta" },
          "requested_limit": { "type": "integer" },
          "returned": { "type": "integer" },
          "candles": { "type": "array", "items": { "$ref": "#/components/schemas/Candle" } },
          "forming_candle": { "oneOf": [ { "$ref": "#/components/schemas/Candle" }, { "type": "null" } ] }
        }
      },
      "Level": {
        "type": "object",
        "properties": {
          "price": { "type": "number" },
          "zone_low": { "type": "number" },
          "zone_high": { "type": "number" },
          "touches": { "type": "integer" },
          "last_touch": { "type": "string", "format": "date-time" },
          "bars_ago": { "type": "integer" }
        }
      },
      "TimeframeAnalysis": {
        "type": "object",
        "properties": {
          "timeframe": { "type": "string" },
          "price_last_closed": { "type": "number" },
          "price_live": { "type": "number" },
          "last_closed_candle": { "$ref": "#/components/schemas/Candle" },
          "forming_candle": { "oneOf": [ { "$ref": "#/components/schemas/Candle" }, { "type": "null" } ] },
          "ema": { "type": "object" },
          "trend": {
            "type": "object",
            "properties": {
              "short_term": { "type": "string", "enum": ["aufwaerts", "abwaerts", "seitwaerts"] },
              "higher_level": { "type": "string", "enum": ["aufwaerts", "abwaerts", "seitwaerts"] }
            }
          },
          "volatility": { "type": "object" },
          "levels": {
            "type": "object",
            "properties": {
              "support": { "type": "array", "items": { "$ref": "#/components/schemas/Level" } },
              "resistance": { "type": "array", "items": { "$ref": "#/components/schemas/Level" } },
              "range_high": { "type": ["number", "null"] },
              "range_low": { "type": ["number", "null"] }
            }
          },
          "break": { "type": "object" },
          "extension": { "type": ["object", "null"] },
          "scenarios": {
            "type": "object",
            "properties": {
              "setup_state": {
                "type": "string",
                "enum": ["bestaetigtes_setup", "moegliches_setup_ohne_bestaetigung", "neutral", "ungueltiges_setup", "veraltete_oder_unvollstaendige_daten"]
              },
              "reason": { "type": "string" },
              "recommendation": { "type": "string" },
              "long": { "type": "object" },
              "short": { "type": "object" },
              "notes": { "type": "array", "items": { "type": "string" } }
            }
          },
          "meta": { "$ref": "#/components/schemas/Meta" }
        }
      },
      "AnalysisResponse": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "symbol": { "type": "string" },
          "quote_currency": { "type": "string", "const": "EUR" },
          "data_source": { "type": "string" },
          "generated_at_utc": { "type": "string", "format": "date-time" },
          "higher_level_filters": { "type": "object" },
          "timeframes": {
            "type": "object",
            "properties": {
              "5m": { "$ref": "#/components/schemas/TimeframeAnalysis" },
              "1h": { "$ref": "#/components/schemas/TimeframeAnalysis" }
            }
          },
          "disclaimer": { "type": "string" }
        }
      },
      "Health": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "service": { "type": "string" },
          "version": { "type": "string" },
          "generated_at_utc": { "type": "string", "format": "date-time" },
          "max_data_age_seconds": { "type": ["integer", "null"] },
          "markets": { "type": "object" }
        }
      }
    }
  }
}