Create Backtest

Run a backtest to evaluate algorithm performance against historical data.

Endpoint

POST /api/backtests

Authentication

Requires authentication via Bearer token.

Authorization: Bearer <access_token>

Request

Headers

Content-Type: application/json
Authorization: Bearer <access_token>

Body

{
  "algorithmId": "507f1f77bcf86cd799439011",
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "initialBalance": 100000,
  "symbols": ["NSE:RELIANCE", "NSE:TCS"]
}

Parameters:

Field	Type	Required	Description
algorithmId	string	Yes	Algorithm ID to backtest
startDate	string	Yes	Start date (YYYY-MM-DD)
endDate	string	Yes	End date (YYYY-MM-DD)
initialBalance	number	Yes	Starting capital (in currency)
symbols	array	No	Symbols to test (uses algorithm symbols if not provided)

Response

Success (201 Created)

{
  "id": "507f1f77bcf86cd799439013",
  "algorithmId": "507f1f77bcf86cd799439011",
  "userId": "507f191e810c19729de860ea",
  "status": "running",
  "startDate": "2024-01-01T00:00:00Z",
  "endDate": "2024-01-31T23:59:59Z",
  "initialBalance": 100000,
  "symbols": ["NSE:RELIANCE", "NSE:TCS"],
  "progress": 0,
  "createdAt": "2024-01-15T11:00:00Z"
}

Errors

Status	Code	Message
400	VALIDATION_ERROR	Invalid date range or parameters
401	UNAUTHORIZED	Authentication required
404	NOT_FOUND	Algorithm not found
422	UNPROCESSABLE_ENTITY	Algorithm configuration incomplete
429	TOO_MANY_REQUESTS	Rate limit exceeded (10 per minute)

Error Response Examples

Invalid Date Range:

{
  "error": {
    "message": "End date must be after start date",
    "code": "VALIDATION_ERROR",
    "status": 400
  }
}

Incomplete Algorithm:

{
  "error": {
    "message": "Algorithm must have entry and exit conditions",
    "code": "UNPROCESSABLE_ENTITY",
    "status": 422
  }
}

Examples

Run Basic Backtest

cURL:

curl -X POST https://api.x3algo.com/api/backtests \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "algorithmId": "507f1f77bcf86cd799439011",
    "startDate": "2024-01-01",
    "endDate": "2024-01-31",
    "initialBalance": 100000
  }'

JavaScript:

const backtest = {
  algorithmId: '507f1f77bcf86cd799439011',
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  initialBalance: 100000
}

const response = await fetch('https://api.x3algo.com/api/backtests', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(backtest)
})

const result = await response.json()
console.log('Backtest ID:', result.id)

// Poll for completion
const completed = await pollBacktestStatus(result.id)
console.log('Results:', completed.results)

Python:

backtest = {
    'algorithmId': '507f1f77bcf86cd799439011',
    'startDate': '2024-01-01',
    'endDate': '2024-01-31',
    'initialBalance': 100000
}

response = requests.post(
    'https://api.x3algo.com/api/backtests',
    headers={'Authorization': f'Bearer {access_token}'},
    json=backtest
)

result = response.json()
print('Backtest ID:', result['id'])

Run Backtest with Specific Symbols

JavaScript:

const backtest = {
  algorithmId: '507f1f77bcf86cd799439011',
  startDate: '2023-01-01',
  endDate: '2023-12-31',
  initialBalance: 500000,
  symbols: ['NSE:NIFTY', 'NSE:BANKNIFTY']
}

const response = await fetch('https://api.x3algo.com/api/backtests', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(backtest)
})

Poll for Backtest Completion

JavaScript:

async function pollBacktestStatus(backtestId, maxAttempts = 60) {
  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://api.x3algo.com/api/backtests/${backtestId}`,
      {
        headers: { 'Authorization': `Bearer ${accessToken}` }
      }
    )
    
    const backtest = await response.json()
    
    if (backtest.status === 'completed') {
      return backtest
    }
    
    if (backtest.status === 'failed') {
      throw new Error(`Backtest failed: ${backtest.error}`)
    }
    
    console.log(`Progress: ${backtest.progress}%`)
    
    // Wait 5 seconds before next poll
    await new Promise(resolve => setTimeout(resolve, 5000))
  }
  
  throw new Error('Backtest timeout')
}

Backtest Process

1. Validation

   • Verify algorithm configuration is complete
   • Validate date range
   • Check data availability

2. Execution

   • Load historical candle data
   • Simulate algorithm execution
   • Track trades and performance
   • Update progress (0-100%)

3. Completion

   • Calculate performance metrics
   • Generate equity curve
   • Store results
   • Status changes to completed

Performance Considerations

• Backtests run asynchronously
• Typical completion time: 1-5 minutes
• Longer date ranges take more time
• Multiple symbols increase processing time
• Rate limited to 10 backtests per minute

Notes

• Backtests use historical data with realistic slippage
• Results include all performance metrics
• Equity curve shows balance over time
• Trade-by-trade details are available
• Results are cached for 30 days

Related

• Get Backtest Results
• List Backtests
• Algorithm API