sentisense

Official JavaScript/TypeScript SDK for the SentiSense market intelligence API.

Install

npm install sentisense

Quick Start

import SentiSense from "sentisense";

const client = new SentiSense({ apiKey: "ss_live_YOUR_KEY" });

const price = await client.stocks.getPrice("AAPL");
console.log(price.currentPrice);

const flows = await client.institutional.getFlows("2025-02-14");

Features

• Full TypeScript support with detailed type definitions
• Works in Node.js 18+, Deno, Bun, and browsers
• Zero runtime dependencies (uses native fetch)
• Namespaced API resources (stocks, documents, institutional, etc.)
• Typed error hierarchy for clean error handling

API Reference

Stocks

client.stocks.list()                                    // All ticker symbols
client.stocks.listDetailed()                            // All stocks with details
client.stocks.getPrice("AAPL")                          // Real-time price
client.stocks.getPrices(["AAPL", "NVDA"])               // Batch prices
client.stocks.getProfile("AAPL")                        // Company profile
client.stocks.getChart("AAPL", { timeframe: "6M" })     // OHLCV chart data
client.stocks.getMarketStatus()                         // Market open/closed
client.stocks.getFundamentals("AAPL")                   // Financial data
client.stocks.getShortInterest("GME")                   // Short interest
client.stocks.getAISummary("AAPL", { depth: "deep" })   // AI report (PRO)

Documents & News

client.documents.getByTicker("AAPL", { source: "news", days: 3 })
client.documents.search("NVDA earnings", { days: 7, limit: 20 })
client.documents.getStories({ limit: 10, expanded: true })
client.documents.getStory("cluster_abc123")

Institutional Flows (13F)

client.institutional.getQuarters()
client.institutional.getFlows("2025-02-14", { limit: 20 })
client.institutional.getHolders("AAPL", "2025-02-14")
client.institutional.getActivists("2025-02-14")

Entity Metrics

// Time-series metrics (v2 API)
client.entityMetrics.getMetrics("AAPL", { metricType: "sentiment" })
client.entityMetrics.getMetrics("AAPL", {
  metricType: "mentions",
  startTime: Date.now() - 7 * 86400000,
  endTime: Date.now(),
  maxDataPoints: 100,
})

// Distribution by source
client.entityMetrics.getDistribution("AAPL", "sentiment")
client.entityMetrics.getDistribution("AAPL", "mentions", { dimension: "source" })

Available metric types: mentions, sentiment, sentisense, social_dominance, creators.

Knowledge Base

client.kb.getPopularEntities()
client.kb.getEntity("entity-id")
client.kb.getAllEntities()

Analyst Ratings

The price target cone (mean, high, low, upside %) and consensus are free for everyone, full data via API — we give it away. Upgrade/downgrade feeds and forward EPS estimates are limited on free, unlimited on PRO.

client.analyst.consensus("AAPL")                        // Price target cone + consensus. Free for everyone, full data.
client.analyst.actions("AAPL", { lookbackDays: 30 })    // Upgrade/downgrade feed. Free: 3 most recent. PRO: unlimited.
client.analyst.estimates("AAPL")                        // Forward EPS + earnings surprises. Free: 1 quarter. PRO: full history.
client.analyst.marketActivity({ lookbackDays: 7 })      // Market-wide analyst actions (PRO).

Company KPIs (PRO)

client.stocks.getKpis("AAPL")       // Product metrics and segment revenue time-series. Free returns metadata only (empty kpis array); PRO returns full series.
client.stocks.listKpiCoverage()     // All tickers with curated KPI data (free, no quota cost)

ETFs (beta)

Composition data is public; the holdings-weighted aggregate views follow the same PRO-with-preview pattern as Analyst/Insider. Aggregates synthesize fund-level views from each constituent's per-stock data, weighted by allocation, with a coverage block on every response.

client.etfs.list()                                              // Every ETF tracked. Returns ticker, name, issuer, tracked index, asset class.
client.etfs.holdings("QQQ")                                     // Full composition: per-holding weights + freshness metadata.
client.etfs.analystAggregate("QQQ")                             // Holdings-weighted analyst consensus. Free: headline + coverage. PRO: + topContributors.
client.etfs.insiderAggregate("ARKK", { lookbackDays: 90 })      // Holdings-weighted Form 4 net flow. Free: headline. PRO: + topContributors.
client.etfs.sentimentAggregate("QQQ")                           // SentiSense readings side-by-side: constituent-weighted vs direct.

Market Mood

client.marketMood.get()

Error Handling

import SentiSense, { AuthenticationError, RateLimitError } from "sentisense";

try {
  const summary = await client.stocks.getAISummary("AAPL");
} catch (error) {
  if (error instanceof AuthenticationError) {
    // 401 or 403 — invalid/missing API key or insufficient tier
  } else if (error instanceof RateLimitError) {
    // 429 — quota exceeded
  }
}

| Error Class | HTTP Status | When | |------------|-------------|------| | AuthenticationError | 401, 403 | Invalid API key or insufficient tier | | NotFoundError | 404 | Resource not found | | RateLimitError | 429 | Quota exceeded | | APIError | Other 4xx/5xx | General API error |

All errors extend SentiSenseError and include status, code, and message properties.

Configuration

const client = new SentiSense({
  apiKey: "ss_live_YOUR_KEY",  // Get yours at app.sentisense.ai/settings/developer
  baseUrl: "https://...",      // Default: https://app.sentisense.ai
  timeout: 30000,              // Default: 30s (in milliseconds)
});

Get an API Key

Generate your API key from the Developer Console.

For full API documentation, see sentisense.ai/docs/api.

License

MIT