{
  "openapi": "3.1.0",
  "info": {
    "title": "KepAIx Educational Intelligence API",
    "version": "1.0.0",
    "description": "KepAIx provides live educational intelligence APIs for developers, dashboards, applications, and AI agents. Endpoints include Main Brain market context, human consensus, Teacher Brain lessons, reasoning, statistics, shared Arena intelligence, and an x402 paid endpoint. All responses are educational only and are not financial, investment, trading, tax, or legal advice.",
    "termsOfService": "https://kepaix.com/terms.php",
    "contact": {
      "name": "KepAIx",
      "url": "https://kepaix.com/developers_arena.php"
    },
    "license": {
      "name": "Educational API Access",
      "url": "https://kepaix.com/api-docs.php"
    }
  },
  "servers": [
    {
      "url": "https://kepaix.com",
      "description": "KepAIx production"
    }
  ],
  "tags": [
    {"name": "Main Brain", "description": "Current KepAIx educational AI intelligence and market context."},
    {"name": "Arena", "description": "Human consensus and human-vs-AI shared intelligence."},
    {"name": "Teacher Brain", "description": "Completed lessons and educational memory from Arena rounds."},
    {"name": "x402", "description": "Machine-payable educational intelligence using x402."},
    {"name": "Network", "description": "Public network statistics and API ecosystem metadata."}
  ],
  "paths": {
    "/api/market-regime.php": {
      "get": {
        "tags": ["Main Brain"],
        "summary": "Free Market Regime API",
        "description": "Returns free public educational market-regime context from KepAIx.",
        "operationId": "getMarketRegime",
        "responses": {
          "200": {
            "description": "Educational market-regime response.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/MarketRegimeResponse"}
              }
            }
          }
        }
      }
    },
    "/api/main-brain.php": {
      "get": {
        "tags": ["Main Brain"],
        "summary": "Main Brain Snapshot API",
        "description": "Returns the current public KepAIx Main Brain snapshot across tracked educational assets.",
        "operationId": "getMainBrainSnapshot",
        "responses": {
          "200": {
            "description": "Current Main Brain snapshot.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/MainBrainResponse"}
              }
            }
          }
        }
      }
    },
    "/api/human-consensus.php": {
      "get": {
        "tags": ["Arena"],
        "summary": "Human Consensus API",
        "description": "Returns the current live Arena human consensus layer for the active round.",
        "operationId": "getHumanConsensus",
        "responses": {
          "200": {
            "description": "Current human consensus for the live Arena round.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/HumanConsensusResponse"}
              }
            }
          }
        }
      }
    },
    "/api/teacher-lessons.php": {
      "get": {
        "tags": ["Teacher Brain"],
        "summary": "Teacher Lessons API",
        "description": "Returns completed Arena learning lessons and Teacher Brain metrics.",
        "operationId": "getTeacherLessons",
        "responses": {
          "200": {
            "description": "Teacher Brain lesson metrics and latest completed lessons.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/TeacherLessonsResponse"}
              }
            }
          }
        }
      }
    },
    "/api/reasoning.php": {
      "get": {
        "tags": ["Main Brain"],
        "summary": "Brain Reasoning API",
        "description": "Returns lightweight structured reasoning for a supported asset.",
        "operationId": "getReasoning",
        "parameters": [
          {
            "name": "asset",
            "in": "query",
            "required": false,
            "description": "Supported asset symbol. Defaults to BTC.",
            "schema": {
              "type": "string",
              "enum": ["BTC", "ETH", "XRP", "SOL", "ALGO", "XLM", "HBAR"],
              "default": "BTC"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Structured reasoning for the selected asset.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/ReasoningResponse"}
              }
            }
          }
        }
      }
    },
    "/api/statistics.php": {
      "get": {
        "tags": ["Network"],
        "summary": "Network Statistics API",
        "description": "Returns public statistics about the KepAIx intelligence network, Main Brain, Arena, Teacher Brain, and API ecosystem.",
        "operationId": "getNetworkStatistics",
        "responses": {
          "200": {
            "description": "KepAIx network statistics.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/StatisticsResponse"}
              }
            }
          }
        }
      }
    },
    "/arena/get_shared_intelligence.php": {
      "get": {
        "tags": ["Arena"],
        "summary": "Shared Intelligence API",
        "description": "Returns the full live Arena shared intelligence payload combining round state, human consensus, Main Brain, Teacher Brain, price context, and educational notices.",
        "operationId": "getSharedIntelligence",
        "responses": {
          "200": {
            "description": "Full live Arena shared intelligence payload.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/SharedIntelligenceResponse"}
              }
            }
          }
        }
      }
    },
    "/api/x402-market-regime.php": {
      "get": {
        "tags": ["x402"],
        "summary": "x402 Market Intelligence API",
        "description": "Paid educational market-regime intelligence endpoint. Without a valid x402 payment, returns HTTP 402 Payment Required with payment instructions. After valid payment, returns paid educational intelligence JSON.",
        "operationId": "getX402MarketRegime",
        "responses": {
          "200": {
            "description": "Paid educational market-regime intelligence after valid x402 payment.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/X402PaidResponse"}
              }
            }
          },
          "402": {
            "description": "Payment required response containing x402 payment details.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/X402PaymentRequiredResponse"}
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "EducationalNotice": {
        "type": "string",
        "description": "Educational-only notice. KepAIx is not financial, investment, trading, tax, or legal advice."
      },
      "MarketRegimeResponse": {
        "type": "object",
        "properties": {
          "project": {"type": "string", "example": "KepAIx"},
          "endpoint": {"type": "string", "example": "market-regime"},
          "type": {"type": "string", "example": "educational_market_regime"},
          "market_mode": {"type": "string", "example": "RISK_ON"},
          "market_state": {"type": "string", "example": "RISK_ON"},
          "confidence": {"type": ["number", "null"], "example": 61},
          "risk_score": {"type": ["number", "null"]},
          "summary": {"type": "string"},
          "updated": {"type": "string"},
          "source": {"type": "string"},
          "disclaimer": {"$ref": "#/components/schemas/EducationalNotice"}
        }
      },
      "CoinSnapshot": {
        "type": "object",
        "properties": {
          "asset": {"type": "string", "example": "BTC"},
          "bias": {"type": ["string", "null"], "example": "UP"},
          "confidence": {"type": ["number", "null"], "example": 61},
          "summary": {"type": ["string", "null"]},
          "price": {"type": ["number", "null"]},
          "change_24h": {"type": ["number", "null"]},
          "price_source": {"type": ["string", "null"]}
        }
      },
      "MainBrainResponse": {
        "type": "object",
        "properties": {
          "success": {"type": "boolean", "example": true},
          "project": {"type": "string", "example": "KepAIx"},
          "type": {"type": "string", "example": "main_brain_snapshot"},
          "mode": {"type": "string", "example": "public_educational_api"},
          "updated": {"type": "string"},
          "source": {"type": "string"},
          "market_state": {
            "type": "object",
            "properties": {
              "regime": {"type": ["string", "null"], "example": "risk_on"},
              "global_bias": {"type": ["string", "null"], "example": "UP"},
              "confidence": {"type": ["number", "null"]},
              "risk_score": {"type": ["number", "null"]},
              "reason": {"type": ["string", "null"]}
            }
          },
          "coins": {
            "type": "object",
            "additionalProperties": {"$ref": "#/components/schemas/CoinSnapshot"}
          },
          "developer_note": {"type": "string"},
          "educational_notice": {"$ref": "#/components/schemas/EducationalNotice"},
          "updated_utc": {"type": "string"}
        }
      },
      "RoundInfo": {
        "type": "object",
        "properties": {
          "round_id": {"type": "string", "example": "BTC-20260701-231500"},
          "asset": {"type": "string", "example": "BTC"},
          "start": {"type": "string"},
          "end": {"type": "string"},
          "seconds_left": {"type": "integer"},
          "timer": {"type": "string", "example": "02:27"}
        }
      },
      "HumanConsensus": {
        "type": "object",
        "properties": {
          "total": {"type": "integer"},
          "bullish": {"type": "integer"},
          "bearish": {"type": "integer"},
          "neutral": {"type": "integer"},
          "bullish_percent": {"type": "number"},
          "bearish_percent": {"type": "number"},
          "neutral_percent": {"type": "number"},
          "consensus": {"type": "string", "enum": ["BULLISH", "BEARISH", "NEUTRAL", "NONE"]},
          "disagreement_score": {"type": "number"}
        }
      },
      "HumanConsensusResponse": {
        "type": "object",
        "properties": {
          "success": {"type": "boolean"},
          "project": {"type": "string"},
          "type": {"type": "string", "example": "human_consensus"},
          "mode": {"type": "string"},
          "asset": {"type": "string"},
          "round": {"$ref": "#/components/schemas/RoundInfo"},
          "human_consensus": {"$ref": "#/components/schemas/HumanConsensus"},
          "developer_note": {"type": "string"},
          "educational_notice": {"$ref": "#/components/schemas/EducationalNotice"},
          "updated_utc": {"type": "string"}
        }
      },
      "TeacherLesson": {
        "type": "object",
        "properties": {
          "lesson_id": {"type": "string"},
          "round_id": {"type": "string"},
          "asset": {"type": "string"},
          "brain_prediction": {"type": "string"},
          "human_consensus": {"type": "string"},
          "actual_outcome": {"type": "string"},
          "brain_correct": {"type": "integer"},
          "crowd_correct": {"type": "integer"},
          "agreement": {"type": "integer"},
          "shared_intelligence_score": {"type": "number"},
          "learning_score": {"type": "number"},
          "pattern_type": {"type": "string"},
          "summary": {"type": "string"},
          "created_at": {"type": "string"}
        }
      },
      "TeacherLessonsResponse": {
        "type": "object",
        "properties": {
          "success": {"type": "boolean"},
          "project": {"type": "string"},
          "type": {"type": "string", "example": "teacher_lessons"},
          "mode": {"type": "string"},
          "teacher_brain": {
            "type": "object",
            "properties": {
              "status": {"type": "string"},
              "role": {"type": "string"},
              "metrics": {"type": "object"}
            }
          },
          "latest_lessons": {"type": "array", "items": {"$ref": "#/components/schemas/TeacherLesson"}},
          "developer_note": {"type": "string"},
          "privacy_note": {"type": "string"},
          "educational_notice": {"$ref": "#/components/schemas/EducationalNotice"},
          "updated_utc": {"type": "string"}
        }
      },
      "ReasoningResponse": {
        "type": "object",
        "properties": {
          "success": {"type": "boolean"},
          "project": {"type": "string"},
          "type": {"type": "string", "example": "brain_reasoning"},
          "mode": {"type": "string"},
          "asset": {"type": "string"},
          "reasoning": {
            "type": "object",
            "properties": {
              "prediction": {"type": "string", "example": "BULLISH"},
              "confidence": {"type": ["number", "null"]},
              "summary": {"type": "string"},
              "reason_points": {"type": "array", "items": {"type": "string"}}
            }
          },
          "supported_assets": {"type": "array", "items": {"type": "string"}},
          "developer_note": {"type": "string"},
          "educational_notice": {"$ref": "#/components/schemas/EducationalNotice"},
          "updated_utc": {"type": "string"}
        }
      },
      "StatisticsResponse": {
        "type": "object",
        "properties": {
          "success": {"type": "boolean"},
          "project": {"type": "string"},
          "type": {"type": "string", "example": "network_statistics"},
          "mode": {"type": "string"},
          "main_brain": {"type": "object"},
          "core_learning": {"type": "object"},
          "arena": {"type": "object"},
          "teacher_brain": {"type": "object"},
          "api_ecosystem": {"type": "object"},
          "developer_note": {"type": "string"},
          "educational_notice": {"$ref": "#/components/schemas/EducationalNotice"},
          "updated_utc": {"type": "string"}
        }
      },
      "SharedIntelligenceResponse": {
        "type": "object",
        "properties": {
          "success": {"type": "boolean"},
          "project": {"type": "string"},
          "type": {"type": "string", "example": "arena_shared_intelligence"},
          "mode": {"type": "string"},
          "asset": {"type": "string"},
          "round": {"type": "object"},
          "my_prediction": {"type": ["string", "null"]},
          "brain_snapshot": {"type": "object"},
          "human_layer": {"$ref": "#/components/schemas/HumanConsensus"},
          "combined_intelligence": {"type": "object"},
          "teacher_brain": {"type": "object"},
          "events": {"type": "object"},
          "price": {"type": "object"},
          "system_integrity": {"type": "object"},
          "educational_notice": {"$ref": "#/components/schemas/EducationalNotice"},
          "updated_utc": {"type": "string"}
        }
      },
      "X402PaymentRequiredResponse": {
        "type": "object",
        "properties": {
          "error": {"type": "string", "example": "Payment required"},
          "project": {"type": "string", "example": "KepAIx"},
          "ecosystem": {"type": "string"},
          "endpoint": {"type": "string", "example": "x402-market-regime"},
          "type": {"type": "string", "example": "paid_educational_market_regime"},
          "x402Version": {"type": "integer", "example": 2},
          "resource": {"type": "object"},
          "accepts": {"type": "array", "items": {"type": "object"}},
          "message": {"type": "string"},
          "what_this_is": {"type": "string"},
          "what_this_is_not": {"type": "string"},
          "related_pages": {"type": "object"},
          "disclaimer": {"$ref": "#/components/schemas/EducationalNotice"}
        }
      },
      "X402PaidResponse": {
        "type": "object",
        "properties": {
          "project": {"type": "string", "example": "KepAIx"},
          "endpoint": {"type": "string", "example": "x402-market-regime"},
          "type": {"type": "string", "example": "paid_educational_market_regime"},
          "payment_status": {"type": "string", "example": "settled"},
          "market_mode": {"type": ["string", "null"]},
          "market_state": {"type": ["string", "null"]},
          "confidence": {"type": ["number", "null"]},
          "risk_score": {"type": ["number", "null"]},
          "summary": {"type": ["string", "null"]},
          "source": {"type": "string"},
          "disclaimer": {"$ref": "#/components/schemas/EducationalNotice"}
        }
      }
    }
  }
}