The Alpaca JavaScript/TypeScript SDK for the 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.
- SDK consumers: Node.js >= 20 — the REST transport uses the platform-global
fetch,Headers,URL, andAbortController, and the package declaresengines.node >=20. Node.js 20 reached end-of-life in April 2026. The SDK remains compatible with Node.js 20, but CI no longer executes that EOL runtime. We recommend upgrading to a currently supported Node.js LTS release to continue receiving security fixes. - Repository contributors: Node.js
>=24.22.1 <25(.nvmrcpins that minimum locally). Build, docs, generation, release tooling, and CI resolve the latest available Node.js 24 patch above that security floor. The published SDK keeps its Node.js >= 20 compatibility contract. - Strict Node TypeScript projects may omit DOM libs; the REST declarations are
portable and do not require
"dom"in the consumertsconfig.
| Runtime | REST / fetch-based SSE | WebSockets | Notes |
|---|---|---|---|
| Node.js >= 20 | ✅ | ✅ | Compatibility floor; Node.js 20 is EOL. |
| 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.
- 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, …) plussubmitAndWaitthrow 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_KEYto the client. Prefer a server or proxy (seeexamples/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.
npm install @alpacahq/alpaca-trade-apiimport { 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();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.
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).
npm install # also builds via the `prepare` script
npm run build # tsup -> dual ESM + CJS in dist/
npm run typecheck
npm run lint
npm testRunnable 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/Stable versions are published to npm on the latest dist-tag. See
CHANGELOG.md
for release notes.
- Library / SDK issues: Bugs, feature requests, or questions specific to this SDK → GitHub Issues.
- Security vulnerabilities: Do not report them publicly. Follow our Security Policy.
- Alpaca API bugs: Bugs in the Alpaca API itself, its OpenAPI specs, or its documentation → alpacahq/alpaca-api.
- Community: API feature requests, general questions, and dashboard bugs → Alpaca Community Forum or Slack.
- Account help: Questions about your account, funding, or orders → Support request.
- Outages: Service status and incident updates → Status page.
Contributions are welcome. See CONTRIBUTING.md for setup, contribution scope, generated-code boundaries, quality requirements, and the pull-request workflow. Participation is governed by our Code of Conduct.
