Version: Next 🚧

Understanding Algorithm Lifecycle

Introduction

Every trading algorithm in x3Algo goes through a well-defined lifecycle from creation to execution and eventual archival. Understanding this lifecycle is crucial for effective algorithm management, troubleshooting, and optimization. This guide explains the six algorithm states, how transitions occur, and best practices for managing algorithms throughout their lifecycle.

Algorithm States

1. Draft

Definition: An algorithm in the initial creation phase, not yet ready for execution.

Characteristics:

Incomplete configuration allowed
Validation is relaxed
Cannot be started or executed
Auto-generated name format: "Algorithm #X"
No performance tracking

When to Use:

During initial algorithm creation
When experimenting with different configurations
When building complex strategies incrementally

Example:

{
  "name": "Algorithm #42",
  "status": "draft",
  "active": false,
  "basicInfo": {
    "strategyType": "momentum"
  }
  // Other steps may be incomplete
}

2. Stopped

Definition: A fully configured algorithm that is not currently executing.

Characteristics:

All 5 configuration steps completed
Passes full validation
Ready to be started
Can be edited and modified
Performance data preserved

When to Use:

After completing algorithm configuration
When temporarily disabling an algorithm
When making configuration changes
During market closures

Transition From:

Draft (via "Complete" action)
Active (via "Stop" action)
Paused (via "Stop" action)

3. Active

Definition: An algorithm that is currently running and monitoring the market for signals.

Characteristics:

Actively scanning for entry conditions
Can open new positions
Executes trades based on configuration
Cannot be edited (must stop first)
Performance metrics updated in real-time

When to Use:

During trading hours when you want the algorithm to execute
When all configuration is finalized and tested
When risk parameters are properly set

Transition From:

Stopped (via "Start" action)
Paused (via "Resume" action)

Important Notes:

Existing open positions remain when stopping
New entries are blocked when stopped
Exit conditions still monitored for open positions

4. Paused

Definition: A temporarily suspended algorithm that can be quickly resumed.

Characteristics:

Temporarily inactive
Configuration locked (cannot edit)
Open positions remain active
Exit conditions still monitored
Can be resumed without re-validation

When to Use:

During high volatility or uncertain market conditions
When temporarily stepping away from trading
During news events or economic announcements
When daily loss limit is approaching

Transition From:

Active (via "Pause" action)

Transition To:

Active (via "Resume" action)
Stopped (via "Stop" action)

5. Error

Definition: An algorithm that encountered a critical error and was automatically stopped.

Characteristics:

Automatically set by the system
Circuit breaker activated
Error details logged
Requires manual intervention
Cannot auto-restart

Common Causes:

Broker connection failures
Invalid configuration discovered during execution
Repeated order rejections
System errors or exceptions

Recovery Steps:

Check error logs and lastExecution.error
Identify and fix the root cause
Update configuration if needed
Manually restart the algorithm

Example Error Object:

{
  "status": "error",
  "lastExecution": {
    "timestamp": "2024-01-15T10:30:00Z",
    "status": "failed",
    "error": "Broker connection timeout after 3 retries"
  }
}

6. Archived

Definition: An algorithm that has been soft-deleted but preserved for historical reference.

Characteristics:

Not visible in main algorithm list
Performance data preserved
Cannot be reactivated (must clone)
Used for algorithms with trading history
Maintains audit trail

When to Use:

When retiring strategies that have performance data
When cleaning up old algorithms
When preserving historical performance records

vs. Hard Delete:

Archived: Soft delete, data preserved, can view history
Hard Delete: Permanent removal, no data recovery

State Transition Diagram

stateDiagram-v2
    [*] --> Draft: Create
    Draft --> Stopped: Complete
    Stopped --> Active: Start
    Active --> Paused: Pause
    Paused --> Active: Resume
    Active --> Stopped: Stop
    Paused --> Stopped: Stop
    Active --> Error: System Error
    Error --> Stopped: Fix & Restart
    Stopped --> Archived: Archive
    Draft --> [*]: Delete

Lifecycle Management

Creating an Algorithm

Step 1: Draft Creation

POST /api/trading/algorithms
{
  "name": "My Strategy",
  "basicInfo": {
    "strategyType": "momentum",
    "timeframe": "15m",
    "symbols": ["NSE:RELIANCE", "NSE:TCS"]
  }
}
// Returns: { status: "draft", ... }

Step 2: Complete Configuration

Configure all 5 steps (Basic Info, Position Sizing, Entry Conditions, Exit Conditions, Risk Parameters)
Validate configuration
Mark as complete

Step 3: Transition to Stopped

POST /api/trading/algorithms/:id/complete
// Returns: { status: "stopped", ... }

Starting an Algorithm

Pre-Start Validation:

All configuration steps completed
Risk parameters within acceptable ranges
Broker connection active (for live trading)
No circuit breaker active
Daily loss limit not exceeded

Start Action:

POST /api/trading/algorithms/:id/start
// Returns: { status: "active", active: true, ... }

What Happens:

System validates configuration
Initializes market data subscriptions
Begins monitoring entry conditions
Updates lastExecution timestamp
Sets active flag to true

Stopping an Algorithm

Stop Action:

POST /api/trading/algorithms/:id/stop
// Returns: { status: "stopped", active: false, ... }

What Happens:

Stops monitoring for new entry signals
Blocks new position entries
Continues monitoring exit conditions for open positions
Unsubscribes from market data
Sets active flag to false

Important: Open positions are NOT automatically closed. They remain active and exit conditions are still monitored.

Pausing an Algorithm

Use Cases:

Temporary market uncertainty
Approaching daily loss limit
News events or economic announcements
Need to step away briefly

Pause Action:

POST /api/trading/algorithms/:id/pause
// Returns: { status: "paused", active: false, ... }

Resume Action:

POST /api/trading/algorithms/:id/resume
// Returns: { status: "active", active: true, ... }

Error Handling

Automatic Error State: The system automatically sets an algorithm to "error" status when:

Broker API returns repeated errors (3+ consecutive failures)
Configuration validation fails during execution
Critical system exceptions occur
Circuit breaker triggers

Recovery Process:

Investigate: Check lastExecution.error for details
Diagnose: Identify root cause (broker, config, system)
Fix: Update configuration or resolve external issues
Test: Validate fix in paper trading mode
Restart: Manually start the algorithm

Example Recovery:

// 1. Check error
GET /api/trading/algorithms/:id
// Response: { status: "error", lastExecution: { error: "..." } }

// 2. Fix configuration
PATCH /api/trading/algorithms/:id
{ /* updated config */ }

// 3. Restart
POST /api/trading/algorithms/:id/start

Archiving Algorithms

When to Archive:

Strategy no longer used but has historical performance
Cleaning up algorithm list
Preserving audit trail for compliance

Archive Action:

DELETE /api/trading/algorithms/:id
// If algorithm has performance data, it's archived
// If no performance data, it's hard deleted

Viewing Archived Algorithms:

GET /api/trading/algorithms?status=archived

Restoring Archived Algorithms: Cannot directly restore. Instead, clone the archived algorithm:

POST /api/trading/algorithms/:id/clone
// Creates new algorithm with same configuration

Status vs Active Flag

Understanding the Difference

Status Field:

Represents the algorithm's lifecycle state
Values: draft, stopped, active, paused, error, archived
Controlled by explicit actions (start, stop, pause)

Active Flag:

Boolean indicating if algorithm is currently executing
true: Algorithm is monitoring and can trade
false: Algorithm is not executing

Combinations:

Status	Active	Meaning
draft	false	Being configured
stopped	false	Ready but not running
active	true	Running and trading
paused	false	Temporarily suspended
error	false	Failed, needs attention
archived	false	Soft deleted

Why Both Fields?

Status provides lifecycle context and history. Active provides real-time execution state.

Example: An algorithm can be "stopped" (status) but still have active=false explicitly set, vs "paused" (status) which also has active=false but with different semantics (can resume vs must start).

Best Practices

1. Development Workflow

Recommended Flow:

Draft → Complete → Stopped → Paper Trading → Stopped → Live Trading

Steps:

Create in draft mode
Configure all 5 steps
Complete to stopped status
Start in paper trading mode
Monitor performance for 1-2 weeks
Stop and review results
Adjust configuration if needed
Start in live trading mode with small position sizes

2. Testing Before Live Trading

Always Test:

Run backtests on historical data
Paper trade for at least 1-2 weeks
Verify entry/exit logic works as expected
Confirm risk parameters are appropriate
Check broker integration works correctly

3. Monitoring Active Algorithms

Regular Checks:

Monitor performance metrics daily
Check for error status
Review lastExecution timestamps
Verify positions are being managed correctly
Watch for circuit breaker activations

4. Handling Errors

Immediate Actions:

Don't panic - open positions are safe
Check error message in lastExecution
Verify broker connection
Review recent trades for issues
Fix root cause before restarting

Common Fixes:

Broker connection: Refresh API credentials
Rate limits: Reduce trading frequency
Configuration: Update invalid parameters
System errors: Contact support

5. Lifecycle Hygiene

Regular Maintenance:

Archive unused algorithms monthly
Review and update active algorithms quarterly
Clean up draft algorithms that are abandoned
Document configuration changes
Maintain version history

6. Position Management

Remember:

Stopping an algorithm does NOT close positions
Exit conditions are still monitored when stopped
Manually close positions if needed before stopping
Pausing maintains all position monitoring

Manual Position Closure:

// Close all positions before stopping
POST /api/trading/algorithms/:id/close-all-positions

// Then stop
POST /api/trading/algorithms/:id/stop

7. Circuit Breaker Awareness

Circuit Breaker Triggers:

Daily loss limit exceeded
Maximum consecutive losses reached
Broker connection failures
System errors

When Triggered:

Algorithm automatically set to error status
No new positions opened
Existing positions remain active
Manual intervention required to restart

8. Version Control

Track Changes:

Document configuration changes
Note performance before/after changes
Use cloning for major variations
Maintain changelog in algorithm notes

Common Scenarios

Scenario 1: Daily Trading Routine

Morning:

// Check status
GET /api/trading/algorithms

// Start algorithms for the day
POST /api/trading/algorithms/:id/start

During Trading:

Monitor performance
Watch for errors
Adjust if needed (requires stop → edit → start)

Evening:

// Stop algorithms after market close
POST /api/trading/algorithms/:id/stop

// Review performance
GET /api/trading/algorithms/:id/performance

Scenario 2: Emergency Stop

High Volatility or News Event:

// Pause immediately (faster than stop)
POST /api/trading/algorithms/:id/pause

// Wait for clarity...

// Resume when safe
POST /api/trading/algorithms/:id/resume

Scenario 3: Configuration Update

Need to Change Settings:

// 1. Stop algorithm
POST /api/trading/algorithms/:id/stop

// 2. Update configuration
PATCH /api/trading/algorithms/:id
{ /* new config */ }

// 3. Restart
POST /api/trading/algorithms/:id/start

Scenario 4: Strategy Retirement

Retiring a Strategy:

// 1. Stop algorithm
POST /api/trading/algorithms/:id/stop

// 2. Close all positions
POST /api/trading/algorithms/:id/close-all-positions

// 3. Archive (soft delete)
DELETE /api/trading/algorithms/:id
// Algorithm moved to archived status

Troubleshooting

Algorithm Won't Start

Check:

Status is "stopped" (not draft, error, or archived)
All 5 configuration steps completed
Broker connection active (for live trading)
Daily loss limit not exceeded
No circuit breaker active

Algorithm Stuck in Error

Resolution:

Check lastExecution.error for details
Fix underlying issue
Verify fix in paper trading
Manually restart with POST /start

Can't Edit Algorithm

Reason: Algorithm is active or paused

Solution:

// Stop first
POST /api/trading/algorithms/:id/stop

// Then edit
PATCH /api/trading/algorithms/:id

Positions Not Closing

Remember: Stopping algorithm doesn't close positions

Solution:

// Manually close positions
POST /api/trading/algorithms/:id/close-all-positions

Summary

Understanding the algorithm lifecycle is essential for effective trading automation:

Six States: draft, stopped, active, paused, error, archived
Clear Transitions: Well-defined actions move between states
Status vs Active: Status provides context, active indicates execution
Best Practices: Test thoroughly, monitor actively, handle errors promptly
Position Management: Stopping doesn't close positions automatically
Error Recovery: Investigate, fix, test, restart

By following these lifecycle management practices, you can ensure your algorithms run smoothly, handle errors gracefully, and maintain a clean, organized trading system.

Getting Started Tutorial - Learn the basics
Paper to Live Trading Transition - Safe deployment practices
Troubleshooting Guide - Common issues and solutions
API Reference - Algorithm Lifecycle - API endpoints for lifecycle management

Introduction​

Algorithm States​

1. Draft​

2. Stopped​

3. Active​

4. Paused​

5. Error​

6. Archived​

State Transition Diagram​

Lifecycle Management​

Creating an Algorithm​

Starting an Algorithm​

Stopping an Algorithm​

Pausing an Algorithm​

Error Handling​

Archiving Algorithms​

Status vs Active Flag​

Understanding the Difference​

Why Both Fields?​

Best Practices​

1. Development Workflow​

2. Testing Before Live Trading​

3. Monitoring Active Algorithms​

4. Handling Errors​

5. Lifecycle Hygiene​

6. Position Management​

7. Circuit Breaker Awareness​

8. Version Control​

Common Scenarios​

Scenario 1: Daily Trading Routine​

Scenario 2: Emergency Stop​

Scenario 3: Configuration Update​

Scenario 4: Strategy Retirement​

Troubleshooting​

Algorithm Won't Start​

Algorithm Stuck in Error​

Can't Edit Algorithm​

Positions Not Closing​

Summary​

Related Documentation​

Introduction

Algorithm States

1. Draft

2. Stopped

3. Active

4. Paused

5. Error

6. Archived

State Transition Diagram

Lifecycle Management

Creating an Algorithm

Starting an Algorithm

Stopping an Algorithm

Pausing an Algorithm

Error Handling

Archiving Algorithms

Status vs Active Flag

Understanding the Difference

Why Both Fields?

Best Practices

1. Development Workflow

2. Testing Before Live Trading

3. Monitoring Active Algorithms

4. Handling Errors

5. Lifecycle Hygiene

6. Position Management

7. Circuit Breaker Awareness

8. Version Control

Common Scenarios

Scenario 1: Daily Trading Routine

Scenario 2: Emergency Stop

Scenario 3: Configuration Update

Scenario 4: Strategy Retirement

Troubleshooting

Algorithm Won't Start

Algorithm Stuck in Error

Can't Edit Algorithm

Positions Not Closing

Summary

Related Documentation