tickerapi

What this skill does

# 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_proximit