@autonomaai/api-schemas 1.0.0

package/openapi.yaml

@@ -0,0 +1,1434 @@
+openapi: 3.0.3
+info:
+  title: autonoma Unified API
+  description: |
+    Standardized API specification for all autonoma services.
+    
+    This specification normalizes schemas across:
+    - Hummingbot MCP Server
+    - Backend API  
+    - Market Maker Agent
+    - Data Collector
+    - RAG Service
+    
+    **Key Improvements:**
+    - Consistent request/response formats
+    - Standardized error schemas
+    - Unified controller metadata propagation
+    - Version-consistent API contracts
+    
+  version: "1.0.0"
+  contact:
+    name: autonoma Team
+    url: https://github.com/autonoma/autonoma
+  license:
+    name: MIT
+    url: https://opensource.org/licenses/MIT
+
+servers:
+  - url: http://localhost:8000
+    description: Hummingbot MCP Server / Data Collector MCP Server
+  - url: http://localhost:8001  
+    description: Backend API
+  - url: http://localhost:3000
+    description: DexScreener MCP Server (Solana Token Analysis)
+  - url: http://localhost:3002
+    description: RAG Service
+
+paths:
+  # =============================================================================
+  # Health and Context Endpoints
+  # =============================================================================
+  
+  /health:
+    get:
+      summary: Get system health status
+      description: Returns comprehensive system health and capabilities
+      tags: [System]
+      responses:
+        '200':
+          description: System health information
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HealthResponse'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /context:
+    get:
+      summary: Get system context and capabilities
+      description: Returns detailed system context for AI agents
+      tags: [System]
+      responses:
+        '200':
+          description: System context information
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ContextResponse'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  # =============================================================================
+  # Controller Management Endpoints (Normalized)
+  # =============================================================================
+  
+  /controllers:
+    get:
+      summary: List all controllers
+      description: Returns list of all trading controllers
+      tags: [Controllers]
+      parameters:
+        - in: query
+          name: status
+          schema:
+            type: string
+            enum: [active, inactive, error]
+          description: Filter controllers by status
+        - in: query
+          name: strategy
+          schema:
+            type: string
+          description: Filter controllers by strategy type
+      responses:
+        '200':
+          description: List of controllers
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  controllers:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Controller'
+                  count:
+                    type: integer
+                  status:
+                    type: string
+                    enum: [success]
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+    
+    post:
+      summary: Create new controller
+      description: Creates a new trading controller with specified configuration
+      tags: [Controllers]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateControllerRequest'
+      responses:
+        '201':
+          description: Controller created successfully
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/SuccessResponse'
+                  - type: object
+                    properties:
+                      data:
+                        $ref: '#/components/schemas/Controller'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /controllers/{controller_id}:
+    parameters:
+      - $ref: '#/components/parameters/ControllerIdPath'
+    
+    get:
+      summary: Get controller details
+      description: Returns detailed information about a specific controller
+      tags: [Controllers]
+      responses:
+        '200':
+          description: Controller details
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/SuccessResponse'
+                  - type: object
+                    properties:
+                      data:
+                        $ref: '#/components/schemas/Controller'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+    
+    put:
+      summary: Update controller configuration
+      description: Updates the configuration of an existing controller
+      tags: [Controllers]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateControllerRequest'
+      responses:
+        '200':
+          description: Controller updated successfully
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/SuccessResponse'
+                  - type: object
+                    properties:
+                      data:
+                        $ref: '#/components/schemas/Controller'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+    
+    delete:
+      summary: Delete controller
+      description: Stops and removes a controller
+      tags: [Controllers]
+      responses:
+        '200':
+          description: Controller deleted successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SuccessResponse'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /controllers/{controller_id}/start:
+    parameters:
+      - $ref: '#/components/parameters/ControllerIdPath'
+    
+    post:
+      summary: Start controller
+      description: Starts a stopped controller
+      tags: [Controllers]
+      responses:
+        '200':
+          description: Controller started successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SuccessResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /controllers/{controller_id}/stop:
+    parameters:
+      - $ref: '#/components/parameters/ControllerIdPath'
+    
+    post:
+      summary: Stop controller
+      description: Stops a running controller
+      tags: [Controllers]
+      responses:
+        '200':
+          description: Controller stopped successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SuccessResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /controllers/{controller_id}/metrics:
+    parameters:
+      - $ref: '#/components/parameters/ControllerIdPath'
+    
+    get:
+      summary: Get controller metrics
+      description: Returns performance metrics for a controller
+      tags: [Controllers]
+      responses:
+        '200':
+          description: Controller metrics
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/SuccessResponse'
+                  - type: object
+                    properties:
+                      data:
+                        $ref: '#/components/schemas/ControllerMetrics'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  # =============================================================================
+  # Trading Operations (Unified Schema)
+  # =============================================================================
+  
+  /trading/exchanges:
+    get:
+      summary: List supported exchanges
+      description: Returns list of all supported exchanges and their capabilities
+      tags: [Trading]
+      responses:
+        '200':
+          description: List of supported exchanges
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ExchangeListResponse'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /trading/signals/execute:
+    post:
+      summary: Execute trading signal (Unified)
+      description: |
+        **UNIFIED ENDPOINT** for executing trading signals.
+        
+        This replaces the previous inconsistent endpoints:
+        - `/trading/execute-signal`
+        - `/trading/{controller_id}/signal`
+        
+        Now uses standardized TradingSignal schema.
+      tags: [Trading]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ExecuteSignalRequest'
+      responses:
+        '200':
+          description: Signal executed successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SignalExecutionResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /trading/controllers/{controller_id}/connect:
+    parameters:
+      - $ref: '#/components/parameters/ControllerIdPath'
+    
+    post:
+      summary: Connect controller to exchange
+      description: Establishes connection between controller and exchange
+      tags: [Trading]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ConnectExchangeRequest'
+      responses:
+        '200':
+          description: Controller connected successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TradingConnectionResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /trading/controllers/{controller_id}/market-data:
+    parameters:
+      - $ref: '#/components/parameters/ControllerIdPath'
+    
+    get:
+      summary: Get market data for controller
+      description: Returns current market data for the controller's trading pair
+      tags: [Trading]
+      responses:
+        '200':
+          description: Current market data
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/SuccessResponse'
+                  - type: object
+                    properties:
+                      data:
+                        $ref: '#/components/schemas/MarketData'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /trading/controllers/{controller_id}/balance:
+    parameters:
+      - $ref: '#/components/parameters/ControllerIdPath'
+    
+    get:
+      summary: Get account balance
+      description: Returns current account balance for the controller
+      tags: [Trading]
+      responses:
+        '200':
+          description: Account balance information
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/SuccessResponse'
+                  - type: object
+                    properties:
+                      data:
+                        $ref: '#/components/schemas/AccountBalance'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+components:
+  parameters:
+    ControllerIdPath:
+      name: controller_id
+      in: path
+      required: true
+      description: Unique controller identifier
+      schema:
+        type: string
+        pattern: '^[a-zA-Z0-9_-]+$'
+        example: 'ctrl_abc123'
+
+  responses:
+    BadRequest:
+      description: Bad request - invalid parameters
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+    
+    NotFound:
+      description: Resource not found
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+    
+    InternalServerError:
+      description: Internal server error
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+
+  schemas:
+    # =============================================================================
+    # Common Response Schemas
+    # =============================================================================
+    
+    SuccessResponse:
+      type: object
+      required:
+        - success
+        - message
+        - timestamp
+      properties:
+        success:
+          type: boolean
+          example: true
+        message:
+          type: string
+          example: "Operation completed successfully"
+        timestamp:
+          type: string
+          format: date-time
+          example: "2024-12-01T12:00:00Z"
+    
+    ErrorResponse:
+      type: object
+      required:
+        - success
+        - error
+        - timestamp
+      properties:
+        success:
+          type: boolean
+          example: false
+        error:
+          type: string
+          example: "Invalid controller ID"
+        detail:
+          type: string
+          example: "Controller ctrl_123 does not exist"
+        error_code:
+          type: string
+          example: "CONTROLLER_NOT_FOUND"
+        timestamp:
+          type: string
+          format: date-time
+          example: "2024-12-01T12:00:00Z"
+
+    # =============================================================================
+    # Health and Context Schemas
+    # =============================================================================
+    
+    HealthResponse:
+      type: object
+      required:
+        - status
+        - version
+        - services
+        - capabilities
+        - timestamp
+      properties:
+        status:
+          type: string
+          enum: [healthy, degraded, unhealthy]
+          example: "healthy"
+        version:
+          type: string
+          example: "1.0.0"
+        system:
+          type: string
+          example: "autonoma Trading System"
+        services:
+          type: object
+          properties:
+            mcp_server:
+              type: string
+              enum: [healthy, unhealthy]
+            backend_api:
+              type: string
+              enum: [healthy, unhealthy]
+            database:
+              type: string
+              enum: [healthy, unhealthy]
+            redis:
+              type: string
+              enum: [healthy, unhealthy]
+        capabilities:
+          type: object
+          properties:
+            ai_agent_interface:
+              type: boolean
+            live_trading:
+              type: boolean
+            multi_strategy_support:
+              type: boolean
+            real_time_data:
+              type: boolean
+        timestamp:
+          type: string
+          format: date-time
+
+    ContextResponse:
+      type: object
+      required:
+        - name
+        - version
+        - description
+        - endpoints
+        - strategies_supported
+        - exchange_profiles
+      properties:
+        name:
+          type: string
+          example: "autonoma Trading System"
+        version:
+          type: string
+          example: "1.0.0"
+        description:
+          type: string
+          example: "AI-powered trading system with MCP integration"
+        endpoints:
+          type: array
+          items:
+            type: string
+          example: ["/health", "/context", "/controllers"]
+        strategies_supported:
+          type: array
+          items:
+            $ref: '#/components/schemas/StrategyInfo'
+        exchange_profiles:
+          type: array
+          items:
+            $ref: '#/components/schemas/ExchangeProfile'
+        features:
+          type: array
+          items:
+            type: string
+
+    # =============================================================================
+    # Controller Schemas (Normalized)
+    # =============================================================================
+    
+    Controller:
+      type: object
+      required:
+        - id
+        - name
+        - strategy
+        - trading_pair
+        - status
+        - created_at
+        - updated_at
+      properties:
+        id:
+          type: string
+          description: Unique controller identifier
+          example: "ctrl_abc123"
+        name:
+          type: string
+          description: Human-readable controller name
+          example: "BTC Market Maker"
+        strategy:
+          type: string
+          description: Trading strategy type
+          enum: [pure_market_making, avellaneda_market_making, twap, grid_trading, arbitrage]
+          example: "pure_market_making"
+        trading_pair:
+          type: string
+          description: Trading pair symbol
+          example: "BTC-PERP"
+        status:
+          type: string
+          description: Current controller status
+          enum: [active, inactive, error, starting, stopping]
+          example: "active"
+        config:
+          type: object
+          description: Controller configuration parameters
+          additionalProperties: true
+          example:
+            exchange: "hyperliquid"
+            order_amount: 0.001
+            bid_spread: 0.001
+            ask_spread: 0.001
+        metadata:
+          type: object
+          description: Controller metadata (standardized propagation)
+          properties:
+            pool_id:
+              type: string
+              example: "pool_xyz789"
+            created_by:
+              type: string
+              example: "user_123"
+            tags:
+              type: array
+              items:
+                type: string
+              example: ["automated", "high-frequency"]
+        created_at:
+          type: string
+          format: date-time
+          example: "2024-12-01T10:00:00Z"
+        updated_at:
+          type: string
+          format: date-time
+          example: "2024-12-01T12:00:00Z"
+
+    CreateControllerRequest:
+      type: object
+      required:
+        - name
+        - strategy
+        - trading_pair
+        - config
+      properties:
+        name:
+          type: string
+          description: Human-readable controller name
+          example: "BTC Market Maker"
+        strategy:
+          type: string
+          description: Trading strategy type
+          enum: [pure_market_making, avellaneda_market_making, twap, grid_trading, arbitrage]
+          example: "pure_market_making"
+        trading_pair:
+          type: string
+          description: Trading pair symbol
+          example: "BTC-PERP"
+        config:
+          type: object
+          description: Strategy configuration parameters
+          additionalProperties: true
+          example:
+            exchange: "hyperliquid"
+            order_amount: 0.001
+            bid_spread: 0.001
+            ask_spread: 0.001
+            order_refresh_time: 10
+        metadata:
+          type: object
+          description: Optional controller metadata
+          additionalProperties: true
+
+    UpdateControllerRequest:
+      type: object
+      properties:
+        name:
+          type: string
+          description: Updated controller name
+        config:
+          type: object
+          description: Updated configuration parameters
+          additionalProperties: true
+        metadata:
+          type: object
+          description: Updated metadata
+          additionalProperties: true
+
+    ControllerMetrics:
+      type: object
+      required:
+        - controller_id
+        - performance
+        - status
+        - trading_stats
+        - timestamp
+      properties:
+        controller_id:
+          type: string
+          example: "ctrl_abc123"
+        performance:
+          type: object
+          properties:
+            total_pnl:
+              type: number
+              example: 150.75
+            unrealized_pnl:
+              type: number
+              example: 25.50
+            realized_pnl:
+              type: number
+              example: 125.25
+            win_rate:
+              type: number
+              minimum: 0
+              maximum: 100
+              example: 65.5
+            total_trades:
+              type: integer
+              minimum: 0
+              example: 247
+            sharpe_ratio:
+              type: number
+              example: 1.85
+        status:
+          type: object
+          properties:
+            is_running:
+              type: boolean
+              example: true
+            last_update:
+              type: string
+              format: date-time
+              example: "2024-12-01T12:00:00Z"
+            health_score:
+              type: number
+              minimum: 0
+              maximum: 100
+              example: 95.2
+        trading_stats:
+          type: object
+          properties:
+            volume_24h:
+              type: number
+              example: 1250.75
+            fees_paid:
+              type: number
+              example: 12.50
+            active_orders:
+              type: integer
+              minimum: 0
+              example: 4
+            orders_filled:
+              type: integer
+              minimum: 0
+              example: 89
+        timestamp:
+          type: string
+          format: date-time
+          example: "2024-12-01T12:00:00Z"
+
+    # =============================================================================
+    # Trading Schemas (Unified)
+    # =============================================================================
+    
+    TradingSignal:
+      type: object
+      required:
+        - type
+        - side
+        - amount
+        - order_type
+      properties:
+        type:
+          type: string
+          description: Signal type
+          enum: [place_order, cancel_order, modify_order, close_position]
+          example: "place_order"
+        side:
+          type: string
+          description: Order side
+          enum: [buy, sell]
+          example: "buy"
+        amount:
+          type: number
+          description: Order amount/quantity
+          minimum: 0
+          exclusiveMinimum: true
+          example: 0.001
+        price:
+          type: number
+          description: Order price (required for limit orders)
+          minimum: 0
+          exclusiveMinimum: true
+          example: 49900.0
+        order_type:
+          type: string
+          description: Order type
+          enum: [market, limit, stop_loss, take_profit]
+          example: "limit"
+        time_in_force:
+          type: string
+          description: Order time in force
+          enum: [GTC, IOC, FOK]
+          default: "GTC"
+          example: "GTC"
+        metadata:
+          type: object
+          description: Additional signal metadata
+          additionalProperties: true
+
+    ExecuteSignalRequest:
+      type: object
+      required:
+        - controller_id
+        - signal
+      properties:
+        controller_id:
+          type: string
+          description: Target controller identifier
+          example: "ctrl_abc123"
+        signal:
+          $ref: '#/components/schemas/TradingSignal'
+        execution_options:
+          type: object
+          description: Signal execution options
+          properties:
+            dry_run:
+              type: boolean
+              default: false
+              description: Execute as simulation only
+            timeout_seconds:
+              type: integer
+              minimum: 1
+              maximum: 300
+              default: 30
+              description: Execution timeout
+
+    SignalExecutionResponse:
+      allOf:
+        - $ref: '#/components/schemas/SuccessResponse'
+        - type: object
+          properties:
+            data:
+              type: object
+              required:
+                - controller_id
+                - signal_id
+                - execution_time_ms
+              properties:
+                controller_id:
+                  type: string
+                  example: "ctrl_abc123"
+                signal_id:
+                  type: string
+                  description: Unique signal execution identifier
+                  example: "sig_xyz789"
+                order_id:
+                  type: string
+                  description: Exchange order identifier (if applicable)
+                  example: "ord_exchange_123"
+                execution_time_ms:
+                  type: integer
+                  description: Signal execution time in milliseconds
+                  example: 150
+                execution_price:
+                  type: number
+                  description: Actual execution price
+                  example: 49905.0
+                filled_amount:
+                  type: number
+                  description: Amount filled
+                  example: 0.001
+                fees:
+                  type: number
+                  description: Trading fees incurred
+                  example: 0.025
+
+    ExchangeListResponse:
+      allOf:
+        - $ref: '#/components/schemas/SuccessResponse'
+        - type: object
+          properties:
+            data:
+              type: object
+              properties:
+                exchanges:
+                  type: array
+                  items:
+                    $ref: '#/components/schemas/ExchangeProfile'
+                count:
+                  type: integer
+                  example: 3
+
+    ConnectExchangeRequest:
+      type: object
+      required:
+        - exchange
+        - trading_pair
+        - credentials
+      properties:
+        exchange:
+          type: string
+          description: Exchange name
+          enum: [hyperliquid, binance, bybit]
+          example: "hyperliquid"
+        trading_pair:
+          type: string
+          description: Trading pair to connect
+          example: "BTC-PERP"
+        credentials:
+          type: object
+          description: Exchange-specific credentials
+          oneOf:
+            - title: "Hyperliquid Credentials"
+              properties:
+                wallet_address:
+                  type: string
+                  example: "0x1234567890abcdef"
+                private_key:
+                  type: string
+                  format: password
+                  example: "0xabcdef1234567890"
+            - title: "CEX Credentials"
+              properties:
+                api_key:
+                  type: string
+                  example: "api_key_123"
+                api_secret:
+                  type: string
+                  format: password
+                  example: "api_secret_456"
+                passphrase:
+                  type: string
+                  format: password
+                  example: "passphrase_789"
+
+    TradingConnectionResponse:
+      allOf:
+        - $ref: '#/components/schemas/SuccessResponse'
+        - type: object
+          properties:
+            data:
+              type: object
+              required:
+                - controller_id
+                - exchange
+                - trading_pair
+                - status
+                - connected_at
+              properties:
+                controller_id:
+                  type: string
+                  example: "ctrl_abc123"
+                exchange:
+                  type: string
+                  example: "hyperliquid"
+                trading_pair:
+                  type: string
+                  example: "BTC-PERP"
+                status:
+                  type: string
+                  enum: [connected, disconnected, error]
+                  example: "connected"
+                connected_at:
+                  type: string
+                  format: date-time
+                  example: "2024-12-01T12:00:00Z"
+                account_info:
+                  type: object
+                  properties:
+                    balance:
+                      type: number
+                      example: 1000.0
+                    margin_level:
+                      type: number
+                      example: 0.85
+
+    MarketData:
+      type: object
+      required:
+        - symbol
+        - price
+        - timestamp
+      properties:
+        symbol:
+          type: string
+          example: "BTC-PERP"
+        price:
+          type: number
+          example: 49950.0
+        bid:
+          type: number
+          example: 49945.0
+        ask:
+          type: number
+          example: 49955.0
+        volume_24h:
+          type: number
+          example: 1500000.0
+        change_24h:
+          type: number
+          example: 2.5
+        high_24h:
+          type: number
+          example: 50200.0
+        low_24h:
+          type: number
+          example: 49500.0
+        timestamp:
+          type: string
+          format: date-time
+          example: "2024-12-01T12:00:00Z"
+        exchange:
+          type: string
+          example: "hyperliquid"
+
+    AccountBalance:
+      type: object
+      required:
+        - balances
+        - timestamp
+      properties:
+        balances:
+          type: object
+          additionalProperties:
+            type: object
+            properties:
+              available:
+                type: number
+                example: 1000.0
+              locked:
+                type: number
+                example: 50.0
+              total:
+                type: number
+                example: 1050.0
+          example:
+            USDC:
+              available: 1000.0
+              locked: 50.0
+              total: 1050.0
+            BTC:
+              available: 0.02
+              locked: 0.001
+              total: 0.021
+        margin_info:
+          type: object
+          properties:
+            margin_level:
+              type: number
+              example: 0.85
+            maintenance_margin:
+              type: number
+              example: 100.0
+            initial_margin:
+              type: number
+              example: 200.0
+        timestamp:
+          type: string
+          format: date-time
+          example: "2024-12-01T12:00:00Z"
+
+    # =============================================================================
+    # Supporting Schemas
+    # =============================================================================
+    
+    StrategyInfo:
+      type: object
+      required:
+        - name
+        - description
+        - parameters
+        - supported_exchanges
+      properties:
+        name:
+          type: string
+          example: "pure_market_making"
+        description:
+          type: string
+          example: "Basic market making strategy with configurable spreads"
+        parameters:
+          type: object
+          additionalProperties:
+            type: string
+          example:
+            bid_spread: "Bid spread percentage"
+            ask_spread: "Ask spread percentage"
+            order_amount: "Order size"
+        supported_exchanges:
+          type: array
+          items:
+            type: string
+          example: ["hyperliquid", "binance"]
+        risk_management:
+          type: object
+          additionalProperties:
+            type: string
+
+    ExchangeProfile:
+      type: object
+      required:
+        - name
+        - type
+        - supported_pairs
+        - features
+      properties:
+        name:
+          type: string
+          example: "hyperliquid"
+        type:
+          type: string
+          enum: [dex, cex]
+          example: "dex"
+        mode:
+          type: string
+          enum: [spot, perpetual, both]
+          example: "both"
+        supported_pairs:
+          type: array
+          items:
+            type: string
+          example: ["BTC-PERP", "ETH-PERP", "SOL-PERP"]
+        features:
+          type: array
+          items:
+            type: string
+          example: ["low_fees", "fast_execution", "vault_integration"]
+        trading_fees:
+          type: object
+          properties:
+            maker:
+              type: number
+              example: 0.0002
+            taker:
+              type: number
+              example: 0.0005
+        api_rate_limits:
+          type: object
+          additionalProperties:
+            type: number
+          example:
+            requests_per_second: 10
+            orders_per_minute: 60
+
+    # =============================================================================
+    # MCP Tools Schemas (Standardized Interface)
+    # =============================================================================
+
+    MCPRequest:
+      type: object
+      required:
+        - jsonrpc
+        - id
+        - method
+      properties:
+        jsonrpc:
+          type: string
+          enum: ["2.0"]
+          example: "2.0"
+        id:
+          oneOf:
+            - type: string
+            - type: integer
+          example: 1
+        method:
+          type: string
+          enum: ["tools/list", "tools/call", "ping"]
+          example: "tools/list"
+        params:
+          type: object
+          properties:
+            name:
+              type: string
+              description: Tool name for tools/call method
+              example: "get_trending_tokens"
+            arguments:
+              type: object
+              description: Tool arguments for tools/call method
+              additionalProperties: true
+              example:
+                token: "BTC"
+                chain: "hyperliquid"
+
+    MCPResponse:
+      type: object
+      required:
+        - jsonrpc
+        - id
+      properties:
+        jsonrpc:
+          type: string
+          enum: ["2.0"]
+          example: "2.0"
+        id:
+          oneOf:
+            - type: string
+            - type: integer
+          example: 1
+        result:
+          oneOf:
+            - $ref: '#/components/schemas/MCPToolsListResult'
+            - $ref: '#/components/schemas/MCPToolCallResult'
+            - $ref: '#/components/schemas/MCPPingResult'
+        error:
+          $ref: '#/components/schemas/MCPError'
+
+    MCPErrorResponse:
+      type: object
+      required:
+        - jsonrpc
+        - id
+        - error
+      properties:
+        jsonrpc:
+          type: string
+          enum: ["2.0"]
+          example: "2.0"
+        id:
+          oneOf:
+            - type: string
+            - type: integer
+          example: 1
+        error:
+          $ref: '#/components/schemas/MCPError'
+
+    MCPError:
+      type: object
+      required:
+        - code
+        - message
+      properties:
+        code:
+          type: integer
+          example: -32601
+        message:
+          type: string
+          example: "Method not found"
+        data:
+          type: string
+          description: Additional error details
+          example: "Tool 'invalid_tool' not found"
+
+    MCPToolsListResult:
+      type: object
+      required:
+        - tools
+      properties:
+        tools:
+          type: array
+          items:
+            $ref: '#/components/schemas/MCPTool'
+
+    MCPTool:
+      type: object
+      required:
+        - name
+        - title
+        - description
+      properties:
+        name:
+          type: string
+          example: "get_trending_tokens"
+        title:
+          type: string
+          example: "Get Trending Solana Tokens"
+        description:
+          type: string
+          example: "Fetch trending Solana tokens with quality filtering"
+        inputSchema:
+          type: object
+          properties:
+            type:
+              type: string
+              example: "object"
+            properties:
+              type: object
+              additionalProperties: true
+            required:
+              type: array
+              items:
+                type: string
+
+    MCPToolCallResult:
+      type: object
+      required:
+        - content
+      properties:
+        content:
+          type: array
+          items:
+            $ref: '#/components/schemas/MCPContent'
+        meta:
+          type: object
+          additionalProperties: true
+          description: Additional metadata
+        isError:
+          type: boolean
+          example: false
+
+    MCPContent:
+      type: object
+      required:
+        - type
+        - text
+      properties:
+        type:
+          type: string
+          enum: ["text"]
+          example: "text"
+        text:
+          type: string
+          example: "💰 **BTC Price Data**\n\nPrice: $45,000\nChain: hyperliquid"
+
+    MCPPingResult:
+      type: object
+      required:
+        - status
+      properties:
+        status:
+          type: string
+          enum: ["pong"]
+          example: "pong"
+        service:
+          type: string
+          example: "market-data-mcp-server"
+
+  # =============================================================================
+  # MCP Tools Endpoints (Standardized Interface)
+  # =============================================================================
+  
+  /mcp:
+    post:
+      summary: MCP Tools Interface
+      description: |
+        Standardized Model Context Protocol endpoint for executing tools.
+        Supports both DexScreener and Data Collector MCP tools.
+      tags: [MCP Tools]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/MCPRequest'
+            examples:
+              list_tools:
+                summary: List available tools
+                value:
+                  jsonrpc: "2.0"
+                  id: 1
+                  method: "tools/list"
+              call_tool:
+                summary: Call a specific tool
+                value:
+                  jsonrpc: "2.0"
+                  id: 2
+                  method: "tools/call"
+                  params:
+                    name: "get_trending_tokens"
+                    arguments: {}
+              ping:
+                summary: Ping the server
+                value:
+                  jsonrpc: "2.0"
+                  id: 3
+                  method: "ping"
+      responses:
+        '200':
+          description: MCP response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MCPResponse'
+              examples:
+                tools_list:
+                  summary: Tools list response
+                  value:
+                    jsonrpc: "2.0"
+                    id: 1
+                    result:
+                      tools:
+                        - name: "get_trending_tokens"
+                          title: "Get Trending Solana Tokens"
+                          description: "Fetch trending Solana tokens with quality filtering"
+                        - name: "get_token_price"
+                          title: "Get Latest Token Price"
+                          description: "Get latest price for any token on supported chains"
+                tool_result:
+                  summary: Tool execution result
+                  value:
+                    jsonrpc: "2.0"
+                    id: 2
+                    result:
+                      content:
+                        - type: "text"
+                          text: "💰 **BTC Price Data**\n\nPrice: $45,000\nChain: hyperliquid"
+                      meta:
+                        raw_data: {}
+                ping_response:
+                  summary: Ping response
+                  value:
+                    jsonrpc: "2.0"
+                    id: 3
+                    result:
+                      status: "pong"
+                      service: "market-data-mcp-server"
+        '400':
+          description: Invalid request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MCPErrorResponse'
+
+tags:
+  - name: System
+    description: System health and context endpoints
+  - name: Controllers
+    description: Trading controller management
+  - name: Trading
+    description: Trading operations and market data
+  - name: MCP Tools
+    description: Model Context Protocol standardized tools interface