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'
