Factor Intelligence API

Access factor intelligence using the 12-factor archetype model. This endpoint is what the dashboard uses for the factor radar and “dominant forces” views.

Endpoint

curl "https://YOUR_BACKEND_DOMAIN/api/archetypes/current?symbol=SPY" \
  -H "X-API-Key: your-api-key"

Parameters

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | symbol | string | No | "SPY" | The stock symbol to analyze (e.g., "SPY", "AAPL", "QQQ") |

Response

The endpoint returns a payload with per-archetype “power” values.

{
  "symbol": "SPY",
  "timestamp": "2026-01-19T01:00:00Z",
  "powers": {
    "athena": 0.62,
    "zeus": 0.48,
    "apollo": 0.31
  }
}

Factor Dimensions

Each factor represents a different aspect of market conditions:

| Dimension | Code | Description | Power Range | |-----------|------|-------------|-------------| | Liquidity | D-01 | Trading volume and market depth | 0.0 - 1.0 | | Relationships | D-02 | Sector and asset correlations | 0.0 - 1.0 | | Volatility | D-03 | Market volatility regime | 0.0 - 1.0 | | Economics | D-04 | Economic cycle positioning | 0.0 - 1.0 | | Risk Premium | D-05 | Risk assessment and pricing | 0.0 - 1.0 | | Clarity | D-06 | Price discovery efficiency | 0.0 - 1.0 | | Protection | D-07 | Defensive positioning demand | 0.0 - 1.0 | | Momentum | D-08 | Price momentum strength | 0.0 - 1.0 | | Structure | D-09 | Technical analysis patterns | 0.0 - 1.0 | | Sentiment | D-10 | Investor sentiment indicators | 0.0 - 1.0 | | Velocity | D-11 | Market speed and tempo | 0.0 - 1.0 | | Chaos | D-12 | Extreme events and tail risk | 0.0 - 1.0 |

Response Fields

| Field | Type | Description | |-------|------|-------------| | name | string | Human-readable dimension name | | code | string | Dimension identifier code | | power | number | Power level (0.0 to 1.0, higher = stronger influence) | | description | string | Brief description of the dimension | | domain | string | Specific market indicators measured | | icon | string | Visual icon representing the dimension | | color | string | Tailwind CSS gradient classes for visualization |

Error Responses

| Status Code | Error | Description | |-------------|-------|-------------| | 400 | INVALID_SYMBOL | The provided symbol is not valid or supported | | 401 | UNAUTHORIZED | Invalid or missing API key | | 429 | RATE_LIMITED | Too many requests | | 500 | INTERNAL_ERROR | Server error occurred | | 502 | BACKEND_UNAVAILABLE | Market data backend temporarily unavailable |

Usage Examples

Analyze Market Conditions

const factors = await client.factors.get({ symbol: 'SPY' })

// Find the strongest influencing factors
const strongFactors = factors
  .filter(factor => factor.power > 0.7)
  .sort((a, b) => b.power - a.power)

console.log('Strong market influences:')
strongFactors.forEach(factor => {
  console.log(`${factor.name}: ${factor.power} (${factor.description})`)
})

Risk Assessment

const factors = await client.factors.get({ symbol: 'SPY' })

// Calculate overall market risk score
const riskFactors = ['D-03', 'D-05', 'D-12'] // Volatility, Risk Premium, Chaos
const riskScore = riskFactors.reduce((score, code) => {
  const factor = factors.find(f => f.code === code)
  return score + (factor ? factor.power : 0)
}, 0) / riskFactors.length

console.log(`Market Risk Score: ${(riskScore * 100).toFixed(1)}%`)

Trading Signal Generation

const factors = await client.factors.get({ symbol: 'AAPL' })

// Momentum-based trading signal
const momentum = factors.find(f => f.code === 'D-08')
const volatility = factors.find(f => f.code === 'D-03')

if (momentum.power > 0.8 && volatility.power < 0.6) {
  console.log('🚀 Strong momentum with low volatility - BULLISH signal')
} else if (momentum.power < 0.3 && volatility.power > 0.8) {
  console.log('⚠️ Weak momentum with high volatility - BEARISH signal')
} else {
  console.log('🤔 Mixed signals - NEUTRAL')
}

Portfolio Optimization

async function getDiversificationFactors(symbols) {
  const results = {}

  for (const symbol of symbols) {
    const factors = await client.factors.get({ symbol })
    const correlationFactor = factors.find(f => f.code === 'D-02')

    results[symbol] = {
      correlationRisk: correlationFactor.power,
      diversificationBenefit: 1 - correlationFactor.power
    }
  }

  return results
}

// Usage
const portfolioSymbols = ['AAPL', 'MSFT', 'GOOGL', 'AMZN']
const diversification = await getDiversificationFactors(portfolioSymbols)

console.log('Portfolio Diversification Analysis:')
Object.entries(diversification).forEach(([symbol, data]) => {
  console.log(`${symbol}: ${(data.diversificationBenefit * 100).toFixed(1)}% diversification benefit`)
})

Data Freshness

• Update Frequency: Factors are updated in real-time during market hours
• Historical Data: Available for the past 2 years
• Supported Symbols: Major US equities, ETFs, and indices

Rate Limits

This endpoint has a rate limit of 100 requests per minute per API key. Higher tiers offer increased limits.