{"id":50727227,"url":"https://github.com/secapi-ai/secapi-js","last_synced_at":"2026-06-10T05:01:44.537Z","repository":{"id":359280847,"uuid":"1245149455","full_name":"secapi-ai/secapi-js","owner":"secapi-ai","description":"Official JavaScript and TypeScript SDK for SEC API","archived":false,"fork":false,"pushed_at":"2026-05-21T00:48:36.000Z","size":85,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-21T13:07:12.958Z","etag":null,"topics":["financial-data","javascript","sdk","sec-api","sec-edgar","typescript"],"latest_commit_sha":null,"homepage":"https://docs.secapi.ai","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/secapi-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-21T00:47:25.000Z","updated_at":"2026-05-21T00:48:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/secapi-ai/secapi-js","commit_stats":null,"previous_names":["secapi-ai/secapi-js"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/secapi-ai/secapi-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/secapi-ai%2Fsecapi-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/secapi-ai%2Fsecapi-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/secapi-ai%2Fsecapi-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/secapi-ai%2Fsecapi-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/secapi-ai","download_url":"https://codeload.github.com/secapi-ai/secapi-js/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/secapi-ai%2Fsecapi-js/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34137570,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["financial-data","javascript","sdk","sec-api","sec-edgar","typescript"],"created_at":"2026-06-10T05:01:43.636Z","updated_at":"2026-06-10T05:01:44.532Z","avatar_url":"https://github.com/secapi-ai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @secapi/sdk-js\n\nTypeScript and JavaScript SDK for [SEC API](https://secapi.ai/developers) -- SEC filings, financial statements, ownership data, and more. Legacy client names remain available for compatibility.\n\n## Installation\n\n```bash\nnpm install @secapi/sdk-js\n# or\npnpm add @secapi/sdk-js\n# or\nyarn add @secapi/sdk-js\n```\n\n## Configuration\n\nCreate a client instance with your API key:\n\n```ts\nimport { SecApiClient } from \"@secapi/sdk-js\"\n\nconst client = new SecApiClient({\n  apiKey: process.env.SECAPI_API_KEY ?? process.env.OMNI_DATASTREAM_API_KEY,\n  // Optional: override the base URL (defaults to https://api.secapi.ai)\n  // baseUrl: process.env.SECAPI_BASE_URL ?? process.env.SECAPI_API_BASE_URL ?? process.env.OMNI_DATASTREAM_BASE_URL,\n})\n```\n\nYou can also authenticate with a Bearer token instead of an API key:\n\n```ts\nconst client = new SecApiClient({\n  bearerToken: process.env.SECAPI_BEARER_TOKEN ?? process.env.OMNI_DATASTREAM_BEARER_TOKEN,\n})\n```\n\n### Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `SECAPI_API_KEY` | Preferred SEC API key env var |\n| `SECAPI_BEARER_TOKEN` | Preferred OAuth bearer token env var |\n| `SECAPI_BASE_URL` | Preferred base URL override |\n| `SECAPI_API_BASE_URL` | Preferred API base URL override alias |\n| `SECAPI_OPERATOR_API_KEY` | Preferred operator/admin API key env var |\n| `OMNI_DATASTREAM_API_KEY` | Legacy API key fallback |\n| `OMNI_DATASTREAM_BEARER_TOKEN` | Legacy OAuth bearer token fallback |\n| `OMNI_DATASTREAM_BASE_URL` | Legacy base URL fallback |\n\n## Reliability\n\nThe SDK retries transient failures with exponential backoff and jitter. Defaults:\n\n- Auto-retried by default: `GET`, `HEAD`, `OPTIONS`\n- Opt-in required: `POST`, `PUT`, `PATCH`, `DELETE`, MCP `tools/call`\n- Always retried regardless of method: `429` rate limits, with `Retry-After` honored\n- Retryable failures: network errors, `408`, `429`, `502`, `503`, `504`\n- Never retried: `400`, `401`, `403`, `404`, `422`\n- Backoff: base `200ms`, max `5s`, max retries `3`, total budget `30s`\n- Circuit breaker: opens after 5 consecutive retryable failures, cools down for 60s\n\nDisable retries globally if you already wrap the SDK with your own retry layer:\n\n```ts\nconst client = new SecApiClient({\n  apiKey: process.env.SECAPI_API_KEY ?? process.env.OMNI_DATASTREAM_API_KEY,\n  retry: false,\n})\n```\n\nPer-call overrides are supported:\n\n```ts\nawait client.latestFiling({ ticker: \"AAPL\", retry: false })\n\nawait client.createArtifact(\n  { kind: \"audit\", payload: { ticker: \"AAPL\" } },\n  { retry: { enabled: true, idempotencyKey: \"artifact-aapl-audit-2026-05-01\" } },\n)\n```\n\nOnly opt into retries for mutating requests when the operation is idempotent from your application's point of view. Provide an idempotency key so ambiguous network failures can be correlated safely.\n\nRetry telemetry emits anonymous `client_retry_attempt` events to SEC API's telemetry project. Set `telemetry: false` globally or per call to opt out.\n\n## Quickstart\n\n```ts\nimport { SecApiClient } from \"@secapi/sdk-js\"\n\nconst client = new SecApiClient({\n  apiKey: process.env.SECAPI_API_KEY ?? process.env.OMNI_DATASTREAM_API_KEY,\n})\n\n// Resolve a company entity\nconst entity = await client.resolveEntity({ ticker: \"AAPL\" })\nconsole.log(entity)\n\n// Get the latest 10-K filing\nconst filing = await client.latestFiling({ ticker: \"AAPL\", form: \"10-K\" })\nconsole.log(filing)\n\n// Extract a specific section from the filing\nconst section = await client.latestSection({\n  ticker: \"AAPL\",\n  form: \"10-K\",\n  sectionKey: \"item_1a\",\n  mode: \"compact\",\n})\nconsole.log(section)\n```\n\n## Common Use Cases\n\n### Financial Statements\n\n```ts\n// Get XBRL facts\nconst facts = await client.facts({ ticker: \"AAPL\", tag: \"Assets\", taxonomy: \"us-gaap\", limit: 5 })\n\n// Full financial statements\nconst statements = await client.allStatements({ ticker: \"AAPL\", period: \"annual\", limit: 3 })\n```\n\n### Ownership and Institutional Holdings\n\n```ts\n// Latest 13F filing (institutional holdings)\nconst holdings = await client.latest13f({ cik: \"0001067983\", limit: 10 })\n\n// Insider trades\nconst insiders = await client.insiderTrades({ ticker: \"AAPL\", limit: 10 })\n```\n\n### Market Data\n\n```ts\n// Market calendar\nconst calendar = await client.marketCalendar({ market: \"XNYS\", duration: 3 })\n\n// Volatility signal\nconst vol = await client.volatilitySignal({ ticker: \"AAPL\" })\n```\n\n## Error Handling\n\nAll API errors throw `SecApiError` with structured details. `OmniDatastreamError` remains an alias-compatible legacy export:\n\n```ts\nimport { SecApiClient, SecApiError } from \"@secapi/sdk-js\"\n\nconst client = new SecApiClient({\n  apiKey: process.env.SECAPI_API_KEY ?? process.env.OMNI_DATASTREAM_API_KEY,\n})\n\ntry {\n  await client.requestDiagnostics(\"missing-request-id\")\n} catch (error) {\n  if (error instanceof SecApiError) {\n    console.error(error.status, error.requestId, error.body)\n  }\n}\n```\n\n## MCP (Model Context Protocol) Usage\n\nThe SDK supports MCP-compatible tool invocation for AI agent workflows:\n\n```ts\n// Get available MCP tools\nconst mcpInfo = await client.mcpInfo()\nconsole.log(mcpInfo)\n\n// Invoke an MCP tool\nconst toolResult = await client.mcp({\n  jsonrpc: \"2.0\",\n  id: \"1\",\n  method: \"tools/call\",\n  params: {\n    name: \"entities.resolve\",\n    arguments: { ticker: \"AAPL\" },\n  },\n})\n```\n\nMCP tool calls use HTTP `POST`, so they are not retried on `502`/`503` by default. Opt in per call only when the tool is read-only or otherwise idempotent:\n\n```ts\nawait client.mcp(\n  {\n    jsonrpc: \"2.0\",\n    id: \"1\",\n    method: \"tools/call\",\n    params: { name: \"entities.resolve\", arguments: { ticker: \"AAPL\" } },\n  },\n  { retry: { enabled: true, idempotencyKey: \"mcp-entities-resolve-aapl\" } },\n)\n```\n\n## Runtime Validation\n\nAll responses are validated at runtime using Zod schemas. This ensures type safety even when consuming untyped API responses.\n\n## Links\n\n- [API Documentation](https://docs.secapi.ai)\n- [Developer Portal](https://secapi.ai/developers)\n- [GitHub Repository](https://github.com/autonomous-computer/omni-datastream)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsecapi-ai%2Fsecapi-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsecapi-ai%2Fsecapi-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsecapi-ai%2Fsecapi-js/lists"}