> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequency.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Start trade execution from debate

> Start the trade execution workflow from a debate result.

## Workflow
1. Loads the debate result from database
2. Calls the strategy agent to generate a TradingStrategy
3. Runs risk guardian pre-trade validation
4. Creates the trade execution record
5. Registers with the Go trade-executor service
6. Returns ExecutionResponse with strategy plan and risk validation

## Requirements
- Valid debate_id from a completed debate
- Execution system must be enabled
- Risk validation must pass (or trade is rejected)

## Trading Mode
Uses the configured trading mode (paper/live). Paper and live use
the same code paths; only the Alpaca base URL differs.



## OpenAPI

````yaml /api/openapi.json post /api/graph/v1/execution/start
openapi: 3.1.0
info:
  title: Sequency Graph API
  description: >

    # Sequency Graph-Native Trading API


    Graph-native API for trading intelligence, built on FalkorDB.


    ## Features


    - **Screener**: Filter stocks using graph-native queries with relationship
    expansion

    - **Stock Detail**: Complete stock context with all relationships

    - **Confluence Scoring**: Setup quality assessment with weighted components

    - **Strategy Matching**: Find matching options strategies via graph
    traversal

    - **Market Context**: Current market-wide context for trading decisions


    ## Data Sources


    All data is sourced from the FalkorDB knowledge graph, populated by:

    - Pattern detector (Go) - Technical indicators, patterns

    - Graph sync service - Levels, volume profiles, news, day classification
  version: 1.0.0
servers: []
security: []
paths:
  /api/graph/v1/execution/start:
    post:
      tags:
        - Execution
      summary: Start trade execution from debate
      description: |-
        Start the trade execution workflow from a debate result.

        ## Workflow
        1. Loads the debate result from database
        2. Calls the strategy agent to generate a TradingStrategy
        3. Runs risk guardian pre-trade validation
        4. Creates the trade execution record
        5. Registers with the Go trade-executor service
        6. Returns ExecutionResponse with strategy plan and risk validation

        ## Requirements
        - Valid debate_id from a completed debate
        - Execution system must be enabled
        - Risk validation must pass (or trade is rejected)

        ## Trading Mode
        Uses the configured trading mode (paper/live). Paper and live use
        the same code paths; only the Alpaca base URL differs.
      operationId: start_execution_api_graph_v1_execution_start_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartExecutionRequest'
        required: true
      responses:
        '200':
          description: Execution started successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionResponse'
        '404':
          description: Debate not found
        '422':
          description: Risk validation failed -- trade rejected
components:
  schemas:
    StartExecutionRequest:
      properties:
        debate_id:
          type: string
          format: uuid
          title: Debate Id
          description: Source debate UUID
        timeframe:
          type: string
          title: Timeframe
          description: Trading timeframe (day, swing, position)
          default: swing
        risk_appetite:
          type: string
          title: Risk Appetite
          description: Risk appetite (conservative, moderate, aggressive)
          default: moderate
        account_value:
          anyOf:
            - type: number
              exclusiveMinimum: 0
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Account Value
          description: Account value for sizing (uses default if not provided)
        account_tier:
          anyOf:
            - type: integer
              maximum: 3
              minimum: 1
            - type: 'null'
          title: Account Tier
          description: Account tier (1=starter, 2=intermediate, 3=advanced)
      type: object
      required:
        - debate_id
      title: StartExecutionRequest
      description: Request to start trade execution from a debate result.
    ExecutionResponse:
      properties:
        execution:
          $ref: '#/components/schemas/TradeExecution'
          description: Current trade execution state
        strategy_plan:
          anyOf:
            - $ref: '#/components/schemas/StrategyPlan'
            - type: 'null'
          description: Active strategy plan
        recent_state_log:
          items:
            $ref: '#/components/schemas/TradeStateLogEntry'
          type: array
          title: Recent State Log
          description: Recent state transition log entries (last 10)
        risk_validation:
          anyOf:
            - $ref: '#/components/schemas/RiskValidationResult'
            - type: 'null'
          description: Latest risk validation result
      type: object
      required:
        - execution
      title: ExecutionResponse
      description: Full trade execution state response.
    TradeExecution:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Trade execution UUID
        debate_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Debate Id
          description: Source debate UUID that triggered this execution
        symbol:
          type: string
          title: Symbol
          description: Stock ticker symbol
        direction:
          $ref: '#/components/schemas/app__models__execution__TradeDirection'
          description: Trade direction
        execution_mode:
          $ref: '#/components/schemas/ExecutionMode'
          description: Assisted or autonomous
        status:
          $ref: '#/components/schemas/TradeExecutionStatus'
          description: Current lifecycle status
        strategy_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Strategy Name
          description: Active strategy name
        instrument_type:
          $ref: '#/components/schemas/app__models__execution__InstrumentType'
          description: Instrument type
          default: option
        contract_symbol:
          anyOf:
            - type: string
            - type: 'null'
          title: Contract Symbol
          description: OCC contract symbol
        entry_order_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Entry Order Id
          description: Alpaca entry order ID
        entry_price:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Entry Price
          description: Filled entry price
        entry_quantity:
          anyOf:
            - type: integer
            - type: 'null'
          title: Entry Quantity
          description: Filled entry quantity
        entry_filled_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Entry Filled At
          description: Entry fill timestamp
        exit_order_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Exit Order Id
          description: Alpaca exit order ID
        exit_price:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Exit Price
          description: Filled exit price
        exit_quantity:
          anyOf:
            - type: integer
            - type: 'null'
          title: Exit Quantity
          description: Filled exit quantity
        exit_filled_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Exit Filled At
          description: Exit fill timestamp
        exit_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Exit Reason
          description: Reason for exit (e.g., 'target_hit', 'stop_loss', 'time_exit')
        realized_pnl:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Realized Pnl
          description: Realized P&L in dollars
        realized_pnl_pct:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Realized Pnl Pct
          description: Realized P&L as percentage
        max_favorable_excursion:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Max Favorable Excursion
          description: Maximum favorable excursion (best unrealized P&L)
        max_adverse_excursion:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Max Adverse Excursion
          description: Maximum adverse excursion (worst unrealized P&L)
        risk_dollars:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Risk Dollars
          description: Dollars at risk
        initial_stop:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Initial Stop
          description: Initial stop loss price
        current_stop:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Current Stop
          description: Current (possibly adjusted) stop price
        trading_mode:
          type: string
          title: Trading Mode
          description: 'Trading mode: ''paper'' or ''live'''
          default: paper
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Record creation timestamp
        updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updated At
          description: Last update timestamp
      type: object
      required:
        - id
        - symbol
        - direction
        - execution_mode
        - status
      title: TradeExecution
      description: |-
        Complete trade execution record.

        Tracks the full lifecycle from strategy generation through close,
        including all entry/exit details, P&L, and risk parameters.
    StrategyPlan:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Strategy plan UUID
        trade_execution_id:
          type: string
          format: uuid
          title: Trade Execution Id
          description: Parent trade execution UUID
        strategy_name:
          type: string
          title: Strategy Name
          description: Strategy name
        direction:
          $ref: '#/components/schemas/app__models__execution__TradeDirection'
          description: Trade direction
        entry_plan:
          additionalProperties: true
          type: object
          title: Entry Plan
          description: Entry plan as JSON
        exit_plan:
          additionalProperties: true
          type: object
          title: Exit Plan
          description: Exit plan as JSON
        position_sizing:
          additionalProperties: true
          type: object
          title: Position Sizing
          description: Position sizing as JSON
        contract_symbol:
          anyOf:
            - type: string
            - type: 'null'
          title: Contract Symbol
        contract_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Contract Type
        strike:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Strike
        expiration:
          anyOf:
            - type: string
            - type: 'null'
          title: Expiration
        target_delta:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Target Delta
        invalidation_price:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Invalidation Price
        model_used:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Used
          description: LLM model that generated this strategy
        tokens_used:
          anyOf:
            - type: integer
            - type: 'null'
          title: Tokens Used
          description: Total tokens consumed
        generation_latency_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: Generation Latency Ms
          description: Strategy generation latency in milliseconds
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
        - id
        - trade_execution_id
        - strategy_name
        - direction
        - entry_plan
        - exit_plan
        - position_sizing
      title: StrategyPlan
      description: |-
        Persisted strategy plan linked to an execution.

        Stores the full LLM-generated strategy with metadata for audit trail.
    TradeStateLogEntry:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Log entry UUID
        trade_execution_id:
          type: string
          format: uuid
          title: Trade Execution Id
          description: Parent trade execution UUID
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Transition timestamp
        from_status:
          $ref: '#/components/schemas/TradeExecutionStatus'
          description: Status before transition
        to_status:
          $ref: '#/components/schemas/TradeExecutionStatus'
          description: Status after transition
        trigger:
          type: string
          title: Trigger
          description: >-
            What triggered the transition (e.g., 'risk_check_passed',
            'user_action')
        agent_phase:
          anyOf:
            - $ref: '#/components/schemas/AgentPhase'
            - type: 'null'
          description: Agent phase that triggered transition
        reasoning:
          anyOf:
            - type: string
            - type: 'null'
          title: Reasoning
          description: Human-readable reasoning for the transition
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
          description: Additional transition metadata
      type: object
      required:
        - id
        - trade_execution_id
        - timestamp
        - from_status
        - to_status
        - trigger
      title: TradeStateLogEntry
      description: |-
        State transition log entry for audit trail.

        Every status change is recorded with trigger, reasoning, and metadata.
    RiskValidationResult:
      properties:
        passed:
          type: boolean
          title: Passed
          description: Whether all required checks passed
        checks:
          items:
            $ref: '#/components/schemas/RiskCheckResult'
          type: array
          title: Checks
          description: Individual check results
        blocked_reasons:
          items:
            type: string
          type: array
          title: Blocked Reasons
          description: Reasons trade was blocked (empty if passed)
        size_modifier:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Size Modifier
          description: Position size modifier (< 1.0 if consecutive losses reduce size)
          default: '1.0'
        sized_position_pct:
          anyOf:
            - type: number
            - type: 'null'
          title: Sized Position Pct
          description: Final position size from sizing engine (None if engine disabled)
        sizing_adjustments:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Sizing Adjustments
          description: Sizing engine adjustment factors for snapshot capture
        or05_decision:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Or05 Decision
          description: Exact replayable OR-05 policy decision evaluated at this boundary
      type: object
      required:
        - passed
      title: RiskValidationResult
      description: Aggregate result from all pre-trade risk checks.
    app__models__execution__TradeDirection:
      type: string
      enum:
        - long
        - short
      title: TradeDirection
      description: Trade direction.
    ExecutionMode:
      type: string
      enum:
        - assisted
        - autonomous
      title: ExecutionMode
      description: Execution mode determining human involvement.
    TradeExecutionStatus:
      type: string
      enum:
        - strategy_generated
        - risk_validated
        - awaiting_entry
        - order_pending
        - position_open
        - exit_pending
        - closed
        - cancelled
        - rejected
        - expired
        - error
        - pending_submission
        - partially_filled
        - submission_failed
        - pending_verification
      title: TradeExecutionStatus
      description: |-
        Trade execution lifecycle status.

        Matches the DB enum for trade_execution.status column.
        Transitions are enforced by TradeManager.VALID_TRANSITIONS.
    app__models__execution__InstrumentType:
      type: string
      enum:
        - option
        - equity
      title: InstrumentType
      description: Instrument type for the trade.
    AgentPhase:
      type: string
      enum:
        - strategy
        - entry
        - exit
        - autonomous_scan
        - autonomous_review
      title: AgentPhase
      description: Agent execution phase for decision logging.
    RiskCheckResult:
      properties:
        rule_name:
          type: string
          title: Rule Name
          description: Risk rule identifier
        passed:
          type: boolean
          title: Passed
          description: Whether this check passed
        current_value:
          anyOf:
            - type: string
            - type: 'null'
          title: Current Value
          description: Current value being checked
        limit_value:
          anyOf:
            - type: string
            - type: 'null'
          title: Limit Value
          description: Limit/threshold value
        action:
          type: string
          title: Action
          description: 'Action: ''passed'', ''blocked'', ''size_reduced'', ''warning'''
        message:
          type: string
          title: Message
          description: Human-readable check result message
      type: object
      required:
        - rule_name
        - passed
        - action
        - message
      title: RiskCheckResult
      description: Result from a single risk check rule.

````