Alpaca Trade API JS

Trade IDs (especially in crypto) are 64-bit integers that can exceed JavaScript's safe integer range (2^53). To prevent data loss, canonical Trade records expose two ID fields:

• id: number: A convenient but potentially lossy representation for values past 2^53.
• idRaw?: string: The exact, lossless string representation. Use idRaw for comparing, storing, or using IDs as keys.

Warning on Raw Endpoints: If using raw generated models (e.g., alpaca.marketData.crypto.cryptoTrades(...).trades[sym][i].i), the ID may arrive as a string at runtime even if the type definition says number. It is highly recommended to use the canonical getCryptoTrades accessor instead.

const trades = await alpaca.marketData.getCryptoTrades({ symbols: "BTC/USD", loc: "us" });
const t = trades["BTC/USD"][0];
t.id;    // number — fine to display, lossy past 2^53
t.idRaw; // e.g. "8857581800245878123" — exact; use this to compare/store/key

Data Feeds

US-equity endpoints accept a feed parameter:

• iex: Free tier.
• sip: Paid tier (includes all US exchanges).
• otc, boats: Other available feeds.

Note on Defaults: For REST, if you omit feed, Alpaca selects the best feed your subscription allows. For streaming, the SDK defaults to feed: "iex" to ensure free keys work out of the box.

The 15-minute Rule (Free Plan)

On the free plan, SIP data for the last 15 minutes is restricted.

• If you explicitly request feed: "sip" with an end time defaulting to now, you will receive a 403 error.
• If using iex, the trailing ~15 minutes may be sparse or empty. To ensure data is present on the free tier, set your end parameter to at least 15 minutes in the past.

Paper vs Live

The paper flag only affects the trading host (paper-api vs api). It does not affect market data; all market-data REST and stream calls go to data.alpaca.markets regardless of your trading environment.

The marketDataShapes namespace provides a way to use the same data models for both historical REST data and real-time WebSocket streams. This allows you to backfill history and then append live updates to the same array without reconciling different object structures.

• REST models: Use compact wire keys (e.g., StockBar is { o, h, l, c, v, vw, n, t }).
• Streaming models: Use readable camelCase keys.
• marketDataShapes: Bridges these into a single canonical shape (e.g., Bar, Trade, Quote).

Normalized Accessors

The Alpaca client provides normalized accessors that return these canonical shapes automatically:

• getStockBars, getCryptoBars, getOptionBars
• getStockTrades, getCryptoTrades
• getStockQuotes, getCryptoQuotes
• getStockCandles, getCryptoCandles

For single-symbol requests, use the *For(symbol) variants (e.g., getStockBarsFor) to get the unwrapped value directly instead of a symbol-keyed map.

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

const alpaca = new Alpaca({ keyId, secret });

// 1. Fetch history as canonical Bars: { [symbol]: Bar[] }
const history = await alpaca.marketData.getStockBars({
  symbols: ["AAPL"], 
  timeframe: TimeFrame.Day, 
  start: new Date("2024-01-01"),
});

// 2. Live bars arrive in the SAME shape - just append them.
const stream = alpaca.marketData.stockStream({ feed: "iex" });
stream.onBar((bar) => history.AAPL?.push(bar)); // bar is a Bar
stream.onConnect(() => stream.subscribeForBars(["AAPL"]));
stream.connect();

Retry Semantics

• Automatic Retries: Enabled by default on the Alpaca client (1 initial + 2 retries). Raw Api classes require manual opt-in.
• Safe Verbs Only: Retries only occur for idempotent methods (GET, HEAD, OPTIONS, TRACE).
• Non-idempotent Methods: POST, PUT, PATCH, and DELETE are never auto-retried. This ensures order-placement POST requests are never replayed.
• Network Failures: Transient failures (DNS, connection reset, TLS) are retried for safe verbs. A deliberate AbortSignal or timeoutMs deadline is not retried.
• Backoff: Uses exponential backoff (doubling per attempt) starting from retryDelayMs up to maxDelayMs, with ±20% jitter. It honors the Retry-After header if present.

Order-Submission Safety

To prevent duplicate orders during ambiguous network failures, always provide a stable, unique clientOrderId.

Crucial Safety Step: If a FetchError occurs during a POST request, the outcome is ambiguous. Before retrying, call getOrderByClientOrderId({ clientOrderId }) to check if the order was actually accepted. Do not assume a lookup miss means the order failed.

const clientOrderId = `mean-reversion-${crypto.randomUUID()}`;
const order = await alpaca.trading.orders.market({
  symbol: "AAPL",
  qty: 1,
  side: "buy",
  clientOrderId,
});

The pipeline (src/run.ts) follows a strict sequence to ensure the generated code remains a 'frozen' and reproducible output:

1. Toolchain Setup: Downloads the pinned generator JAR and locates a working JDK.
2. Fetch & Diff: Fetches latest specs from docs.alpaca.markets, canonicalizes them, and performs a semantic diff against pinned specs. It detects added/removed/modified schemas and operations, as well as moved or renamed operations.
3. Confirm & Adopt: Prompts the user to overwrite pinned specs. --yes handles additive changes, but removals require --allow-breaking-spec-removals to prevent accidental breaking changes.
4. Derive: Applies JSON Patch overlays (found in overlays/) to the pinned spec to create the final generator input.
5. Generate: Executes openapi-generator using forked Mustache templates (found in templates/typescript-fetch/).
6. Cleanup: Removes stale files from apis/ and models/ that are no longer present in the new generator manifest.
7. Safety Gate: Runs typecheck, lint, test, and docs:api to ensure the new code is valid.
8. Orphan Report: Generates a report diffing apis/index.ts and models/index.ts to identify potential broken references in hand-written code (e.g., in src/client.ts, src/orders.ts, etc.).