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

# Finnhub

The io.b3os/finnhub pack: 8 actions with call snippets, fixture outputs, connection setup and error codes, generated from version 1.0.0.

`io.b3os/finnhub` 1.0.0 · `finance`, `stocks`, `market-data` · MIT

Stock market data from Finnhub with your own Finnhub API key: real-time quotes, basic financial metrics (valuation, margins, growth, 52-week range, beta), company and market news, earnings calendar, analyst recommendation trends, thematic portfolios and symbol search. Some endpoints, such as thematic portfolios, need a paid Finnhub plan.

Every call's result carries `upstream_status` and `timing`: `validate_ms`, `inject_ms`, `render_ms`, `upstream_ms`, `map_ms` and `total_ms`. `upstream` is the service's time; the others are B3OS's own ([call actions](/actions/call)). The snippets below show no timing values, because a fixture records none.

## Connection

`finnhub`, type `api_key`: Finnhub API key.

Your Finnhub API key from finnhub.io/dashboard. Sent as the X-Finnhub-Token header to finnhub.io only.

How to get one: [finnhub.io](https://finnhub.io/docs/api/authentication).

The credential is sent only to `finnhub.io`.

Store the credential once as a [vault connection](/vault) for this pack and key, then name its id in a call's `connections`. Leave the key out and B3OS uses the project's newest connection for the pack and key without a `subject` ([connections](/actions/call#connections)).

Hosts it reaches: `finnhub.io`.

## Actions

| Action | Effect | MCP tool | Title |
|---|---|---|---|
| [`get-quote`](/actions/catalog/finnhub#finnhub-get-quote) | read | `finnhub__get-quote` | Get Stock Quote |
| [`get-basic-financials`](/actions/catalog/finnhub#finnhub-get-basic-financials) | read | `finnhub__get-basic-financials` | Get Basic Financials |
| [`get-company-news`](/actions/catalog/finnhub#finnhub-get-company-news) | read | `finnhub__get-company-news` | Get Company News |
| [`get-earnings-calendar`](/actions/catalog/finnhub#finnhub-get-earnings-calendar) | read | `finnhub__get-earnings-calendar` | Get Earnings Calendar |
| [`get-investment-theme`](/actions/catalog/finnhub#finnhub-get-investment-theme) | read | `finnhub__get-investment-theme` | Get Investment Theme Constituents |
| [`get-market-news`](/actions/catalog/finnhub#finnhub-get-market-news) | read | `finnhub__get-market-news` | Get Market News |
| [`get-recommendation-trends`](/actions/catalog/finnhub#finnhub-get-recommendation-trends) | read | `finnhub__get-recommendation-trends` | Get Analyst Recommendation Trends |
| [`symbol-search`](/actions/catalog/finnhub#finnhub-symbol-search) | read | `finnhub__symbol-search` | Search Symbols |

get-quote

**Get Stock Quote.** Fetch the real-time quote for a stock symbol from Finnhub. Returns current price, daily change, percent change, day high/low, open, and previous close. Ideal for: stock price alerts, portfolio monitoring, price-based workflow conditions.

Ref `io.b3os/finnhub/get-quote@1.0.0` · effect `read` · connection `finnhub` · MCP tool `finnhub__get-quote`

**curl**

```bash
    curl -s https://beta-api.b3os.org/v1/actions/call \
      -H "Authorization: Bearer $B3OS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
          "ref": "io.b3os/finnhub/get-quote@1",
          "input": {"symbol": "AAPL"},
          "connections": {"finnhub": "conn_01m5t6cbgdjs1ketgcqwa2sne8"}
        }'
    ```
  **TypeScript**

```ts
    import { B3OS } from "@b3os/sdk";

    const b3os = new B3OS();
    const result = await b3os.actions.call({
      ref: "io.b3os/finnhub/get-quote@1",
      input: { symbol: "AAPL" },
      connections: { finnhub: "conn_01m5t6cbgdjs1ketgcqwa2sne8" },
    });
    console.log(result.output);
    ```
  **Python**

```python
    from b3os import B3OS

    b3os = B3OS()
    result = b3os.actions.call({
        "ref": "io.b3os/finnhub/get-quote@1",
        "input": {"symbol": "AAPL"},
        "connections": {"finnhub": "conn_01m5t6cbgdjs1ketgcqwa2sne8"},
    })
    print(result["output"])
    ```
  **MCP**

```json
    {
      "method": "tools/call",
      "params": {"name": "finnhub__get-quote", "arguments": {"symbol": "AAPL"}}
    }
    ```

    Expose the pack as tools with `--packs finnhub` on the local server or `?packs=finnhub` on the remote URL, and the agent calls `finnhub__get-quote` with the action's input. The tool uses your newest connection for each key without a `subject`. Without exposing the pack, `actions_call` takes the same input with `ref`.

Output, labeled `fixture`: Get Stock Quote (documented response shape, example values). From the bundle's `fixtures/get-quote.json`, not a live call.

```json
{
  "symbol": "AAPL",
  "current": 262.82,
  "change": 3.24,
  "percentChange": 1.2482,
  "high": 264.13,
  "low": 259.18,
  "open": 259.94,
  "previousClose": 259.58,
  "timestamp": 1761336000
}
```

When the service answers with an error, the call fails with [`upstream_error`](/errors#upstream_error) and `pack_error.code` is one of:

| `pack_error.code` | Service status | Retryable | Message |
|---|---|---|---|
| `connection_unauthorized` | 401 | no | Finnhub rejected the API key; check the connection. |
| `forbidden` | 403 | no | This Finnhub endpoint or symbol is not included in your Finnhub plan. |
| `rate_limited` | 429 | yes | Finnhub rate limit reached for this API key; retry shortly. |
| `invalid_request` | 400, 422 | no | Finnhub rejected the request (check the symbol and dates). |

get-basic-financials

**Get Basic Financials.** Fetch basic financial metrics for a stock symbol from Finnhub (100+ metrics: valuation, margins, growth, liquidity, 52-week range). Returns a metric map keyed by name, e.g. peTTM, beta, 52WeekHigh, currentRatio, grossMarginTTM. Ideal for: fundamental screening, valuation alerts, enriching AI analysis with company fundamentals.

Ref `io.b3os/finnhub/get-basic-financials@1.0.0` · effect `read` · connection `finnhub` · MCP tool `finnhub__get-basic-financials`

**curl**

```bash
    curl -s https://beta-api.b3os.org/v1/actions/call \
      -H "Authorization: Bearer $B3OS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
          "ref": "io.b3os/finnhub/get-basic-financials@1",
          "input": {"symbol": "AAPL"},
          "connections": {"finnhub": "conn_01m5t6cbgdjs1ketgcqwa2sne8"}
        }'
    ```
  **TypeScript**

```ts
    import { B3OS } from "@b3os/sdk";

    const b3os = new B3OS();
    const result = await b3os.actions.call({
      ref: "io.b3os/finnhub/get-basic-financials@1",
      input: { symbol: "AAPL" },
      connections: { finnhub: "conn_01m5t6cbgdjs1ketgcqwa2sne8" },
    });
    console.log(result.output);
    ```
  **Python**

```python
    from b3os import B3OS

    b3os = B3OS()
    result = b3os.actions.call({
        "ref": "io.b3os/finnhub/get-basic-financials@1",
        "input": {"symbol": "AAPL"},
        "connections": {"finnhub": "conn_01m5t6cbgdjs1ketgcqwa2sne8"},
    })
    print(result["output"])
    ```
  **MCP**

```json
    {
      "method": "tools/call",
      "params": {
        "name": "finnhub__get-basic-financials",
        "arguments": {"symbol": "AAPL"}
      }
    }
    ```

    Expose the pack as tools with `--packs finnhub` on the local server or `?packs=finnhub` on the remote URL, and the agent calls `finnhub__get-basic-financials` with the action's input. The tool uses your newest connection for each key without a `subject`. Without exposing the pack, `actions_call` takes the same input with `ref`.

Output, labeled `fixture`: Get Basic Financials (documented response shape, example values). From the bundle's `fixtures/get-basic-financials.json`, not a live call.

```json
{
  "symbol": "AAPL",
  "metricType": "all",
  "metric": {
    "10DayAverageTradingVolume": 45.8,
    "52WeekHigh": 264.38,
    "52WeekLow": 169.21,
    "beta": 1.09,
    "currentRatioQuarterly": 0.87,
    "grossMarginTTM": 46.68,
    "peTTM": 39.9,
    "revenueGrowthTTMYoy": 6.43
  }
}
```

When the service answers with an error, the call fails with [`upstream_error`](/errors#upstream_error) and `pack_error.code` is one of:

| `pack_error.code` | Service status | Retryable | Message |
|---|---|---|---|
| `connection_unauthorized` | 401 | no | Finnhub rejected the API key; check the connection. |
| `forbidden` | 403 | no | This Finnhub endpoint or symbol is not included in your Finnhub plan. |
| `rate_limited` | 429 | yes | Finnhub rate limit reached for this API key; retry shortly. |
| `invalid_request` | 400, 422 | no | Finnhub rejected the request (check the symbol and dates). |

get-company-news

**Get Company News.** Fetch news articles about a stock symbol from Finnhub published between two dates (YYYY-MM-DD), with headline, summary, source, URL, image and publication time. Finnhub covers North American companies; its free tier has one year of history.

Ref `io.b3os/finnhub/get-company-news@1.0.0` · effect `read` · connection `finnhub` · MCP tool `finnhub__get-company-news`

**curl**

```bash
    curl -s https://beta-api.b3os.org/v1/actions/call \
      -H "Authorization: Bearer $B3OS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
          "ref": "io.b3os/finnhub/get-company-news@1",
          "input": {
            "symbol": "AAPL",
            "from": "2026-10-19",
            "to": "2026-10-26",
            "limit": 2
          },
          "connections": {"finnhub": "conn_01m5t6cbgdjs1ketgcqwa2sne8"}
        }'
    ```
  **TypeScript**

```ts
    import { B3OS } from "@b3os/sdk";

    const b3os = new B3OS();
    const result = await b3os.actions.call({
      ref: "io.b3os/finnhub/get-company-news@1",
      input: { symbol: "AAPL", from: "2026-10-19", to: "2026-10-26", limit: 2 },
      connections: { finnhub: "conn_01m5t6cbgdjs1ketgcqwa2sne8" },
    });
    console.log(result.output);
    ```
  **Python**

```python
    from b3os import B3OS

    b3os = B3OS()
    result = b3os.actions.call({
        "ref": "io.b3os/finnhub/get-company-news@1",
        "input": {
            "symbol": "AAPL",
            "from": "2026-10-19",
            "to": "2026-10-26",
            "limit": 2,
        },
        "connections": {"finnhub": "conn_01m5t6cbgdjs1ketgcqwa2sne8"},
    })
    print(result["output"])
    ```
  **MCP**

```json
    {
      "method": "tools/call",
      "params": {
        "name": "finnhub__get-company-news",
        "arguments": {
          "symbol": "AAPL",
          "from": "2026-10-19",
          "to": "2026-10-26",
          "limit": 2
        }
      }
    }
    ```

    Expose the pack as tools with `--packs finnhub` on the local server or `?packs=finnhub` on the remote URL, and the agent calls `finnhub__get-company-news` with the action's input. The tool uses your newest connection for each key without a `subject`. Without exposing the pack, `actions_call` takes the same input with `ref`.

Output, labeled `fixture`: Get Company News (documented response shape, example values). From the bundle's `fixtures/get-company-news.json`, not a live call.

```json
{
  "symbol": "AAPL",
  "from": "2026-10-19",
  "to": "2026-10-26",
  "articles": [
    {
      "id": 136810001,
      "category": "company",
      "datetime": 1898210801,
      "headline": "Apple's services push meets an expanding installed base",
      "summary": "Analysts expect services revenue to keep growing as the installed base expands.",
      "source": "Yahoo",
      "url": "https://finnhub.io/api/news?id=136810001",
      "image": "https://static2.finnhub.io/file/publicdatany/finnhubimage/stock_market_news/example.jpg",
      "related": "AAPL"
    },
    {
      "id": 136810002,
      "category": "company",
      "datetime": 1898210802,
      "headline": "What to watch in Apple's quarterly report",
      "summary": "Analysts expect services revenue to keep growing as the installed base expands.",
      "source": "Yahoo",
      "url": "https://finnhub.io/api/news?id=136810002",
      "image": "https://static2.finnhub.io/file/publicdatany/finnhubimage/stock_market_news/example.jpg",
      "related": "AAPL"
    }
  ],
  "count": 2
}
```

When the service answers with an error, the call fails with [`upstream_error`](/errors#upstream_error) and `pack_error.code` is one of:

| `pack_error.code` | Service status | Retryable | Message |
|---|---|---|---|
| `connection_unauthorized` | 401 | no | Finnhub rejected the API key; check the connection. |
| `forbidden` | 403 | no | This Finnhub endpoint or symbol is not included in your Finnhub plan. |
| `rate_limited` | 429 | yes | Finnhub rate limit reached for this API key; retry shortly. |
| `invalid_request` | 400, 422 | no | Finnhub rejected the request (check the symbol and dates). |

get-earnings-calendar

**Get Earnings Calendar.** Fetch scheduled and reported company earnings from Finnhub between two dates (YYYY-MM-DD), optionally for one symbol: date, before or after market hours, fiscal year and quarter, EPS and revenue estimates and actuals.

Ref `io.b3os/finnhub/get-earnings-calendar@1.0.0` · effect `read` · connection `finnhub` · MCP tool `finnhub__get-earnings-calendar`

**curl**

```bash
    curl -s https://beta-api.b3os.org/v1/actions/call \
      -H "Authorization: Bearer $B3OS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
          "ref": "io.b3os/finnhub/get-earnings-calendar@1",
          "input": {"from": "2026-10-27", "to": "2026-10-31", "symbol": "AAPL"},
          "connections": {"finnhub": "conn_01m5t6cbgdjs1ketgcqwa2sne8"}
        }'
    ```
  **TypeScript**

```ts
    import { B3OS } from "@b3os/sdk";

    const b3os = new B3OS();
    const result = await b3os.actions.call({
      ref: "io.b3os/finnhub/get-earnings-calendar@1",
      input: { from: "2026-10-27", to: "2026-10-31", symbol: "AAPL" },
      connections: { finnhub: "conn_01m5t6cbgdjs1ketgcqwa2sne8" },
    });
    console.log(result.output);
    ```
  **Python**

```python
    from b3os import B3OS

    b3os = B3OS()
    result = b3os.actions.call({
        "ref": "io.b3os/finnhub/get-earnings-calendar@1",
        "input": {"from": "2026-10-27", "to": "2026-10-31", "symbol": "AAPL"},
        "connections": {"finnhub": "conn_01m5t6cbgdjs1ketgcqwa2sne8"},
    })
    print(result["output"])
    ```
  **MCP**

```json
    {
      "method": "tools/call",
      "params": {
        "name": "finnhub__get-earnings-calendar",
        "arguments": {"from": "2026-10-27", "to": "2026-10-31", "symbol": "AAPL"}
      }
    }
    ```

    Expose the pack as tools with `--packs finnhub` on the local server or `?packs=finnhub` on the remote URL, and the agent calls `finnhub__get-earnings-calendar` with the action's input. The tool uses your newest connection for each key without a `subject`. Without exposing the pack, `actions_call` takes the same input with `ref`.

Output, labeled `fixture`: Get Earnings Calendar (documented response shape, example values). From the bundle's `fixtures/get-earnings-calendar.json`, not a live call.

```json
{
  "from": "2026-10-27",
  "to": "2026-10-31",
  "symbol": "AAPL",
  "earnings": [
    {
      "symbol": "AAPL",
      "date": "2026-10-30",
      "hour": "amc",
      "year": 2026,
      "quarter": 4,
      "epsEstimate": 1.78,
      "epsActual": null,
      "revenueEstimate": 101960000000,
      "revenueActual": null
    }
  ],
  "count": 1
}
```

When the service answers with an error, the call fails with [`upstream_error`](/errors#upstream_error) and `pack_error.code` is one of:

| `pack_error.code` | Service status | Retryable | Message |
|---|---|---|---|
| `connection_unauthorized` | 401 | no | Finnhub rejected the API key; check the connection. |
| `forbidden` | 403 | no | This Finnhub endpoint or symbol is not included in your Finnhub plan. |
| `rate_limited` | 429 | yes | Finnhub rate limit reached for this API key; retry shortly. |
| `invalid_request` | 400, 422 | no | Finnhub rejected the request (check the symbol and dates). |

get-investment-theme

**Get Investment Theme Constituents.** Fetch the constituent stock symbols of a thematic investing portfolio from Finnhub (e.g. ai, robotics, cybersecurity, fintech). Returns the list of symbols and a count; unknown themes return an empty list. Ideal for: building thematic watchlists, screening stocks by sector trend, feeding symbols into downstream quote or sentiment checks.

Ref `io.b3os/finnhub/get-investment-theme@1.0.0` · effect `read` · connection `finnhub` · MCP tool `finnhub__get-investment-theme`

**curl**

```bash
    curl -s https://beta-api.b3os.org/v1/actions/call \
      -H "Authorization: Bearer $B3OS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
          "ref": "io.b3os/finnhub/get-investment-theme@1",
          "input": {"theme": "financialExchangesData"},
          "connections": {"finnhub": "conn_01m5t6cbgdjs1ketgcqwa2sne8"}
        }'
    ```
  **TypeScript**

```ts
    import { B3OS } from "@b3os/sdk";

    const b3os = new B3OS();
    const result = await b3os.actions.call({
      ref: "io.b3os/finnhub/get-investment-theme@1",
      input: { theme: "financialExchangesData" },
      connections: { finnhub: "conn_01m5t6cbgdjs1ketgcqwa2sne8" },
    });
    console.log(result.output);
    ```
  **Python**

```python
    from b3os import B3OS

    b3os = B3OS()
    result = b3os.actions.call({
        "ref": "io.b3os/finnhub/get-investment-theme@1",
        "input": {"theme": "financialExchangesData"},
        "connections": {"finnhub": "conn_01m5t6cbgdjs1ketgcqwa2sne8"},
    })
    print(result["output"])
    ```
  **MCP**

```json
    {
      "method": "tools/call",
      "params": {
        "name": "finnhub__get-investment-theme",
        "arguments": {"theme": "financialExchangesData"}
      }
    }
    ```

    Expose the pack as tools with `--packs finnhub` on the local server or `?packs=finnhub` on the remote URL, and the agent calls `finnhub__get-investment-theme` with the action's input. The tool uses your newest connection for each key without a `subject`. Without exposing the pack, `actions_call` takes the same input with `ref`.

Output, labeled `fixture`: Get Investment Theme Constituents (documented response shape, example values). From the bundle's `fixtures/get-investment-theme.json`, not a live call.

```json
{
  "theme": "financialExchangesData",
  "symbols": ["ICE", "CME", "NDAQ"],
  "count": 3
}
```

When the service answers with an error, the call fails with [`upstream_error`](/errors#upstream_error) and `pack_error.code` is one of:

| `pack_error.code` | Service status | Retryable | Message |
|---|---|---|---|
| `connection_unauthorized` | 401 | no | Finnhub rejected the API key; check the connection. |
| `forbidden` | 403 | no | This Finnhub endpoint or symbol is not included in your Finnhub plan. |
| `rate_limited` | 429 | yes | Finnhub rate limit reached for this API key; retry shortly. |
| `invalid_request` | 400, 422 | no | Finnhub rejected the request (check the symbol and dates). |

get-market-news

**Get Market News.** Fetch the latest market news from Finnhub for a category: general, forex, crypto, or merger. Returns headline, summary, source, URL, and publication timestamp per article, capped by limit (default 20, max 100). Ideal for: daily market briefings, crypto news alerts, feeding headlines into AI summarization.

Ref `io.b3os/finnhub/get-market-news@1.0.0` · effect `read` · connection `finnhub` · MCP tool `finnhub__get-market-news`

**curl**

```bash
    curl -s https://beta-api.b3os.org/v1/actions/call \
      -H "Authorization: Bearer $B3OS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
          "ref": "io.b3os/finnhub/get-market-news@1",
          "input": {"category": "general", "limit": 2},
          "connections": {"finnhub": "conn_01m5t6cbgdjs1ketgcqwa2sne8"}
        }'
    ```
  **TypeScript**

```ts
    import { B3OS } from "@b3os/sdk";

    const b3os = new B3OS();
    const result = await b3os.actions.call({
      ref: "io.b3os/finnhub/get-market-news@1",
      input: { category: "general", limit: 2 },
      connections: { finnhub: "conn_01m5t6cbgdjs1ketgcqwa2sne8" },
    });
    console.log(result.output);
    ```
  **Python**

```python
    from b3os import B3OS

    b3os = B3OS()
    result = b3os.actions.call({
        "ref": "io.b3os/finnhub/get-market-news@1",
        "input": {"category": "general", "limit": 2},
        "connections": {"finnhub": "conn_01m5t6cbgdjs1ketgcqwa2sne8"},
    })
    print(result["output"])
    ```
  **MCP**

```json
    {
      "method": "tools/call",
      "params": {
        "name": "finnhub__get-market-news",
        "arguments": {"category": "general", "limit": 2}
      }
    }
    ```

    Expose the pack as tools with `--packs finnhub` on the local server or `?packs=finnhub` on the remote URL, and the agent calls `finnhub__get-market-news` with the action's input. The tool uses your newest connection for each key without a `subject`. Without exposing the pack, `actions_call` takes the same input with `ref`.

Output, labeled `fixture`: Get Market News (documented response shape, example values). From the bundle's `fixtures/get-market-news.json`, not a live call.

```json
{
  "category": "general",
  "articles": [
    {
      "id": 7542001,
      "category": "company",
      "datetime": 1768942801,
      "headline": "Futures edge higher ahead of a busy earnings week",
      "summary": "Analysts expect services revenue to keep growing as the installed base expands.",
      "source": "Yahoo",
      "url": "https://finnhub.io/api/news?id=7542001",
      "image": "https://static2.finnhub.io/file/publicdatany/finnhubimage/stock_market_news/example.jpg",
      "related": ""
    },
    {
      "id": 7542002,
      "category": "company",
      "datetime": 1768942802,
      "headline": "Treasury yields steady before Fed decision",
      "summary": "Analysts expect services revenue to keep growing as the installed base expands.",
      "source": "Yahoo",
      "url": "https://finnhub.io/api/news?id=7542002",
      "image": "https://static2.finnhub.io/file/publicdatany/finnhubimage/stock_market_news/example.jpg",
      "related": ""
    }
  ],
  "count": 2
}
```

When the service answers with an error, the call fails with [`upstream_error`](/errors#upstream_error) and `pack_error.code` is one of:

| `pack_error.code` | Service status | Retryable | Message |
|---|---|---|---|
| `connection_unauthorized` | 401 | no | Finnhub rejected the API key; check the connection. |
| `forbidden` | 403 | no | This Finnhub endpoint or symbol is not included in your Finnhub plan. |
| `rate_limited` | 429 | yes | Finnhub rate limit reached for this API key; retry shortly. |
| `invalid_request` | 400, 422 | no | Finnhub rejected the request (check the symbol and dates). |

get-recommendation-trends

**Get Analyst Recommendation Trends.** Fetch monthly analyst recommendation trends for a stock symbol from Finnhub. Returns strong-buy/buy/hold/sell/strong-sell counts per month, most recent first. Ideal for: tracking analyst consensus shifts, rating-change alerts, combining with price data for trade signals.

Ref `io.b3os/finnhub/get-recommendation-trends@1.0.0` · effect `read` · connection `finnhub` · MCP tool `finnhub__get-recommendation-trends`

**curl**

```bash
    curl -s https://beta-api.b3os.org/v1/actions/call \
      -H "Authorization: Bearer $B3OS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
          "ref": "io.b3os/finnhub/get-recommendation-trends@1",
          "input": {"symbol": "AAPL"},
          "connections": {"finnhub": "conn_01m5t6cbgdjs1ketgcqwa2sne8"}
        }'
    ```
  **TypeScript**

```ts
    import { B3OS } from "@b3os/sdk";

    const b3os = new B3OS();
    const result = await b3os.actions.call({
      ref: "io.b3os/finnhub/get-recommendation-trends@1",
      input: { symbol: "AAPL" },
      connections: { finnhub: "conn_01m5t6cbgdjs1ketgcqwa2sne8" },
    });
    console.log(result.output);
    ```
  **Python**

```python
    from b3os import B3OS

    b3os = B3OS()
    result = b3os.actions.call({
        "ref": "io.b3os/finnhub/get-recommendation-trends@1",
        "input": {"symbol": "AAPL"},
        "connections": {"finnhub": "conn_01m5t6cbgdjs1ketgcqwa2sne8"},
    })
    print(result["output"])
    ```
  **MCP**

```json
    {
      "method": "tools/call",
      "params": {
        "name": "finnhub__get-recommendation-trends",
        "arguments": {"symbol": "AAPL"}
      }
    }
    ```

    Expose the pack as tools with `--packs finnhub` on the local server or `?packs=finnhub` on the remote URL, and the agent calls `finnhub__get-recommendation-trends` with the action's input. The tool uses your newest connection for each key without a `subject`. Without exposing the pack, `actions_call` takes the same input with `ref`.

Output, labeled `fixture`: Get Analyst Recommendation Trends (documented response shape, example values). From the bundle's `fixtures/get-recommendation-trends.json`, not a live call.

```json
{
  "symbol": "AAPL",
  "trends": [
    {
      "symbol": "AAPL",
      "period": "2026-10-01",
      "strongBuy": 14,
      "buy": 24,
      "hold": 15,
      "sell": 2,
      "strongSell": 0
    },
    {
      "symbol": "AAPL",
      "period": "2026-09-01",
      "strongBuy": 14,
      "buy": 23,
      "hold": 16,
      "sell": 2,
      "strongSell": 0
    }
  ]
}
```

When the service answers with an error, the call fails with [`upstream_error`](/errors#upstream_error) and `pack_error.code` is one of:

| `pack_error.code` | Service status | Retryable | Message |
|---|---|---|---|
| `connection_unauthorized` | 401 | no | Finnhub rejected the API key; check the connection. |
| `forbidden` | 403 | no | This Finnhub endpoint or symbol is not included in your Finnhub plan. |
| `rate_limited` | 429 | yes | Finnhub rate limit reached for this API key; retry shortly. |
| `invalid_request` | 400, 422 | no | Finnhub rejected the request (check the symbol and dates). |

symbol-search

**Search Symbols.** Search Finnhub for securities (stocks, ETFs, crypto) by company name or ticker. Returns matching symbols with their display symbol, description, and type, best match first (default 10, max 50). Ideal for: resolving a company name to a ticker before fetching quotes/news/financials, ticker autocomplete.

Ref `io.b3os/finnhub/symbol-search@1.0.0` · effect `read` · connection `finnhub` · MCP tool `finnhub__symbol-search`

**curl**

```bash
    curl -s https://beta-api.b3os.org/v1/actions/call \
      -H "Authorization: Bearer $B3OS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
          "ref": "io.b3os/finnhub/symbol-search@1",
          "input": {"query": "apple", "limit": 2},
          "connections": {"finnhub": "conn_01m5t6cbgdjs1ketgcqwa2sne8"}
        }'
    ```
  **TypeScript**

```ts
    import { B3OS } from "@b3os/sdk";

    const b3os = new B3OS();
    const result = await b3os.actions.call({
      ref: "io.b3os/finnhub/symbol-search@1",
      input: { query: "apple", limit: 2 },
      connections: { finnhub: "conn_01m5t6cbgdjs1ketgcqwa2sne8" },
    });
    console.log(result.output);
    ```
  **Python**

```python
    from b3os import B3OS

    b3os = B3OS()
    result = b3os.actions.call({
        "ref": "io.b3os/finnhub/symbol-search@1",
        "input": {"query": "apple", "limit": 2},
        "connections": {"finnhub": "conn_01m5t6cbgdjs1ketgcqwa2sne8"},
    })
    print(result["output"])
    ```
  **MCP**

```json
    {
      "method": "tools/call",
      "params": {
        "name": "finnhub__symbol-search",
        "arguments": {"query": "apple", "limit": 2}
      }
    }
    ```

    Expose the pack as tools with `--packs finnhub` on the local server or `?packs=finnhub` on the remote URL, and the agent calls `finnhub__symbol-search` with the action's input. The tool uses your newest connection for each key without a `subject`. Without exposing the pack, `actions_call` takes the same input with `ref`.

Output, labeled `fixture`: Search Symbols (documented response shape, example values). From the bundle's `fixtures/symbol-search.json`, not a live call.

```json
{
  "query": "apple",
  "results": [
    {
      "symbol": "AAPL",
      "displaySymbol": "AAPL",
      "description": "APPLE INC",
      "type": "Common Stock"
    },
    {
      "symbol": "APLE",
      "displaySymbol": "APLE",
      "description": "APPLE HOSPITALITY REIT INC",
      "type": "Common Stock"
    }
  ],
  "count": 2
}
```

When the service answers with an error, the call fails with [`upstream_error`](/errors#upstream_error) and `pack_error.code` is one of:

| `pack_error.code` | Service status | Retryable | Message |
|---|---|---|---|
| `connection_unauthorized` | 401 | no | Finnhub rejected the API key; check the connection. |
| `forbidden` | 403 | no | This Finnhub endpoint or symbol is not included in your Finnhub plan. |
| `rate_limited` | 429 | yes | Finnhub rate limit reached for this API key; retry shortly. |
| `invalid_request` | 400, 422 | no | Finnhub rejected the request (check the symbol and dates). |