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

# Market Data Skills

> Reference for market.news, market.screener, market.movers, market.quote, and market.tide — the archive-backed market data skills exposed to AI agents.

Market data skills pull quotes, screens, movers, news, and breadth from the Ithaca archive. Most are backed by the **community archive** (delayed but free); `market.quote` uses **IBKR** for real-time or delayed quotes depending on your tier.

<Callout type="info">
  All examples assume you've opened a session with `session_context`. Every result includes the [provenance envelope](/skills/overview#the-provenance-envelope).
</Callout>

## Skill summary

| Skill ID          | Tool name         | Source            | Runtime     | Description                                      |
| ----------------- | ----------------- | ----------------- | ----------- | ------------------------------------------------ |
| `market.news`     | `market_news`     | archive-community | interactive | News headlines + sentiment for a ticker or topic |
| `market.screener` | `market_screener` | archive-community | scan        | Multi-filter universe screen                     |
| `market.movers`   | `market_movers`   | archive-community | interactive | Top gainers/losers/most-active by exchange       |
| `market.quote`    | `market_quote`    | ibkr              | interactive | Real-time or delayed quote                       |
| `market.tide`     | `market_tide`     | archive-community | interactive | Aggregate market breadth                         |

***

## market.news

Pulls recent news headlines for a ticker or topic, with a lightweight sentiment score per item.

**Arguments**

| Name                | Type     | Required                | Default    | Description                               |
| ------------------- | -------- | ----------------------- | ---------- | ----------------------------------------- |
| `symbol`            | string   | one of `symbol`/`topic` | —          | Ticker symbol, e.g. `NVDA`                |
| `topic`             | string   | one of `symbol`/`topic` | —          | Free-text topic, e.g. `semiconductors`    |
| `limit`             | int      | no                      | `20`       | Max headlines (1–100)                     |
| `since`             | ISO date | no                      | `now - 7d` | Earliest article timestamp                |
| `include_sentiment` | bool     | no                      | `true`     | Attach a `-1..1` sentiment score per item |

**Source**: `archive-community`

**Example**

```json theme={null}
market_news({ "symbol": "NVDA", "limit": 3 })
```

```json theme={null}
{
  "skill_id": "market.news",
  "data": {
    "items": [
      { "ts": "2025-06-27T14:02:00Z", "headline": "Nvidia lifts data-center guidance", "source": "Reuters", "sentiment": 0.72, "url": "..." },
      { "ts": "2025-06-27T11:30:00Z", "headline": "Analysts cut NVDA price target", "source": "Bloomberg", "sentiment": -0.31, "url": "..." },
      { "ts": "2025-06-27T09:15:00Z", "headline": "NVDA opens higher on AI demand", "source": "CNBC", "sentiment": 0.45, "url": "..." }
    ]
  },
  "provenance": { "source": "archive-community", "freshness": { "as_of": "2025-06-27T14:05:00Z", "lag_seconds": 180 }, "coverage": { "start": "2025-06-20T00:00:00Z", "end": "2025-06-27T14:05:00Z" }, "cost": { "credits": 1, "tier": "free" }, "warnings": [] }
}
```

***

## market.screener

Runs a multi-filter screen across the supported universe. Runs under the **scan** profile (900 s).

**Arguments**

| Name                 | Type   | Required | Default      | Description                                       |
| -------------------- | ------ | -------- | ------------ | ------------------------------------------------- |
| `universe`           | string | no       | `sp500`      | One of `sp500`, `russell2000`, `nasdaq100`, `all` |
| `min_market_cap`     | float  | no       | —            | Minimum market cap in USD                         |
| `max_market_cap`     | float  | no       | —            | Maximum market cap in USD                         |
| `min_price`          | float  | no       | —            | Minimum share price                               |
| `max_price`          | float  | no       | —            | Maximum share price                               |
| `min_avg_volume`     | float  | no       | —            | Minimum 30-day average volume                     |
| `sector`             | string | no       | —            | GICS sector, e.g. `Technology`                    |
| `industry`           | string | no       | —            | GICS industry                                     |
| `min_pe`             | float  | no       | —            | Minimum P/E (trailing)                            |
| `max_pe`             | float  | no       | —            | Maximum P/E (trailing)                            |
| `min_dividend_yield` | float  | no       | —            | Minimum dividend yield (decimal, e.g. `0.02`)     |
| `min_rs_rating`      | float  | no       | —            | Minimum Relative Strength rating (0–100)          |
| `sort_by`            | string | no       | `market_cap` | Sort field                                        |
| `sort_dir`           | string | no       | `desc`       | `asc` or `desc`                                   |
| `limit`              | int    | no       | `50`         | Max results (1–500)                               |

**Source**: `archive-community`

**Example**

```json theme={null}
market_screener({
  "universe": "sp500",
  "sector": "Technology",
  "min_market_cap": 100000000000,
  "min_avg_volume": 5000000,
  "sort_by": "rs_rating",
  "limit": 10
})
```

```json theme={null}
{
  "skill_id": "market.screener",
  "data": {
    "matches": [
      { "symbol": "NVDA", "name": "NVIDIA Corp", "market_cap": 3150000000000, "pe": 68.2, "rs_rating": 99, "price": 128.42 },
      { "symbol": "AVGO", "name": "Broadcom Inc", "market_cap": 780000000000, "pe": 71.4, "rs_rating": 95, "price": 172.18 }
    ],
    "total": 2
  },
  "provenance": { "source": "archive-community", "freshness": { "as_of": "2025-06-27T20:00:00Z", "lag_seconds": 900 }, "cost": { "credits": 5, "tier": "basic" }, "warnings": [] }
}
```

***

## market.movers

Returns top gainers, losers, and most-active tickers for an exchange or universe.

**Arguments**

| Name         | Type     | Required | Default        | Description                                     |
| ------------ | -------- | -------- | -------------- | ----------------------------------------------- |
| `exchange`   | string   | no       | `us`           | `us`, `nasdaq`, `nyse`, `amex`                  |
| `universe`   | string   | no       | —              | Optional universe filter (overrides `exchange`) |
| `direction`  | string   | no       | `all`          | `gainers`, `losers`, `most_active`, or `all`    |
| `min_price`  | float    | no       | `1.0`          | Exclude sub-dollar names                        |
| `min_volume` | float    | no       | —              | Minimum day volume                              |
| `limit`      | int      | no       | `25`           | Per category (1–100)                            |
| `as_of`      | ISO date | no       | latest session | Historical movers snapshot                      |

**Source**: `archive-community`

**Example**

```json theme={null}
market_movers({ "direction": "gainers", "limit": 5 })
```

```json theme={null}
{
  "skill_id": "market.movers",
  "data": {
    "as_of": "2025-06-27",
    "gainers": [
      { "symbol": "SMCI", "price": 612.30, "change_pct": 12.4, "volume": 8900000 },
      { "symbol": "PLTR", "price": 138.55, "change_pct": 8.1, "volume": 51000000 }
    ]
  },
  "provenance": { "source": "archive-community", "freshness": { "as_of": "2025-06-27T20:00:00Z", "lag_seconds": 60 }, "cost": { "credits": 1, "tier": "free" }, "warnings": [] }
}
```

***

## market.quote

Real-time or delayed quote via IBKR. Latency depends on your data tier.

**Arguments**

| Name       | Type      | Required | Default                         | Description                                                        |
| ---------- | --------- | -------- | ------------------------------- | ------------------------------------------------------------------ |
| `symbol`   | string    | yes      | —                               | Ticker symbol                                                      |
| `fields`   | string\[] | no       | `["last","bid","ask","volume"]` | Extra fields: `open`, `high`, `low`, `close`, `vwap`, `change_pct` |
| `realtime` | bool      | no       | `false`                         | Request real-time (requires pro tier + IBKR market data sub)       |

**Source**: `ibkr`

<Callout type="warn">
  If `realtime=true` but your tier or IBKR subscription doesn't include it, the call falls back to delayed (15 min) and adds a `realtime_unavailable` warning to the envelope.
</Callout>

**Example**

```json theme={null}
market_quote({ "symbol": "AAPL", "fields": ["last","bid","ask","volume","change_pct"] })
```

```json theme={null}
{
  "skill_id": "market.quote",
  "data": { "symbol": "AAPL", "last": 212.55, "bid": 212.54, "ask": 212.56, "volume": 42100000, "change_pct": 0.83 },
  "provenance": { "source": "ibkr", "freshness": { "as_of": "2025-06-27T16:00:15Z", "lag_seconds": 15 }, "cost": { "credits": 1, "tier": "free" }, "warnings": [] }
}
```

***

## market.tide

Aggregate market breadth — advancers/decliners, new highs/lows, up-volume/down-volume — across an exchange. Useful as a regime filter.

**Arguments**

| Name            | Type     | Required | Default        | Description                    |
| --------------- | -------- | -------- | -------------- | ------------------------------ |
| `exchange`      | string   | no       | `us`           | `us`, `nasdaq`, `nyse`, `amex` |
| `as_of`         | ISO date | no       | latest session | Historical breadth snapshot    |
| `lookback_days` | int      | no       | `1`            | Breadth trend over N sessions  |

**Source**: `archive-community`

**Example**

```json theme={null}
market_tide({ "exchange": "nyse", "lookback_days": 5 })
```

```json theme={null}
{
  "skill_id": "market.tide",
  "data": {
    "as_of": "2025-06-27",
    "advancers": 1842, "decliners": 1213, "unchanged": 102,
    "new_highs": 214, "new_lows": 38,
    "up_volume": 3120000000, "down_volume": 1980000000,
    "breadth_5d": [0.62, 0.58, 0.71, 0.49, 0.60]
  },
  "provenance": { "source": "archive-community", "freshness": { "as_of": "2025-06-27T20:00:00Z", "lag_seconds": 300 }, "cost": { "credits": 1, "tier": "free" }, "warnings": [] }
}
```

## Next steps

<Card title="Fundamentals Skills" icon="table-list" href="/skills/fundamentals">
  Fundamentals snapshots, comparisons, point-in-time data, and analyst ratings.
</Card>

<Card title="Skills Overview" icon="puzzle-piece" href="/skills/overview">
  Back to the full catalog and provenance envelope reference.
</Card>