@omni-datastream/sdk-js

TypeScript and JavaScript SDK for Omni Datastream -- SEC filings, financial statements, ownership data, and more.

Installation

npm install @omni-datastream/sdk-js
# or
pnpm add @omni-datastream/sdk-js
# or
yarn add @omni-datastream/sdk-js

Configuration

Create a client instance with your API key:

import { OmniDatastreamClient } from "@omni-datastream/sdk-js"

const client = new OmniDatastreamClient({
  apiKey: process.env.OMNI_DATASTREAM_API_KEY,
  // Optional: override the base URL (defaults to https://api.secapi.ai)
  // baseUrl: "http://127.0.0.1:8787",
})

You can also authenticate with a Bearer token instead of an API key:

const client = new OmniDatastreamClient({
  bearerToken: process.env.OMNI_DATASTREAM_BEARER_TOKEN,
})

Environment Variables

| Variable | Description | |----------|-------------| | OMNI_DATASTREAM_API_KEY | Your Omni Datastream API key (starts with ods_) | | OMNI_DATASTREAM_BEARER_TOKEN | Alternative: OAuth bearer token |

Quickstart

import { OmniDatastreamClient } from "@omni-datastream/sdk-js"

const client = new OmniDatastreamClient({
  apiKey: process.env.OMNI_DATASTREAM_API_KEY,
})

// Resolve a company entity
const entity = await client.resolveEntity({ ticker: "AAPL" })
console.log(entity)

// Get the latest 10-K filing
const filing = await client.latestFiling({ ticker: "AAPL", form: "10-K" })
console.log(filing)

// Extract a specific section from the filing
const section = await client.latestSection({
  ticker: "AAPL",
  form: "10-K",
  sectionKey: "item_1a",
  mode: "compact",
})
console.log(section)

Common Use Cases

Financial Statements

// Get XBRL facts
const facts = await client.facts({ ticker: "AAPL", tag: "Assets", taxonomy: "us-gaap", limit: 5 })

// Full financial statements
const statements = await client.allStatements({ ticker: "AAPL", period: "annual", limit: 3 })

Ownership and Institutional Holdings

// Latest 13F filing (institutional holdings)
const holdings = await client.latest13f({ cik: "0001067983", limit: 10 })

// Insider trades
const insiders = await client.insiderTrades({ ticker: "AAPL", limit: 10 })

Market Data

// Market calendar
const calendar = await client.marketCalendar({ market: "XNYS", duration: 3 })

// Volatility signal
const vol = await client.volatilitySignal({ ticker: "AAPL" })

Error Handling

All API errors throw OmniDatastreamError with structured details:

import { OmniDatastreamClient, OmniDatastreamError } from "@omni-datastream/sdk-js"

const client = new OmniDatastreamClient({
  apiKey: process.env.OMNI_DATASTREAM_API_KEY,
})

try {
  await client.requestDiagnostics("missing-request-id")
} catch (error) {
  if (error instanceof OmniDatastreamError) {
    console.error(error.status, error.requestId, error.body)
  }
}

MCP (Model Context Protocol) Usage

The SDK supports MCP-compatible tool invocation for AI agent workflows:

// Get available MCP tools
const mcpInfo = await client.mcpInfo()
console.log(mcpInfo)

// Invoke an MCP tool
const toolResult = await client.mcp({
  jsonrpc: "2.0",
  id: "1",
  method: "tools/call",
  params: {
    name: "entities.resolve",
    arguments: { ticker: "AAPL" },
  },
})

Runtime Validation

All responses are validated at runtime using Zod schemas. This ensures type safety even when consuming untyped API responses.

Links

• API Documentation
• Developer Portal
• GitHub Repository