Tickerapi

TickerAPI Skill

First Run Setup

If the TICKERAPI_KEY environment variable is not set, walk the user through signup before doing anything else:

1. Ask for their email address.
2. Call POST https://api.tickerapi.ai/auth with { "email": "<their email>" }.
3. Tell them to check their inbox for a 6-digit code.
4. Once they provide the code, call POST https://api.tickerapi.ai/auth/verify with { "email": "<their email>", "code": "<their code>" }.
5. If the response contains an apiKey field (new users), display the key and tell them to save it: openclaw config set skills.tickerapi.apiKey <key>. If they already have an account (no apiKey in response), tell them to grab their key from https://tickerapi.ai/dashboard.
6. If the tickerarena skill is also installed, tell them to save the same key there too: openclaw config set skills.tickerarena.apiKey <key> — one account works for both services.

After the first successful request, offer to set up a daily morning scan:

"Want me to scan the market for you every morning before it opens? I'll check for oversold stocks, breakouts, and volume spikes and summarize the best setups. Type /tickerapi cron to set it up."

TickerAPI provides pre-computed, categorical market data designed for LLMs and AI agents. Every response contains verifiable facts — no OHLCV, no raw indicator values, just derived categorical bands (e.g. oversold, not RSI: 24).

• Asset classes: US Stocks, Crypto (tickers require USD suffix, e.g. BTCUSD), ETFs
• Timeframes: daily (default), weekly
• Update frequency: End-of-day (~00:30 UTC)
• Response format: JSON
• Data is factual, not predictive — no scores, no recommendations, no bias

Authentication

All requests require a Bearer token in the Authorization header:

Authorization: Bearer $TICKERAPI_KEY

Unified accounts: TickerAPI and TickerArena share the same account system. One API key (prefixed ta_) works for both services. If a user already has a TickerArena account, their existing key works here — and vice versa.

Errors: 401 = missing/invalid token. 403 = endpoint requires higher tier (response includes upgrade_url).

Base URL

https://api.tickerapi.ai/v1

Common Parameters (all endpoints)

Important: Asset Class Rules

• Stocks get all technical + fundamental data (valuation, growth, earnings, analyst consensus).
• 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.

Categorical Bands Reference

TickerAPI never returns raw indicator values. All data uses categorical bands:

• RSI/Stochastic zones: deep_oversold, oversold, neutral_low, neutral, neutral_high, overbought, deep_overbought
• 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 ratio: extremely_low, low, normal, elevated, high, extremely_high
• Accumulation state: strong_accumulation, accumulation, neutral, distribution, strong_distribution
• Volatility regime: low, normal, elevated, high, extreme
• Support/resistance distance: at_level, very_close, near, moderate, far, very_far
• MACD state: expanding_positive, contracting_positive, expanding_negative, contracting_negative
• Momentum direction: accelerating, steady, decelerating, bullish_reversal, bearish_reversal
• Valuation zone (stocks only): deep_value, undervalued, fair_value, overvalued, extreme_premium
• Growth zone (stocks only): high_growth, moderate_growth, stable, declining, contracting
• Growth direction (stocks only): accelerating, steady, decelerating, contracting
• Earnings proximity (stocks only): imminent, this_week, this_month, next_month, not_soon
• Earnings surprise (stocks only): big_beat, beat, met, missed, big_miss
• Analyst consensus (stocks only): strong_buy, buy, hold, sell, strong_sell
• Analyst consensus direction (stocks only): upgrading, stable, downgrading
• Insider activity zone (stocks only): heavy_buying, moderate_buying, neutral, moderate_selling, heavy_selling
• Insider net direction (stocks only): strong_buying, buying, neutral, selling, strong_selling
• Condition rarity: extremely_rare, very_rare, rare, uncommon, occasional, common

Scan Endpoints

GET /v1/scan/oversold

Find assets in oversold conditions with per-asset historical context. Strategy: mean reversion / bounce.

Parameters:

Free tier fields: ticker, asset_class, rsi_zone, condition_rarity, sector, valuation_zone (stocks only)

Plus adds: stochastic_zone, days_in_oversold, oversold_streaks_count, volume_context (capitulation/elevated/normal/drying_up), volume_ratio_band, trend_context, nearest_support_distance, sector_rsi_zone, earnings_proximity (stocks), growth_zone (stocks), analyst_consensus (stocks)

Pro adds: accumulation_state, historical_median_oversold_days, historical_max_oversold_days, sector_agreement (boolean), sector_oversold_count, sector_total_count

Example:

curl https://api.tickerapi.ai/v1/scan/oversold?asset_class=stock&min_severity=deep_oversold&limit=5 \
  -H "Authorization: Bearer $TICKERAPI_KEY"

GET /v1/scan/breakouts

Assets testing or breaking key levels with volume confirmation. Strategy: momentum / breakout.

Parameters:

Free tier fields: ticker, asset_class, breakout_type (resistance_break/support_break/resistance_test/support_test), condition_rarity, sector

Plus adds: level_price, level_type (horizontal/trendline/ma_derived), level_touch_count, held_count, broke_count, volume_ratio_band, rsi_zone, trend_context, earnings_proximity (stocks), growth_zone (stocks)

Pro adds: squeeze_context (active_squeeze/recent_squeeze_fire/no_squeeze), volume_vs_prior_breakouts (stronger/similar/weaker), sector_breakout_count, sector_total_count

Example:

curl https://api.tickerapi.ai/v1/scan/breakouts?direction=bullish&asset_class=stock&limit=10 \
  -H "Authorization: Bearer $TICKERAPI_KEY"

GET /v1/scan/unusual-volume

Assets at significantly abnormal volume levels. Strategy: volume anomaly detection.

Parameters:

Free tier fields: ticker, asset_class, volume_ratio_band, condition_rarity, sector

Plus adds: volume_percentile, price_direction_on_volume (up/down/flat), consecutive_elevated_days, rsi_zone, trend_context, nearest_level_distance, nearest_level_type (support/resistance), earnings_proximity (stocks), last_earnings_surprise (stocks)

Pro adds: accumulation_state, historical_avg_elevated_streak, sector_elevated_volume_count, sector_total_count

Example:

curl https://api.tickerapi.ai/v1/scan/unusual-volume?min_ratio_band=high&asset_class=crypto&limit=5 \
  -H "Authorization: Bearer $TICKERAPI_KEY"

GET /v1/scan/valuation

Stocks at historically abnormal valuations. Strategy: value / mean reversion. Stocks only — crypto and ETFs have no fundamental valuation data.

Parameters:

Free tier fields: ticker, sector, valuation_zone, valuation_rarity, growth_zone, analyst_consensus

Plus adds: revenue_growth_direction, eps_growth_direction, earnings_proximity, rsi_zone, trend_context, sector_valuation_zone, sector_agreement (boolean)

Pro adds: pe_vs_historical_zone, pe_vs_sector_zone, pb_vs_historical_zone, last_earnings_surprise, analyst_consensus_direction

Example:

curl https://api.tickerapi.ai/v1/scan/valuation?direction=undervalued&min_severity=deep_value&limit=10 \
  -H "Authorization: Bearer $TICKERAPI_KEY"

GET /v1/scan/insider-activity

Stocks with significant insider buying or selling (SEC Form 4 filings). Stocks only.

Parameters:

Free tier fields: ticker, sector, insider_activity_zone, net_direction

Plus adds: quarter, buy_count, sell_count, shares_bought, shares_sold, rsi_zone, trend_context, volume_ratio_band, valuation_zone, earnings_proximity

Example:

curl https://api.tickerapi.ai/v1/scan/insider-activity?direction=buying&sort_by=zone_severity&limit=10 \
  -H "Authorization: Bearer $TICKERAPI_KEY"

Asset Endpoints

GET /v1/summary/{ticker}

Comprehensive factual snapshot for a single asset. Every field is a verifiable fact.

Parameters:

Tier access: Free gets core technical (trend, momentum, extremes, volatility, volume). Plus adds support/resistance and basic fundamentals. Pro adds sector_context and advanced fundamentals.

Response sections:

• trend — direction, duration_days, ma_alignment, distance_from_ma_band (ma_20, ma_50, ma_200), volume_confirmation (confirmed/diverging/neutral)
• momentum — rsi_zone, stochastic_zone, rsi_stochastic_agreement, macd_state, direction, divergence_detected, divergence_type (bullish_divergence/bearish_divergence/null)
• extremes — condition (deep_oversold through deep_overbought or normal), days_in_condition, historical_median_duration, historical_max_duration, streak_count_1yr, condition_percentile, condition_rarity
• volatility — regime, regime_trend (compressing/stable/expanding), squeeze_active, squeeze_days, historical_avg_squeeze_duration
• volume — ratio_band, percentile, accumulation_state, climax_detected, climax_type (buying_climax/selling_climax/null)
• support_level / resistance_level (Plus+) — level_price, status (holding/testing/broke), distance_band, touch_count, held_count, broke_count, last_tested_days_ago, type (horizontal/ma_derived), volume_at_tests_band
• range_position — lower_third, mid_range, or upper_third
• sector_context (Pro) — sector_rsi_zone, sector_trend, asset_vs_sector_rsi, asset_vs_sector_trend, sector_oversold_count, sector_total_count
• fundamentals (stocks only, Plus+) — Plus: valuation_zone, growth_zone, earnings_proximity, analyst_consensus. Pro adds: valuation_percentile, pe_vs_historical_zone, pe_vs_sector_zone, pb_vs_historical_zone, revenue_growth_direction, eps_growth_direction, last_earnings_surprise, analyst_consensus_direction

Example:

curl https://api.tickerapi.ai/v1/summary/NVDA \
  -H "Authorization: Bearer $TICKERAPI_KEY"

GET /v1/compare

Side-by-side factual comparison of 2–10 assets. Plus: up to 5 tickers. Pro: up to 10 tickers.

Parameters:

Response structure:

• summaries — Object keyed by ticker, each a full summary object. Missing tickers return null.
• comparison — Side-by-side fields: rsi_zones, trend_directions, volume_ratio_bands, extremes_conditions, range_positions, condition_percentiles, valuation_zones (stocks), growth_zones (stocks), analyst_consensuses (stocks)
• comparison.divergences — Array of objects with type (e.g. rsi_divergence, trend_divergence, valuation_divergence) and description (human-readable)
• Envelope: tickers_requested, tickers_found, data_status

Example:

curl "https://api.tickerapi.ai/v1/compare?tickers=NVDA,AMD,INTC" \
  -H "Authorization: Bearer $TICKERAPI_KEY"

POST /v1/watchlist

Batch check multiple tickers with compact snapshots. Plus: up to 10 tickers. Pro: up to 50 tickers.

Request body (JSON):

{
  "tickers": ["AAPL", "MSFT", "BTCUSD", "SPY"],
  "timeframe": "daily"
}

Response fields per item: ticker, asset_class, 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), earnings_proximity (stocks), analyst_consensus (stocks), notable_changes (array of day-over-day changes like "entered deep_value", "analyst downgraded")

Tickers not found return "status": "not_found".

Example:

curl -X POST https://api.tickerapi.ai/v1/watchlist \
  -H "Authorization: Bearer $TICKERAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tickers": ["AAPL", "TSLA", "BTCUSD"], "timeframe": "daily"}'

GET /v1/assets

Full list of supported tickers with metadata. Available on all tiers. Does not count against request limits.

Response: assets array (each with ticker, name, asset_class, sector, exchange), total_count, asset_classes (breakdown by stock/crypto/etf counts).

Example:

curl https://api.tickerapi.ai/v1/assets \
  -H "Authorization: Bearer $TICKERAPI_KEY"

Response Envelope (scan endpoints)

All scan endpoints return:

{
  "matches": [...],
  "total_scanned": 648,
  "match_count": 12,
  "data_status": "eod"
}

Errors

When you get a 403, tell the user which tier they need and share the upgrade URL from the response.

Rate Limits

• /v1/assets never counts against limits
• HTTP 304 (conditional/cached) responses do not count
• Use ETag / If-None-Match headers for conditional requests
• Rate limit headers: X-Requests-Remaining, X-Request-Reset, etc.

Caching

All data is pre-computed after market close. Daily timeframe refreshes ~5:15 PM ET. Weekly refreshes after Friday close. Responses are edge-cached with Cache-Control and ETag headers.