> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fintheon.io/llms.txt
> Use this file to discover all available pages before exploring further.

# RiskFlow — AI-Scored News Feed with IV Urgency

> RiskFlow is Fintheon's real-time news feed scored for implied volatility impact. Monitor urgency levels, manage your watchlist, track catalyst phrases, and receive breaking-news alerts.

RiskFlow is the intelligence layer behind Fintheon's real-time awareness. Every incoming headline — from social commentary, economic releases, and tracked speaker accounts — is scored for implied volatility impact and ranked on a 1–10 urgency scale. The feed is always live, adapts to your instrument selection, and drives several downstream features: it feeds NarrativeFlow catalyst cards, triggers Fintheon Arbitrum deliberations, and supplies the source material for every daily brief. You see a compact version of RiskFlow in the Strategium right rail; the full feed lives inside Sanctum.

## How scoring works

Each item that enters the feed receives an IV score based on the headline content, the source's credibility weight, the current VIX environment, and the session context (pre-market, regular hours, after-hours). Scores run from 1 to 10:

| Score range | Urgency level       | What it means                                                                   |
| ----------- | ------------------- | ------------------------------------------------------------------------------- |
| 1–2         | Low                 | Background noise — informational, no immediate market impact expected           |
| 3–4         | Medium              | Noteworthy development; warrants monitoring but unlikely to move the tape alone |
| 5–6         | Elevated            | Meaningful catalyst potential; relevant to positions or the day's theme         |
| 7–8         | High                | Significant event risk; cross-reference with your open positions                |
| 9–10        | Critical / Breaking | Market-moving potential; immediate attention warranted                          |

Items scoring **4 or above** are flagged as breaking news and pushed through the real-time SSE stream. Items scoring **8.5 or above** from a top-tier commentator or tracked party of interest automatically trigger a Fintheon Arbitrum chamber deliberation.

The score you see on each card already accounts for your selected instrument. A headline bearish for equities will show a different implied direction for `/ES` versus `/GC` (gold), and RiskFlow flips the sentiment label accordingly at serve time.

## IV aggregate

The IV aggregate is a composite implied volatility score computed from recent news items, live VIX data, session timing, and event-season context (earnings weeks, FOMC windows). It appears as the large number in the IV widget in Strategium.

The aggregate refreshes continuously. When VIX spikes sharply in a short window, the aggregate score receives an additional upward adjustment. The widget hover expands to show the rationale, session multiplier, VIX correlation context, and the latest Arbitrum verdict peek.

**API endpoint**

```http theme={null}
GET /api/riskflow/iv-aggregate?instrument=/ES
```

You can pass any supported instrument symbol via the `instrument` query parameter. The response includes the composite score, implied points estimate for that instrument, VIX level and spike status, event activity count, and a plain-language rationale string.

## Watchlist

Your watchlist filters the feed to surface items most relevant to the instruments and tickers you care about. Items matching your watchlist symbols are promoted to the top of the feed.

<Steps>
  <Step title="Open your watchlist">
    The watchlist editor is accessible from the Strategium panel header or from within the full RiskFlow view in Sanctum.
  </Step>

  <Step title="Add symbols">
    Type a ticker or instrument symbol (e.g., `NVDA`, `/ES`, `SPY`) and confirm. Symbols are matched against both the item's tagged symbols and its headline text.
  </Step>

  <Step title="Remove symbols">
    Select a symbol in the list and remove it. The feed adjusts immediately.
  </Step>
</Steps>

**Watchlist API endpoints**

| Endpoint                                 | Purpose                      |
| ---------------------------------------- | ---------------------------- |
| `GET /api/riskflow/watchlist`            | Fetch your current watchlist |
| `POST /api/riskflow/watchlist`           | Replace the full watchlist   |
| `POST /api/riskflow/watchlist/symbols`   | Add one or more symbols      |
| `DELETE /api/riskflow/watchlist/symbols` | Remove one or more symbols   |

<CodeGroup>
  ```http Add symbols theme={null}
  POST /api/riskflow/watchlist/symbols
  Content-Type: application/json

  { "symbols": ["NVDA", "/NQ"] }
  ```

  ```http Remove symbols theme={null}
  DELETE /api/riskflow/watchlist/symbols
  Content-Type: application/json

  { "symbols": ["NVDA"] }
  ```
</CodeGroup>

## Catalyst Watch

Catalyst Watch lets you define keyword phrases that act as alert triggers. Any incoming headline containing a matching phrase is immediately surfaced and — if the IV score warrants — flagged for your attention. Use this to track specific policy actions, executive names, geopolitical terms, or any phrase that matters to your trading plan.

<Steps>
  <Step title="Add a phrase">
    Open Catalyst Watch from the RiskFlow settings panel. Type the phrase you want to monitor. You can choose between **contains** matching (the phrase appears anywhere in the headline) or **exact** matching.

    Bias-loaded words (buy, sell, long, short, etc.) are automatically stripped from the stored phrase to keep matching neutral.
  </Step>

  <Step title="Set repeat behavior">
    Toggle **repeating** on if you want the alert to fire every time the phrase matches, not just on the first hit.
  </Step>

  <Step title="Manage active phrases">
    Your active Catalyst Watch phrases are listed in the panel. Deactivate any phrase to stop monitoring it without deleting it permanently.
  </Step>
</Steps>

**Catalyst Watch API endpoints**

| Endpoint                           | Purpose                   |
| ---------------------------------- | ------------------------- |
| `GET /api/riskflow/phrases`        | List your active phrases  |
| `POST /api/riskflow/phrases`       | Add a new phrase          |
| `DELETE /api/riskflow/phrases/:id` | Deactivate a phrase by ID |

<CodeGroup>
  ```http Add a phrase theme={null}
  POST /api/riskflow/phrases
  Content-Type: application/json

  {
    "phrase": "reciprocal tariff",
    "matchType": "contains",
    "repeating": true
  }
  ```

  ```json Response theme={null}
  {
    "phrase": {
      "id": 42,
      "phrase": "reciprocal tariff",
      "matchType": "contains",
      "repeating": true
    },
    "removedBias": []
  }
  ```
</CodeGroup>

## Breaking news and the SSE stream

Items scoring level 4 or above are marked breaking and pushed immediately to all connected clients via a Server-Sent Events stream. You don't need to poll or refresh — breaking items appear in the feed automatically as they arrive.

```http theme={null}
GET /api/riskflow/stream
```

The stream emits a heartbeat comment every 30 seconds to keep the connection alive. Breaking items arrive as SSE event data objects. The Strategium feed and the full Sanctum feed both connect to this stream.

## Marking items as not relevant

The thumbs-down button on any feed card removes that item from your feed and logs the dismissal as a feedback signal. Over time, the scorer learns from your dismissals and down-weights similar items from the same source. You can optionally include a reason when dismissing via the API.

```http theme={null}
POST /api/riskflow/:id/not-relevant
Content-Type: application/json

{ "reason": "Off-topic source" }
```

The item is removed immediately from both the scored and raw item tables. Harper's autonomous loop picks up dismissed items on her next heartbeat to incorporate the signal into feed quality scoring.

## RiskFlow in Strategium vs. Sanctum

**Strategium (right rail)** — Shows a compact, truncated version of the feed: the most recent high-scoring items, the IV aggregate widget, and the Catalyst Watch alert banner. This is your always-visible peripheral awareness layer while you work in other surfaces.

**Sanctum (full feed)** — The complete RiskFlow experience with full item cards, expandable agent notes, NarrativeFlow thread assignments, and all filter controls. Navigate to Sanctum from the Consilium workspace to get the untruncated view.

## Risk Signals

Risk Signals are AI-refined, high-confidence signal cards generated from the current feed. They represent the subset of RiskFlow items that the scoring engine has assessed as having high signal-to-noise ratio — not just high IV scores, but items where the analytical confidence in the market implication is also elevated.

```http theme={null}
GET /api/riskflow/risk-signals
```

Risk Signal cards appear at the top of the full Sanctum feed view when available. Each card includes a direction, a confidence level, and the source item.

## API reference summary

| Endpoint                          | Method        | Description                                                                                                                          |
| --------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `/api/riskflow/feed`              | GET           | Main scored news feed (supports filters: `sources`, `symbols`, `tags`, `breaking`, `limit`, `offset`, `minMacroLevel`, `instrument`) |
| `/api/riskflow/breaking`          | GET           | Breaking items only (level 4+)                                                                                                       |
| `/api/riskflow/stream`            | GET           | SSE stream for real-time level 4+ push                                                                                               |
| `/api/riskflow/iv-aggregate`      | GET           | Composite IV score with VIX correlation                                                                                              |
| `/api/riskflow/watchlist`         | GET / POST    | Read or replace your watchlist                                                                                                       |
| `/api/riskflow/watchlist/symbols` | POST / DELETE | Add or remove watchlist symbols                                                                                                      |
| `/api/riskflow/phrases`           | GET / POST    | Read or add Catalyst Watch phrases                                                                                                   |
| `/api/riskflow/phrases/:id`       | DELETE        | Deactivate a phrase                                                                                                                  |
| `/api/riskflow/:id/not-relevant`  | POST          | Mark an item as not relevant                                                                                                         |
| `/api/riskflow/risk-signals`      | GET           | AI-refined high-confidence signal cards                                                                                              |
| `/api/riskflow/sources`           | GET           | Connection status for all data source indicators                                                                                     |