Skill

Query TickerAPI.ai for pre-computed categorical market intelligence — scan for oversold stocks, breakouts, unusual volume, valuation extremes, and insider activity. Get single-asset summaries, compare multiple tickers, or monitor a watchlist. Use when the user asks about market conditions, stock signals, what's oversold or breaking out, asset comparisons, portfolio checks, or any derived indicator data. Covers US stocks, crypto, and ETFs with daily/weekly timeframes. Pairs with tickerarena for automated trade execution.

# 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](https://tickerarena.com) 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)

| Parameter | Type | Description |
|-----------|------|-------------|
| `ticker` | string | Asset symbol, uppercase. Crypto needs `USD` suffix (e.g. `BTCUSD`). Required on per-asset endpoints. |
| `timeframe` | string | `daily` or `weekly`. Default: `daily`. |
| `asset_class` | string | `stock`, `crypto`, `etf`, or `all`. Auto-detected on per-asset endpoints. |
| `date` | string | ISO 8601 (`YYYY-MM-DD`) for historical snapshot. Plus: 30 days. Pro: full backfill. |
| `limit` | integer | Max results. Default: 20, max: 50. Scan endpoints only. |

## 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:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `asset_class` | string | `all` | `stock`, `crypto`, `etf`, or `all` |
| `sector` | string | none | Filter by sector (case-insensitive), e.g. `Semiconductors` |
| `min_severity` | string | `oversold` | `oversold` or `deep_oversold` |
| `sort_by` | string | `severity` | `severity`, `days_oversold`, or `condition_percentile` |
| `limit` | integer | 20 | Max results, max 50 |
| `timeframe` | string | `daily` | `daily` or `weekly` |
| `date` | string | latest | Historical snapshot (Plus+) |

**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:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `asset_class` | string | `all` | `stock`, `crypto`, `etf`, or `all` |
| `sector` | string | none | Filter by sector (case-insensitive) |
| `direction` | string | `all` | `bullish` (resistance), `bearish` (support), or `all` |
| `sort_by` | string | `volume_ratio` | `volume_ratio`, `level_strength`, or `condition_percentile` |
| `limit` | integer | 20 | Max results, max 50 |
| `timeframe` | string | `daily` | `daily` or `weekly` |
| `date` | string | latest | Historical snapshot (Plus+) |

**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