# Schema

61+ queryable fields and 56 pre-thresholded boolean flags per ticker, recomputed every minute. The same identifier is the field name on a ticker response, the column name in a SQL WHERE clause, the signal name on a history pull, the order/fields argument on a scan, and the column scoped by a saved rule.

For a machine-readable JSON dump, see https://tickerbot.io/api/schema.json.

## Fields

### Identification

| Name | Type | Cadence | Description |
|------|------|---------|-------------|
| `ticker` | string | Daily, post-close | Ticker symbol. Equities use the exchange symbol (e.g. AAPL). Crypto uses the bare symbol (e.g. BTC, ETH). |
| `name` | string | Daily, post-close | Company or asset display name. |
| `asset_type` | enum | Daily, post-close | Asset class. One of `equity`, `etf`, or `crypto`. |
| `active` | boolean | Daily, post-close | Whether this ticker is actively tracked. False for delisted or auto-halted symbols. |

### Price & change

| Name | Type | Cadence | Description |
|------|------|---------|-------------|
| `price` | number | Every 1 min, 4 AM–8 PM ET weekdays | Most recent trade price. |
| `previous_close` | number | Daily, post-close | Official prior-session close. |
| `session_open` | number | Every 1 min, 4 AM–8 PM ET weekdays | Today’s opening print. |
| `session_high` | number | Every 1 min, 4 AM–8 PM ET weekdays | Highest trade so far today. |
| `session_low` | number | Every 1 min, 4 AM–8 PM ET weekdays | Lowest trade so far today. |
| `day_change` | number | Every 1 min, 4 AM–8 PM ET weekdays | Absolute change vs `previous_close`. |
| `day_change_pct` | number | Every 1 min, 4 AM–8 PM ET weekdays | Percent change vs `previous_close`. Expressed as a percent (5.2 = 5.2%), not a fraction. |
| `gap_pct` | number | Every 1 min, 4 AM–8 PM ET weekdays | Percent change of `session_open` vs `previous_close`. One value per session. |
| `premarket_price` | number | Every 1 min, 4 AM–8 PM ET weekdays | Last premarket price, if available. |
| `afterhours_price` | number | Every 1 min, 4 AM–8 PM ET weekdays | Last after-hours price, if available. |

### Volume

| Name | Type | Cadence | Description |
|------|------|---------|-------------|
| `volume_today` | integer | Every 1 min, 4 AM–8 PM ET weekdays | Shares traded so far today. |
| `avg_volume_10d` | integer | Daily, post-close | 10-day trailing average daily volume. |
| `avg_volume_30d` | integer | Daily, post-close | 30-day trailing average daily volume. |
| `relative_volume` | number | Every 1 min, 4 AM–8 PM ET weekdays | Ratio of today’s pace-adjusted volume to the 10-day average. 2.0 means 2× normal. |
| `day_dollar_volume` | number | Every 1 min, 4 AM–8 PM ET weekdays | Today’s cumulative dollar volume traded. |
| `day_vwap` | number | Every 1 min, 4 AM–8 PM ET weekdays | Today’s session volume-weighted average price. |

### 52-week & period extremes

| Name | Type | Cadence | Description |
|------|------|---------|-------------|
| `high_52w` | number | Every 1 min, 4 AM–8 PM ET weekdays | Highest trade in the trailing 52 weeks (live, includes today). |
| `low_52w` | number | Every 1 min, 4 AM–8 PM ET weekdays | Lowest trade in the trailing 52 weeks (live, includes today). |
| `high_20d` | number | Every 1 min, 4 AM–8 PM ET weekdays | Highest trade in the trailing 20 trading days. |
| `low_20d` | number | Every 1 min, 4 AM–8 PM ET weekdays | Lowest trade in the trailing 20 trading days. |
| `days_since_52w_high` | integer | Daily, post-close | Trading days since the most recent 52-week high. |
| `days_since_52w_low` | integer | Daily, post-close | Trading days since the most recent 52-week low. |

### Relative position

| Name | Type | Cadence | Description |
|------|------|---------|-------------|
| `pct_from_52w_high` | number | Every 1 min, 4 AM–8 PM ET weekdays | Percent below the 52-week high. Always >= 0 (use the `at_52w_high` flag to test highs). |
| `pct_from_52w_low` | number | Every 1 min, 4 AM–8 PM ET weekdays | Percent above the 52-week low. Always >= 0. |
| `position_in_52w_range` | number | Every 1 min, 4 AM–8 PM ET weekdays | Where the live price sits in the 52-week range, 0–100. 0 = at low, 100 = at high. |
| `pct_from_sma_50` | number | Every 1 min, 4 AM–8 PM ET weekdays | Percent distance from the 50-day SMA. Negative when price is below the average. |
| `pct_from_sma_200` | number | Every 1 min, 4 AM–8 PM ET weekdays | Percent distance from the 200-day SMA. Negative when price is below the average. |
| `pct_from_vwap` | number | Every 1 min, 4 AM–8 PM ET weekdays | Percent distance from today’s VWAP. |

### Volatility

| Name | Type | Cadence | Description |
|------|------|---------|-------------|
| `atr_14` | number | Daily, post-close | 14-day Average True Range. |
| `atr_percent` | number | Every 1 min, 4 AM–8 PM ET weekdays | ATR(14) as a percent of price. Useful as a volatility filter. |
| `bollinger_pct_b` | number | Every 1 min, 4 AM–8 PM ET weekdays | Position within Bollinger bands. 0 = at lower band, 1 = at upper band, >1 = outside. |

### Technical indicators

| Name | Type | Cadence | Description |
|------|------|---------|-------------|
| `sma_10` | number | Daily, post-close | 10-day simple moving average. |
| `sma_20` | number | Daily, post-close | 20-day simple moving average. |
| `sma_50` | number | Daily, post-close | 50-day simple moving average. |
| `sma_200` | number | Daily, post-close | 200-day simple moving average. |
| `rsi_14` | number | Every 1 min, 4 AM–8 PM ET weekdays | Relative Strength Index, 14-period. Range 0–100. |
| `macd_line` | number | Every 1 min, 4 AM–8 PM ET weekdays | MACD line (12-EMA minus 26-EMA). |
| `macd_signal` | number | Every 1 min, 4 AM–8 PM ET weekdays | MACD signal line (9-EMA of MACD line). |
| `macd_histogram` | number | Every 1 min, 4 AM–8 PM ET weekdays | MACD line minus signal. Positive when bullish, negative when bearish. |
| `bollinger_upper` | number | Every 1 min, 4 AM–8 PM ET weekdays | Upper Bollinger band (20-period, 2σ). |
| `bollinger_lower` | number | Every 1 min, 4 AM–8 PM ET weekdays | Lower Bollinger band (20-period, 2σ). |

### Fundamentals

| Name | Type | Cadence | Description |
|------|------|---------|-------------|
| `market_cap` | number | Daily, post-close | Market capitalization. Updated daily; intraday change derived from `price` × `shares_outstanding`. |
| `pe_ratio` | number | Quarterly, after issuer files | Price-to-earnings ratio (trailing twelve months). Null for unprofitable issuers. |
| `eps` | number | Quarterly, after issuer files | Earnings per share (trailing twelve months). |
| `dividend_yield` | number | Daily, post-close | Forward dividend yield as a fraction (0.025 = 2.5%). Null for non-payers. |
| `beta` | number | Daily, post-close | Trailing beta vs SPY. Null for issuers with insufficient price history. |
| `float_shares` | integer | Daily, post-close | Public float (shares available to trade). |
| `shares_outstanding` | integer | Daily, post-close | Total shares outstanding. |

### Classification

| Name | Type | Cadence | Description |
|------|------|---------|-------------|
| `sector` | enum | Daily, post-close | GICS sector. One of: Technology, Healthcare, Financials, Consumer Discretionary, Consumer Staples, Energy, Industrials, Materials, Utilities, Real Estate, Communication Services. |
| `industry` | string | Daily, post-close | GICS industry within the sector. |
| `exchange` | enum | Daily, post-close | Listing exchange. One of `NYSE`, `NASDAQ`, `AMEX`, `OTC`, `CRYPTO`. |
| `country` | string | Daily, post-close | ISO country code of the issuer. |

### Event dates

| Name | Type | Cadence | Description |
|------|------|---------|-------------|
| `earnings_date` | date | On corporate event | Next scheduled earnings announcement date. Null if not scheduled. |
| `days_to_earnings` | integer | Daily, post-close | Calendar days until next earnings announcement. Negative after report. |
| `ex_dividend_date` | date | On corporate event | Next ex-dividend date. |

### News

| Name | Type | Cadence | Description |
|------|------|---------|-------------|
| `news_volume` | number | Every 15 min | Count of news articles published in the last 24 hours mentioning this ticker with AlphaVantage relevance score ≥ 0.6. Refreshed every 15 minutes. Null when no qualifying articles in the window. |
| `news_volume_weighted_sentiment` | number | Every 15 min | Range -1.0 to +1.0. The relevance-weighted average sentiment of articles in the last 24 hours, attenuated by `tanh(news_volume / 15)` so quiet tickers (1-2 articles) read near zero regardless of sentiment sign. Strong negative = loud bad news; strong positive = loud good news; values near 0 = quiet or mixed. Null when no qualifying articles. |

## Flags

### Moving averages

| Name | Firing | Kind | Summary |
|------|--------|------|---------|
| `above_sma_10` | Continuous | State | Price is above the 10-day simple moving average. |
| `above_sma_20` | Continuous | State | Price is above the 20-day simple moving average. |
| `above_sma_50` | Continuous | State | Price is above the 50-day simple moving average. |
| `above_sma_200` | Continuous | State | Price is above the 200-day simple moving average. |
| `above_vwap` | Continuous | State | Price is above today’s volume-weighted average price. |
| `golden_cross_today` | Sticky for session | Event | 50-day SMA crossed above 200-day SMA today. |
| `death_cross_today` | Sticky for session | Event | 50-day SMA crossed below 200-day SMA today. |
| `macd_above_signal` | Continuous | State | MACD line is above its signal line. |

### Trend

| Name | Firing | Kind | Summary |
|------|--------|------|---------|
| `in_uptrend` | Continuous | State | Stacked uptrend across short, medium, and long horizons. |
| `in_downtrend` | Continuous | State | Stacked downtrend across short, medium, and long horizons. |
| `trend_reversal_bullish_today` | Sticky for session | Event | Trend flipped from down to up today. |
| `trend_reversal_bearish_today` | Sticky for session | Event | Trend flipped from up to down today. |

### 52-week & 20-day extremes

| Name | Firing | Kind | Summary |
|------|--------|------|---------|
| `at_52w_high` | Continuous | State | Price is within 0.5% of the 52-week high. |
| `at_52w_low` | Continuous | State | Price is within 0.5% of the 52-week low. |
| `at_20d_high` | Continuous | State | Price is at or above the 20-day high. |
| `at_20d_low` | Continuous | State | Price is at or below the 20-day low. |
| `approaching_52w_high` | Continuous | State | Price is within 5% of the 52-week high. |
| `approaching_52w_low` | Continuous | State | Price is within 5% of the 52-week low. |

### Gaps

| Name | Firing | Kind | Summary |
|------|--------|------|---------|
| `gap_up_3pct` | Sticky for session | Event | Today opened 3%+ above prior close. |
| `gap_down_3pct` | Sticky for session | Event | Today opened 3%+ below prior close. |
| `gap_up_10pct` | Sticky for session | Event | Today opened 10%+ above prior close. |
| `gap_down_10pct` | Sticky for session | Event | Today opened 10%+ below prior close. |

### Bollinger bands

| Name | Firing | Kind | Summary |
|------|--------|------|---------|
| `at_bollinger_upper` | Continuous | State | Price has reached the upper Bollinger band. |
| `at_bollinger_lower` | Continuous | State | Price has reached the lower Bollinger band. |

### Volume

| Name | Firing | Kind | Summary |
|------|--------|------|---------|
| `volume_spike` | Continuous | State | Today’s volume run-rate is meaningfully above average. |
| `volume_unusual_2x` | Continuous | State | Today’s volume run-rate is at least 2× average. |
| `volume_dry_up` | Continuous | State | Today’s volume is unusually low. |

### Momentum

| Name | Firing | Kind | Summary |
|------|--------|------|---------|
| `rsi_overbought` | Continuous | State | RSI(14) is in overbought territory. |
| `rsi_oversold` | Continuous | State | RSI(14) is in oversold territory. |
| `momentum_strong_up` | Continuous | State | Strong upward momentum across multiple measures. |
| `momentum_strong_down` | Continuous | State | Strong downward momentum across multiple measures. |
| `momentum_exhaustion_up` | Continuous | State | Upward momentum showing signs of exhaustion. |
| `momentum_exhaustion_down` | Continuous | State | Downward momentum showing signs of exhaustion. |

### Support & resistance

| Name | Firing | Kind | Summary |
|------|--------|------|---------|
| `at_support` | Continuous | State | Price is testing recent support. |
| `at_resistance` | Continuous | State | Price is testing recent resistance. |
| `breaking_above_20d_high` | Sticky for session | Event | Price just broke above the prior 20-day high. |
| `breaking_below_20d_low` | Sticky for session | Event | Price just broke below the prior 20-day low. |

### Patterns

| Name | Firing | Kind | Summary |
|------|--------|------|---------|
| `consolidation_breakout` | Sticky for session | Event | Breakout from a tight consolidation range. |
| `bounce_off_support` | Sticky for session | Event | Reversal off a recent support level. |
| `pullback` | Continuous | State | Pullback within an established uptrend. |

### Edge-triggered alerts

| Name | Firing | Kind | Summary |
|------|--------|------|---------|
| `breakout` | Sticky for session | Event | New 52-week high posted today. |
| `breakdown` | Sticky for session | Event | New 52-week low posted today. |
| `price_up_3pct` | Sticky for session | Event | Intraday move of 3%+ vs prior close. |
| `price_down_3pct` | Sticky for session | Event | Intraday move of -3% or worse vs prior close. |

### Fundamentals

| Name | Firing | Kind | Summary |
|------|--------|------|---------|
| `small_cap` | Continuous | Classification | Market cap between $300M and $2B. |
| `mid_cap` | Continuous | Classification | Market cap between $2B and $10B. |
| `large_cap` | Continuous | Classification | Market cap between $10B and $200B. |
| `mega_cap` | Continuous | Classification | Market cap above $200B. |
| `value_stock` | Continuous | Classification | Trades at a value-style P/E. |
| `growth_stock` | Continuous | Classification | Trades at a growth-style P/E. |
| `high_dividend_yield` | Continuous | Classification | Dividend yield above 4%. |
| `high_beta` | Continuous | Classification | Beta above 1.5: moves more than the market. |
| `low_float` | Continuous | Classification | Public float under 50 million shares. |

### Corporate events

| Name | Firing | Kind | Summary |
|------|--------|------|---------|
| `earnings_this_week` | Continuous | State | Earnings announcement scheduled in the next 7 days. |
| `earnings_today` | Continuous | State | Earnings announcement scheduled for today. |
| `recently_reported_earnings` | Continuous | State | Reported earnings within the last 3 trading days. |