@alpacahq/alpaca-trade-api

A Node.js TypeScript SDK for the Alpaca Trading API and Market Data API. Both APIs live under their own namespace (trading / marketData) in one package, fronted by a unified Alpaca client with typed errors, resilience (retry / timeout / rate limiting), pagination helpers, ergonomic order builders, and real-time streaming.

Upgrading from 3.x? See the migration guide (also on the docs site) — it maps common 3.x calls and workflows to their 4.x equivalents and ships a codemod that automates most of the work.

Requirements

• SDK consumers: Node.js >= 20 — the REST transport uses the platform-global fetch, Headers, URL, and AbortController. (Node 18 reached end-of-life in April 2025; the package declares engines.node >=20.)
• Repository contributors: Node.js >= 24 (see .nvmrc). Build, docs, generation, and release tooling run on Node 24; CI separately executes the packed SDK on Node 20 to preserve the consumer compatibility floor.
• Strict Node TypeScript projects may omit DOM libs; the REST declarations are portable and do not require "dom" in the consumer tsconfig.

Runtime compatibility

Legend: ✅ supported · ❌ not supported.

• WebSocket streaming is Node/Bun only. Those clients use Node-compatible streaming modules, which don't run on edge or in the browser. On those targets the package's export conditions transparently resolve the root import to the WebSocket-free REST build, so REST and fetch-based SSE work while the stream factories (stockStream, stream, …) plus submitAndWait throw if called. For WebSocket streaming, run on Node or Bun.
• Browser: technically works, but discouraged. Calling Alpaca directly from a browser ships your APCA_API_SECRET_KEY to the client. Prefer a server or proxy (see examples/marketdata-backend.ts) rather than embedding credentials in front-end code.

ESM and CJS module formats, edge export conditions, and the REST-only entrypoint are documented on the docs site: Runtime & module compatibility.

Install

npm install @alpacahq/alpaca-trade-api

Quick start

import { Alpaca } from "@alpacahq/alpaca-trade-api";

const alpaca = new Alpaca({
  keyId: process.env.APCA_API_KEY_ID,
  secret: process.env.APCA_API_SECRET_KEY,
  paper: true, // default; set false for live trading
});

const account = await alpaca.trading.account.getAccount();
const price = await alpaca.marketData.getLatestPrice("AAPL");

const bars = alpaca.marketData.stockStream({ feed: "iex" });
bars.onBar((b) => console.log(b.symbol, b.close));
bars.onConnect(() => bars.subscribeForBars(["AAPL", "MSFT"]));
bars.connect();

Server-Sent Events

The facade provides typed async SSE subscriptions with cancellation, reconnection, and Last-Event-ID resumption:

const controller = new AbortController();
const activities = await alpaca.trading.subscribeActivities(
  {},
  { signal: controller.signal },
);

try {
  for await (const activity of activities) {
    console.log(activity.activityType, activity.details);
  }
} finally {
  activities.close();
}

Corporate-action mutations are available from alpaca.marketData.subscribeCorporateActions(). The longer generated operation names remain available under trading.events and marketData.corporateActions; see the streaming guide.

Documentation

The documentation site is the canonical source for workflows, conventions, and curated API discovery. Installed TypeScript declarations remain authoritative for exact signatures and models. Key guides:

• Getting started
• Trading
• Market data
• Streaming
• Authentication
• Resilience & configuration
• Pagination
• Values & types
• Testing your integration
• Runtime & module compatibility
• Examples
• Migration from 3.x
• Migration overview
• Migration from 4.x to 5.0
• API reference
• AI coding guidance — choose either equivalent format:
  • Read the packaged LLMS.md.
  • Install the Agent Skill: npx skills add alpacahq/alpaca-trade-api-js (agentskills.io).

Build from source

npm install      # also builds via the `prepare` script
npm run build    # tsup -> dual ESM + CJS in dist/
npm run typecheck
npm run lint
npm test

Runnable examples live in examples/. To preview the docs site locally:

npm --prefix docs install   # first time only
npm --prefix docs start     # http://localhost:3000/alpaca-trade-api-js/

Releases

Stable versions are published to npm on the latest dist-tag. See CHANGELOG.md for release notes.

Support

• Library / SDK issues: Bugs, feature requests, or questions specific to this TypeScript library → GitHub Issues.
• General Alpaca support & API discussion: Account questions, platform issues, or broader API topics → Alpaca Community Forum.
• Slack community: Chat with other developers and the Alpaca community on Slack.

Contributing

Contributions are welcome. See CONTRIBUTING.md for setup, generated-code boundaries, documentation workflow, and release notes conventions.