# TickerDB — Complete API Documentation

> Pre-computed, categorical market intelligence for LLMs and AI agents. 12,000+ assets. 5 years of history. Stocks, crypto, and ETFs.

TickerDB provides pre-computed, categorical market data designed for LLMs and AI agents. Every response contains verifiable facts expressed as categorical bands (e.g. "oversold", not "RSI: 24"). No OHLCV parsing, no raw indicator values, no infrastructure required.

## Base URL

https://api.tickerdb.com/v1

## Coverage

- Asset Classes: US Stocks, Crypto (tickers require USD suffix: BTCUSD, ETHUSD), ETFs
- Total Assets: 12,000+
- Timeframes: daily (default), weekly
- Update Frequency: End-of-day (EOD), refreshes daily around 00:30 UTC
- Response Format: JSON
- Data Philosophy: Factual, not predictive. No scores, no recommendations, no bias.

## Asset Class Rules

- Stocks get all technical + fundamental data (valuation, growth, earnings, analyst consensus, insider activity, sector context).
- Crypto and ETFs get technical data only. Fundamental fields are omitted entirely (keys absent, not null).
- Crypto tickers MUST include USD suffix: BTCUSD, ETHUSD, SOLUSD. Using just BTC returns an error.

---

## Authentication

All API requests require a Bearer token in the Authorization header:

    Authorization: Bearer YOUR_API_KEY

Error responses:
- 401 Unauthorized: Missing or invalid Bearer token
- 403 Forbidden: Endpoint requires higher tier (response includes upgrade_url)

---

## Architecture: 4 Core Endpoints

TickerDB uses 4 core endpoints. There are no separate scan/screener endpoints — the generic search endpoint replaces all of them.

| Endpoint | Purpose | Credits |
|----------|---------|---------|
| GET /v1/summary/{ticker} | Single-asset intelligence (snapshot, history, events) | 1 (2 with cross-asset correlation) |
| GET /v1/search | Find assets by categorical state with arbitrary filters | 1 |
| GET /v1/schema/fields | Discover all queryable fields, operators, and valid values | 0 (always free) |
| /v1/watchlist (GET/POST/DELETE) | Persistent server-side watchlist with live data and change tracking | 1 |

---

## Endpoint 1: GET /v1/summary/{ticker}

Unified endpoint for single-asset intelligence. Supports 4 modes depending on which parameters are provided:

1. **Snapshot** (default) — Current categorical state for a ticker
2. **Historical snapshot** — Pass `date` for a point-in-time snapshot
3. **Historical series** — Pass `start`/`end` for a date range of snapshots
4. **Events** — Pass `field` (and optionally `band`) to get band transition history with aftermath performance

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| ticker | string | — | Required. Path param (e.g. /v1/summary/AAPL) |
| timeframe | string | daily | daily or weekly |
| date | string | latest | Point-in-time snapshot (YYYY-MM-DD). Plus: 2 years. Pro: 5 years. |
| start | string | — | Range start date (YYYY-MM-DD). Use with end for historical series. |
| end | string | latest | Range end date (YYYY-MM-DD). Use with start. |
| field | string | — | Band field name for events mode (e.g. rsi_zone, trend_direction, valuation_zone). Switches to events mode. |
| band | string | all | Filter events to a specific band value (e.g. deep_oversold). Only with field. |
| limit | int | 10 | Max event results (1-100). Only with field. |
| before | string | — | Return events before this date (YYYY-MM-DD). Only with field. |
| after | string | — | Return events after this date (YYYY-MM-DD). Only with field. |
| context_ticker | string | — | Cross-asset correlation: second ticker (e.g. SPY). Requires context_field + context_band. Plus/Pro only. 2 credits. |
| context_field | string | — | Band field to check on context ticker (e.g. trend_direction). |
| context_band | string | — | Required band value on context ticker (e.g. downtrend). |

### Tier Access

- Free: Core technical (performance, trend, momentum, extremes, volatility, volume). 3-month history. Events: 90-day lookback, no aftermath.
- Plus: + support/resistance, basic fundamentals, band stability _meta objects, aftermath data on events, cross-asset correlation. 2-year history/lookback.
- Pro: + sector_context, advanced fundamentals. 5-year history/lookback.

### Response Sections (Snapshot/Historical Modes)

**performance** — Candle performance vs. asset's own historical return distribution.
Values: sharp_decline | moderate_decline | slight_decline | flat | slight_gain | moderate_gain | sharp_gain
Per-ticker percentile-based.

**trend:**
- direction: strong_uptrend | uptrend | neutral | downtrend | strong_downtrend
- duration_days: integer
- ma_alignment: aligned_bullish | mixed | aligned_bearish
- distance_from_ma_band: object with ma_20, ma_50, ma_200 each being far_above | moderately_above | slightly_above | slightly_below | moderately_below | far_below
- volume_confirmation: confirmed | diverging | neutral

**momentum:**
- rsi_zone: deep_oversold | oversold | neutral_low | neutral | neutral_high | overbought | deep_overbought
- stochastic_zone: same scale as rsi_zone
- rsi_stochastic_agreement: boolean
- macd_state: expanding_positive | contracting_positive | expanding_negative | contracting_negative
- direction: accelerating | steady | decelerating | bullish_reversal | bearish_reversal
- divergence_detected: boolean
- divergence_type: bullish_divergence | bearish_divergence | null

**extremes:**
- condition: deep_oversold | oversold | overbought | deep_overbought | normal
- days_in_condition: integer
- historical_median_duration: integer
- historical_max_duration: integer
- occurrences_1yr: integer
- condition_percentile: 0-100
- condition_rarity: extremely_rare | very_rare | rare | uncommon | occasional | common

**volatility:**
- regime: low | normal | above_normal | high | extreme
- regime_trend: compressing | stable | expanding
- squeeze_active: boolean
- squeeze_days: integer
- historical_avg_squeeze_duration: integer

**volume:**
- ratio_band: extremely_low | low | normal | above_average | high | extremely_high
- percentile: 0-100
- accumulation_state: strong_accumulation | accumulation | neutral | distribution | strong_distribution
- climax_detected: boolean
- climax_type: buying_climax | selling_climax | null

**support_level / resistance_level** (Plus+, null if not found):
- level_price: number
- status: intact | approaching | breached
- distance_band: at_level | very_close | near | moderate | far | very_far
- touch_count, held_count, broke_count: integers
- consecutive_closes_beyond: integer
- last_tested_days_ago: integer
- type: horizontal | ma_derived
- volume_at_tests_band: string

**range_position:** lower_third | mid_range | upper_third

**sector_context** (Pro only, stocks only):
- sector_rsi_zone, sector_trend
- asset_vs_sector_rsi: weaker | aligned | stronger
- asset_vs_sector_trend: weaker | aligned | stronger
- sector_oversold_count, sector_total_count

**fundamentals** (stocks only, omitted for crypto/ETFs):

Plus tier:
- valuation_zone: deep_value | undervalued | fair_value | overvalued | deeply_overvalued
- growth_zone: high_growth | moderate_growth | stable | slowing | shrinking
- earnings_proximity: within_days | this_week | this_month | next_month | not_soon
- analyst_consensus: strong_buy | buy | hold | sell | strong_sell

Pro tier adds:
- valuation_percentile, pe_vs_historical_zone, pe_vs_sector_zone, pb_vs_historical_zone
- revenue_growth_direction, eps_growth_direction: accelerating | steady | decelerating | deteriorating
- last_earnings_surprise: big_beat | beat | met | missed | big_miss
- analyst_consensus_direction: upgrading | stable | downgrading

### Band Stability Metadata (Plus/Pro only)

Each categorical band field (e.g. rsi_zone, trend_direction, volatility_regime) has a sibling _meta object (e.g. rsi_zone_meta) that describes how stable the current value is.

_meta fields:
- stability: fresh | holding | established | volatile
- periods_in_current_state: integer (days for daily, weeks for weekly)
- flips_recent: integer (state changes in the lookback window)
- flips_lookback: string (e.g. "30d" or "12w")
- timeframe: daily or weekly

Stability meanings:
- fresh: Band just changed (1 period). May flip back.
- holding: Persisted 2-4 periods. Gaining confidence.
- established: Held 5+ periods. High confidence.
- volatile: Flipped frequently (3+ flips in lookback). Unstable regardless of current duration.

### Events Mode Response

When field is provided, the endpoint returns band transition events instead of a snapshot.

Response envelope: ticker, field, timeframe, events (array), total_occurrences, query_range

Each event object:
- date: YYYY-MM-DD
- band: current band value
- prev_band: previous band value
- duration_days: integer (null if still active). duration_weeks for weekly timeframe.
- stability_at_entry: stability label at time of event (Plus/Pro)
- flips_recent_at_entry: integer (Plus/Pro)
- flips_lookback: string (Plus/Pro)
- aftermath: object with performance at lookahead windows (null for Free tier or recent events)

When cross-asset correlation is used, also includes:
- context: object with ticker, field, and band describing the filter applied

Aftermath windows:
- Daily: 5d, 10d, 20d, 50d, 100d
- Weekly: 2w, 4w, 8w, 12w, 16w

Aftermath performance bands (per-ticker percentile-based):
- sharp_decline (Bottom 5%), moderate_decline (5th-20th), slight_decline (20th-40th), flat (40th-60th), slight_gain (60th-80th), moderate_gain (80th-95th), sharp_gain (Top 5%)

### Supported Event Fields

Technical (Free): rsi_zone, trend_direction, ma_alignment, volume_ratio_band, accumulation_state, volatility_regime, macd_state, support_status, resistance_status
Basic Fundamentals (Plus): valuation_zone, growth_zone, earnings_proximity, analyst_consensus
Advanced Fundamentals (Pro): pe_vs_historical, pe_vs_sector, revenue_growth_direction, eps_growth_direction, earnings_surprise, analyst_consensus_direction, insider_activity_zone, net_direction

### Examples

Snapshot (current state):
    curl "https://api.tickerdb.com/v1/summary/NVDA" \
      -H "Authorization: Bearer $TICKERDB_KEY"

Historical snapshot:
    curl "https://api.tickerdb.com/v1/summary/AAPL?date=2026-01-15" \
      -H "Authorization: Bearer $TICKERDB_KEY"

Historical series:
    curl "https://api.tickerdb.com/v1/summary/AAPL?start=2026-01-01&end=2026-03-31" \
      -H "Authorization: Bearer $TICKERDB_KEY"

Events (band transition history):
    curl "https://api.tickerdb.com/v1/summary/AAPL?field=rsi_zone&band=deep_oversold&limit=5" \
      -H "Authorization: Bearer $TICKERDB_KEY"

Events with cross-asset correlation:
    curl "https://api.tickerdb.com/v1/summary/AAPL?field=rsi_zone&band=deep_oversold&context_ticker=SPY&context_field=trend_direction&context_band=downtrend&limit=5" \
      -H "Authorization: Bearer $TICKERDB_KEY"

---

## Endpoint 2: GET /v1/search

Search for assets matching categorical filter criteria. Replaces all previous scan endpoints (oversold, overbought, breakouts, unusual-volume, valuation, insider-activity) with a single generic query interface against the flat TimescaleDB schema.

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| filters | string | — | Required. JSON array of {field, op, value} filter objects. |
| timeframe | string | daily | daily or weekly |
| date | string | latest | Historical date (YYYY-MM-DD). Tier date limits apply. |
| sort_by | string | ticker | Column to sort by (must be a valid field name) |
| sort_direction | string | desc | asc or desc |
| limit | int | 20 | Max results (1-100) |
| fields | string | core subset | Columns to return. JSON array or comma-separated. Default if omitted: ticker, asset_class, sector, performance, trend_direction, momentum_rsi_zone, extremes_condition, extremes_condition_rarity, volatility_regime, volume_ratio_band, fundamentals_valuation_zone, range_position. Use ["*"] for all 120+ fields. ticker is always included. Invalid fields return 400 pointing to /v1/schema/fields. |

### Filter Objects

Each filter is a JSON object with three keys:

    { "field": "<column_name>", "op": "<operator>", "value": "<value>" }

### Operators

| Operator | Description | Works With |
|----------|-------------|------------|
| eq | Equals | text, numeric, boolean |
| neq | Not equals | text, numeric, boolean |
| in | Value is in array | text, numeric |
| gt | Greater than | numeric |
| gte | Greater than or equal | numeric |
| lt | Less than | numeric |
| lte | Less than or equal | numeric |

Boolean fields only support eq and neq operators.

### Tier-Based Filter Limits

| Tier | Max Filters Per Query |
|------|----------------------|
| Free | 3 |
| Plus | 5 |
| Pro | 10 |

Exceeding the filter limit returns 403 tier_restricted.

### Tier-Based Field Access

- Free: Core technical fields (trend_*, momentum_*, extremes_*, volatility_*, volume_*). No stability/meta columns.
- Plus: + support_*, resistance_*, range_*, basic fundamentals (valuation_zone, growth_zone, earnings_proximity, analyst_consensus).
- Pro: All fields including advanced fundamentals, insider_*, sector_*.

Metadata fields (ticker, asset_class, sector, data_status, performance) are always available on all tiers.

### Field Categories

Fields use a flat naming convention with category prefixes: trend_, momentum_, extremes_, volatility_, volume_, support_, resistance_, fundamentals_, insider_, sector_. Use GET /v1/schema/fields for the full list.

### Filter Examples

Find all deep oversold assets:
    [{"field": "momentum_rsi_zone", "op": "eq", "value": "deep_oversold"}]

Find tech stocks in strong uptrend with high volume:
    [{"field": "sector", "op": "eq", "value": "Technology"}, {"field": "trend_direction", "op": "in", "value": ["uptrend", "strong_uptrend"]}, {"field": "volume_ratio_band", "op": "eq", "value": "high"}]

Find stocks with insider buying and undervalued:
    [{"field": "insider_zone", "op": "eq", "value": "heavy_buying"}, {"field": "fundamentals_valuation_zone", "op": "eq", "value": "undervalued"}]

Find assets with volatility squeeze lasting more than 10 days:
    [{"field": "volatility_squeeze_active", "op": "eq", "value": true}, {"field": "volatility_squeeze_days", "op": "gt", "value": 10}]

### Response

    {
      "timeframe": "daily",
      "date": null,
      "filter_count": 1,
      "result_count": 5,
      "results": [
        { "ticker": "XYZ", "asset_class": "stock", "momentum_rsi_zone": "deep_oversold", ... }
      ]
    }

Each result is a flat snapshot row filtered to include only fields accessible at the caller's tier. When the `fields` parameter is used, the response includes a top-level `fields` array listing the column names returned.

### Examples

Return only specific fields (dramatically reduces token usage — ~10K tokens to ~500):
    curl "https://api.tickerdb.com/v1/search?filters=%5B%7B%22field%22%3A%22momentum_rsi_zone%22%2C%22op%22%3A%22eq%22%2C%22value%22%3A%22deep_oversold%22%7D%5D&fields=%5B%22ticker%22%2C%22sector%22%2C%22momentum_rsi_zone%22%5D" \
      -H "Authorization: Bearer $TICKERDB_KEY"

### Example

    curl "https://api.tickerdb.com/v1/search?filters=%5B%7B%22field%22%3A%22momentum_rsi_zone%22%2C%22op%22%3A%22eq%22%2C%22value%22%3A%22deep_oversold%22%7D%5D" \
      -H "Authorization: Bearer $TICKERDB_KEY"

Sort by valuation percentile (cheapest first):
    curl "https://api.tickerdb.com/v1/search?filters=%5B%7B%22field%22%3A%22fundamentals_valuation_zone%22%2C%22op%22%3A%22in%22%2C%22value%22%3A%5B%22deep_value%22%2C%22undervalued%22%5D%7D%5D&sort_by=fundamentals_valuation_percentile&sort_direction=asc" \
      -H "Authorization: Bearer $TICKERDB_KEY"

---

## Endpoint 3: GET /v1/schema/fields

Discover all queryable fields, their types, valid values, and categories. Use this to understand what filters are available for the search endpoint. Always free — 0 credits, no rate limiting, available on all tiers.

### Response

    {
      "total_fields": 120,
      "categories": ["metadata", "trend", "momentum", "extremes", "volatility", "volume", "support", "resistance", "range", "fundamentals", "insider", "sector_context"],
      "operators": ["eq", "neq", "in", "gt", "gte", "lt", "lte"],
      "fields": [
        {
          "name": "momentum_rsi_zone",
          "type": "text",
          "category": "momentum",
          "values": ["deep_oversold", "oversold", "neutral_low", "neutral", "neutral_high", "overbought", "deep_overbought"],
          "description": "RSI categorical zone"
        },
        ...
      ]
    }

Each field includes:
- name: The column name to use in search filters
- type: text, integer, numeric, boolean, or bigint
- category: Grouping (metadata, trend, momentum, etc.)
- values: Array of allowed values (for enum-type text fields). Absent for open-ended fields.
- description: Human-readable description

### Example

    curl "https://api.tickerdb.com/v1/schema/fields" \
      -H "Authorization: Bearer $TICKERDB_KEY"

---

## Endpoint 4: Watchlist — /v1/watchlist

The watchlist is a persistent, server-side list of tickers. Users save tickers once and retrieve live data on demand. The saved watchlist is also what webhooks monitor — watchlist.changes events fire for tickers on the user's saved watchlist.

### Tier Limits

| Tier | Max Tickers |
|------|-------------|
| Free | 5 |
| Plus | 50 |
| Pro | 100 |

### GET /v1/watchlist — Retrieve saved watchlist with live data

Returns compact live snapshots for all saved tickers.

Query params: timeframe (optional, daily or weekly, default daily)

Response fields per ticker:
- ticker, asset_class, performance
- trend_direction, rsi_zone, volume_ratio_band
- extremes_condition, days_in_extreme, condition_rarity
- squeeze_active
- support_level_price, support_level_distance
- resistance_level_price, resistance_level_distance
- valuation_zone (stocks only), earnings_proximity (stocks only), analyst_consensus (stocks only)
- notable_changes: array of change descriptions

Envelope: watchlist (array), tickers_saved, tickers_found, watchlist_limit, data_status

Tickers with no available data return {"ticker": "XXX", "status": "not_found"}. Empty watchlist returns {"watchlist": [], "tickers_saved": 0, ...}.

Example:
    curl "https://api.tickerdb.com/v1/watchlist" \
      -H "Authorization: Bearer $TICKERDB_KEY"

### POST /v1/watchlist — Add tickers to saved watchlist

Add one or more tickers. Duplicates are skipped silently. Only supported tickers can be added — all tickers are validated against the assets database.

Request body:
    { "tickers": ["AAPL", "MSFT", "BTCUSD"] }

Response:
    { "added": ["AAPL", "MSFT", "BTCUSD"], "already_saved": [], "watchlist_count": 3, "watchlist_limit": 50 }

Errors:
- 400 invalid_tickers: Ticker not recognized (includes invalid_tickers array)
- 400 watchlist_limit: Adding would exceed tier limit (includes upgrade_url)

Example:
    curl -X POST "https://api.tickerdb.com/v1/watchlist" \
      -H "Authorization: Bearer $TICKERDB_KEY" \
      -H "Content-Type: application/json" \
      -d '{"tickers": ["AAPL", "TSLA", "BTCUSD"]}'

### DELETE /v1/watchlist — Remove tickers from saved watchlist

Remove one or more tickers.

Request body:
    { "tickers": ["MSFT"] }

Response:
    { "removed": ["MSFT"], "watchlist_count": 2 }

Example:
    curl -X DELETE "https://api.tickerdb.com/v1/watchlist" \
      -H "Authorization: Bearer $TICKERDB_KEY" \
      -H "Content-Type: application/json" \
      -d '{"tickers": ["MSFT"]}'

### GET /v1/watchlist/changes — Field-level state changes

Returns structured, field-level diffs for saved watchlist tickers since the last pipeline run. Daily shows day-over-day changes, weekly shows week-over-week changes. Available on all tiers (including Free). Returns the same data format that webhooks deliver, but pull-based.

Parameters: timeframe (optional, daily or weekly, default daily)

Fields tracked: rsi_zone, trend_direction, volume_ratio_band, squeeze_active, extreme_condition, breakout_type, fundamentals.valuation_zone, fundamentals.analyst_consensus, fundamentals.earnings_proximity, fundamentals.last_earnings_surprise, fundamentals.growth_zone

Response:
    {
      "timeframe": "daily",
      "run_date": "2026-03-28",
      "changes": {
        "AAPL": [
          {"field": "rsi_zone", "from": "neutral", "to": "oversold", "stability": "fresh", "periods_in_current_state": 1, "flips_recent": 2, "flips_lookback": "30d"}
        ]
      },
      "tickers_checked": 5,
      "tickers_changed": 1
    }

Only tickers with at least one change appear in changes. Plus/Pro users get stability metadata on each change object (stability, periods_in_current_state, flips_recent, flips_lookback). Free tier gets field, from, and to only.

Example:
    curl "https://api.tickerdb.com/v1/watchlist/changes?timeframe=daily" \
      -H "Authorization: Bearer $TICKERDB_KEY"

---

## Supporting Endpoints

### Webhooks — /v1/webhooks

Register webhook URLs to receive push notifications after each pipeline run instead of polling.

Tier access: Free (no webhooks), Plus (1 URL), Pro (1 URL), Commercial Plus (3 URLs), Commercial Pro (3 URLs).

Each webhook delivery counts as 1 API request against daily allowance.

#### Event Types

| Event | Description | Default |
|-------|-------------|---------|
| watchlist.changes | Structured field-level diffs for tickers on the saved watchlist. Only fires when at least one field changed. | Enabled on creation |
| data.ready | Notification that fresh data has been computed and is available. | Opt-in |

#### POST /v1/webhooks — Register a webhook

Request body: { "url": "https://example.com/webhook", "events": { "watchlist.changes": true, "data.ready": true } }

- url (required): Must be HTTPS
- events (optional): Defaults to {"watchlist.changes": true}

Response (201): { id, url, secret, events, active, created_at }

The secret is returned ONLY on creation. Save it immediately for HMAC-SHA256 signature verification.

#### GET /v1/webhooks — List webhooks

Response: { webhooks (array of { id, url, events, active, created_at, updated_at }), webhook_count, webhook_limit }

Secret is never included in GET responses.

#### PUT /v1/webhooks — Update a webhook

Request body: { "id": "...", "events": {...}, "active": false }

#### DELETE /v1/webhooks — Remove a webhook

Request body: { "id": "..." }

Response: { deleted, webhook_count }

#### Webhook Delivery Headers

- X-Webhook-Signature: HMAC-SHA256 hex digest of raw request body, signed with webhook secret
- X-Webhook-Event: Event type (watchlist.changes or data.ready)
- Content-Type: application/json
- User-Agent: TickerDB-Webhook/1.0

#### Signature Verification

Always verify the X-Webhook-Signature before processing payloads. Compute HMAC-SHA256 of the raw request body using the webhook secret, and compare to the header value.

### GET /v1/account

Check plan tier, rate limits, and current API usage. Does not count against request limits.

Response: plan (tier name), usage (current period request counts), limits (daily/hourly caps), watchlist_limit, webhook_limit.

Example:
    curl "https://api.tickerdb.com/v1/account" \
      -H "Authorization: Bearer $TICKERDB_KEY"

---

## Categorical Bands Reference

TickerDB never returns raw indicator values. All data uses categorical bands. This is the complete vocabulary.

### Momentum & Oscillators

RSI Zones: deep_oversold, oversold, neutral_low, neutral, neutral_high, overbought, deep_overbought
Stochastic Zones: deep_oversold, oversold, neutral_low, neutral, neutral_high, overbought, deep_overbought
MACD State: expanding_positive, contracting_positive, expanding_negative, contracting_negative
Momentum Direction: accelerating, steady, decelerating, bullish_reversal, bearish_reversal
Extremes Condition: deep_oversold, oversold, overbought, deep_overbought, normal

### Trend

Trend Direction: strong_uptrend, uptrend, neutral, downtrend, strong_downtrend
MA Alignment: aligned_bullish, mixed, aligned_bearish
MA Distance: far_above, moderately_above, slightly_above, slightly_below, moderately_below, far_below
Volume Confirmation: confirmed, diverging, neutral

### Volume

Volume Ratio: extremely_low, low, normal, above_average, high, extremely_high
Accumulation State: strong_accumulation, accumulation, neutral, distribution, strong_distribution
Price Direction on Volume: up, down, flat

### Volatility

Volatility Regime: low, normal, above_normal, high, extreme
Volatility Trend: compressing, stable, expanding

### Support & Resistance

Distance Band: at_level, very_close, near, moderate, far, very_far
Status: intact, approaching, breached
Level Type: horizontal, ma_derived

### Range

Range Position: lower_third, mid_range, upper_third

### Performance

Performance: sharp_decline, moderate_decline, slight_decline, flat, slight_gain, moderate_gain, sharp_gain
(Per-ticker percentile-based. Thresholds derived from each asset's own historical return distribution.)

### Condition & Rarity

Condition Rarity: extremely_rare, very_rare, rare, uncommon, occasional, common

### Fundamentals (Stocks Only)

Valuation Zone: deep_value, undervalued, fair_value, overvalued, deeply_overvalued
P/E vs. Historical: historic_low, below_average, average, above_average, historic_high
P/E vs. Sector: deep_discount, discount, aligned, premium, deep_premium
Growth Zone: high_growth, moderate_growth, stable, slowing, shrinking
Growth Direction: accelerating, steady, decelerating, deteriorating
Earnings Proximity: within_days, this_week, this_month, next_month, not_soon
Earnings Surprise: big_beat, beat, met, missed, big_miss
Analyst Consensus: strong_buy, buy, hold, sell, strong_sell
Analyst Consensus Direction: upgrading, stable, downgrading

### Insider Activity (Stocks Only)

Insider Activity Zone: heavy_buying, moderate_buying, neutral, moderate_selling, heavy_selling, no_activity
Net Direction (Insider): strong_buying, buying, neutral, selling, strong_selling

### Other

Market Cap Tier: nano, micro, small, mid, large, mega, ultra_mega

### Band Stability (Plus/Pro Only)

Stability: fresh, holding, established, volatile

---

## Rate Limits

### Daily Limits

| Tier | Daily Requests |
|------|----------------|
| Free | 100 |
| Plus (Individual) | 50,000 |
| Pro (Individual) | 100,000 |
| Plus (Commercial) | 250,000 |
| Pro (Commercial) | 500,000 |

### Hourly Limits

| Tier | Hourly Requests |
|------|-----------------|
| Free | 50 |
| Plus (Individual) | 5,000 |
| Pro (Individual) | 10,000 |
| Plus (Commercial) | 25,000 |
| Pro (Commercial) | 50,000 |

### Counting Rules

- Each API call = 1 credit (regardless of result count)
- Cross-asset correlation on summary events = 2 credits
- /v1/schema/fields and /v1/account never count
- HTTP 304 (conditional/cached) responses do not count
- Each webhook delivery counts as 1 credit
- Daily limits reset at midnight UTC
- Hourly limits reset at top of each UTC hour

### Rate Limit Headers

Every response includes:
- X-Request-Limit, X-Requests-Used, X-Requests-Remaining, X-Request-Reset
- X-Hourly-Request-Limit, X-Hourly-Requests-Used, X-Hourly-Requests-Remaining, X-Hourly-Request-Reset

Rate limit exceeded: HTTP 429, error type "rate_limit_exceeded", includes upgrade_url and reset time.

---

## Pricing Tiers

| Tier | Price | Daily Requests | Hourly Requests | History | Watchlist | Webhooks | Search Filters |
|------|-------|----------------|-----------------|---------|-----------|----------|----------------|
| Free | $0/mo | 100 | 50 | 3 months | 5 tickers | None | 3 per query |
| Plus (Individual) | $25/mo | 50,000 | 5,000 | 2 years | 50 tickers | 1 URL | 5 per query |
| Pro (Individual) | $50/mo | 100,000 | 10,000 | 5 years | 100 tickers | 1 URL | 10 per query |
| Plus (Commercial) | $100/mo | 250,000 | 25,000 | 2 years | 200 tickers | 3 URLs | 5 per query |
| Pro (Commercial) | $200/mo | 500,000 | 50,000 | 5 years | 400 tickers | 3 URLs | 10 per query |

### What Each Tier Unlocks

Free:
- Core technical data (trend, momentum, extremes, volatility, volume)
- No stability metadata, no fundamentals, no support/resistance
- 3-month historical lookback
- Events: 90-day lookback, no aftermath, no cross-asset correlation

Plus:
- Everything in Free, plus:
- Support/resistance levels
- Basic fundamentals (valuation_zone, growth_zone, earnings_proximity, analyst_consensus)
- Band stability metadata (_meta sibling objects)
- Event aftermath data and cross-asset correlation
- 2-year historical lookback

Pro:
- Everything in Plus, plus:
- Sector context (sector_rsi_zone, asset_vs_sector_rsi, etc.)
- Advanced fundamentals (pe_vs_historical_zone, pe_vs_sector_zone, analyst_consensus_direction, etc.)
- 5-year historical lookback

Commercial tiers (Plus/Pro):
- Higher request limits (250k-500k/day)
- Larger watchlists (200-400 tickers)
- More webhook URLs (3)
- For products that serve end users

Beta: All users get Pro-tier access free during beta. No credit card required.

---

## Error Codes

All errors return: { "error": { "type": "...", "message": "..." } }

| Status | Type | Description |
|--------|------|-------------|
| 400 | invalid_parameter | Bad ticker, timeframe, filter, or other parameter |
| 401 | unauthorized | Missing or invalid Bearer token |
| 403 | tier_restricted | Endpoint or feature requires higher tier (includes upgrade_url) |
| 404 | not_found | Ticker not in database |
| 429 | rate_limit_exceeded | Daily or hourly limit hit (includes upgrade_url and reset time) |
| 500 | internal_error | Server error |
| 503 | data_unavailable | Data feed temporarily down |

---

## Caching

- Daily timeframe: Refreshes after market close (~5:15 PM ET)
- Weekly timeframe: Refreshes after Friday close
- Cache-Control and ETag headers included on all responses
- 304 Not Modified responses do not count against rate limits
- Use ETag with If-None-Match header for conditional requests

---

## MCP Integration

TickerDB exposes all endpoints as MCP tools for use with Claude Desktop, Cursor, Windsurf, and any MCP-compatible client. Install via npm: @anthropic/tickerdb-mcp.

## SDKs

- Python: tickerdb-python
- JavaScript/TypeScript: tickerdb-js
- Go: tickerdb-go