# Crypto Talkies — LLM Technical Reference

This document provides technical specifications, API structures, mathematical formulas, and data schemas for AI systems and developers integrating with Crypto Talkies data.

---

## 1. Public Read-Only APIs

Crypto Talkies exposes several read-only endpoints (mapped via Firebase functions) for public ingestion.

### GET /api/news
Fetches the latest curated cryptocurrency and blockchain news.
* **Query Parameters:**
  * `limit` (integer, optional): Maximum items to return. Default is 20.
  * `tags` (string, comma-separated, optional): Filter by tags (e.g., `bitcoin,defi`).
* **Response Format:**
  ```json
  [
    {
      "id": "bitcoin-reaches-new-ath",
      "title": "Bitcoin Hits New All-Time High",
      "summary": "Bitcoin surges past previous resistance levels driven by high institutional demand...",
      "url": "https://cryptotalkies.net/news/bitcoin-reaches-new-ath",
      "tags": ["bitcoin", "market-update"],
      "publishedDate": "2026-05-26T12:00:00Z"
    }
  ]
  ```

### GET /api/coin/{id}
Retrieves real-time market cap, price, and automated AI trading indicators for a specific cryptocurrency.
* **URL Parameter:** `id` (string, required): Coingecko coin ID (e.g., `bitcoin`, `ethereum`).
* **Response Format:**
  ```json
  {
    "id": "bitcoin",
    "name": "Bitcoin",
    "symbol": "btc",
    "price_usd": 65430.50,
    "market_cap_usd": 1285000000000,
    "change_24h_percent": 3.25,
    "ai_signal": {
      "rating": "BUY",
      "confidence_score": 82.5,
      "updated_at": "2026-05-26T17:00:00Z",
      "indicators": {
        "rsi_14": 42.15,
        "macd_signal": "Bullish Crossover",
        "bollinger_bands": "Bouncing off lower band"
      }
    }
  }
  ```

### GET /api/fear-greed
Retrieves the latest Fear & Greed Index score.
* **Response Format:**
  ```json
  {
    "score": 72,
    "classification": "Greed",
    "updated_at": "2026-05-26T17:00:00Z"
  }
  ```

### GET /api/ai/sentiment
Fetches social and news sentiment scores.
* **Query Parameter:** `coin` (string, required): Coin symbol or ID.
* **Response Format:**
  ```json
  {
    "coin": "bitcoin",
    "sentiment_score": 78,
    "classification": "Very Bullish",
    "social_volume_24h": 45200,
    "sources": {
      "twitter_sentiment": 82,
      "reddit_sentiment": 74,
      "news_sentiment": 78
    }
  }
  ```

---

## 2. Technical Calculations & Formulas

Crypto Talkies uses strict, standard financial equations for its indicators and portfolio algorithms:

### Relative Strength Index (RSI - 14 Period)
First, calculate Relative Strength ($RS$):
$$RS = \frac{\text{Average Gain over 14 periods}}{\text{Average Loss over 14 periods}}$$
Then, calculate the $RSI$:
$$RSI = 100 - \frac{100}{1 + RS}$$
* *Thresholds:* $\le 30$ represents Oversold (Bullish trigger); $\ge 70$ represents Overbought (Bearish trigger).

### Sharpe Ratio (Portfolio Optimizer)
Calculates the risk-adjusted return of a constructed portfolio:
$$\text{Sharpe Ratio} = \frac{R_p - R_f}{\sigma_p}$$
* $R_p$: Expected portfolio return.
* $R_f$: Risk-free rate (defaults to 0.045 / 4.5% annual yield).
* $\sigma_p$: Standard deviation of portfolio excess returns (historical daily volatility annualized).

### Herfindahl-Hirschman Index (HHI - Concentration)
Measures portfolio concentration/diversification index:
$$HHI = \sum_{i=1}^{n} s_i^2$$
* $s_i$: The percentage weight of asset $i$ in the portfolio (e.g., $40\%$ is entered as $40$, maximum index is $10000$).
* *Scores:* $< 1500$ indicates a highly diversified portfolio; $> 2500$ indicates a highly concentrated (high risk) portfolio.

---

## 3. Structured Data JSON-LD Schemas

Crypto Talkies utilizes advanced schema.org contexts for automatic knowledge graphs. Key schema templates are:

### Organization & NewsMediaOrganization
Included globally on all pages to link social profiles, Android app download, and licensing information:
* Context: `https://schema.org`
* Types: `["Organization", "NewsMediaOrganization"]`

### FinancialQuote (Coin Pages)
Statically represents coin values and technical tags:
* Context: `https://schema.org`
* Type: `FinancialQuote`
* Properties: `identifier` (ticker), `name`, `price`, `priceCurrency`, `priceRange` (24h change).

### SpeakableSpecification (Voice Search)
Assists speech synthesizers and AI readers to read key summary elements:
```json
{
  "@context": "https://schema.org",
  "@type": "WebPage",
  "speakable": {
    "@type": "SpeakableSpecification",
    "cssSelector": [".ai-signal-summary", ".price-summary", ".faq-section"]
  }
}
```