@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

| Runtime | REST | Streaming | Notes | | --- | :---: | :---: | --- | | Node.js >= 20 | ✅ | ✅ | Primary target. | | Bun | ✅ | ✅ | Node-compatible (ws runs). | | Deno | ✅ | ❌ | Root auto-resolves to the REST build via the deno export condition. | | Cloudflare Workers / workerd | ✅ | ❌ | Root auto-resolves to the REST build (workerd / worker). | | Vercel Edge | ✅ | ❌ | Root auto-resolves to the REST build (edge-light). | | Browser | ✅ | ❌ | Resolves to the REST build (browser). Not recommended — see caveat. |

Legend: ✅ supported · ❌ not supported.

• Streaming is Node/Bun only. The WebSocket 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 streaming-free REST build, so REST works and the stream factories (stockStream, stream, …) plus submitAndWait throw if called. For real-time 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();

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
• 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.