Skip to main content

Ergonomic helpers

alpaca.trading.orders — order builders​

One typed builder per order kind; drops the postOrder wrapper and enforces required fields at compile time.

alpaca.trading.orders.market​

Place one market order (exactly one of qty/notional) with a client ID for audit and recovery.

const clientOrderId = crypto.randomUUID();
await alpaca.trading.orders.market({ symbol: "AAPL", side: "buy", qty: 1, clientOrderId });
alpaca.trading.orders.limit​

Place one limit order with a stable, unique client ID.

const clientOrderId = crypto.randomUUID();
await alpaca.trading.orders.limit({ symbol: "AAPL", side: "buy", qty: 1, limitPrice: 150, clientOrderId });
alpaca.trading.orders.stop​

Place one stop (stop-market) order with a stable, unique client ID.

const clientOrderId = crypto.randomUUID();
await alpaca.trading.orders.stop({ symbol: "AAPL", side: "sell", qty: 1, stopPrice: 140, clientOrderId });
alpaca.trading.orders.stopLimit​

Place one stop-limit order with a stable, unique client ID.

const clientOrderId = crypto.randomUUID();
await alpaca.trading.orders.stopLimit({ symbol: "AAPL", side: "sell", qty: 1, stopPrice: 140, limitPrice: 139, clientOrderId });
alpaca.trading.orders.trailingStop​

Place one trailing-stop order (one of trailPrice/trailPercent) with a stable, unique client ID.

const clientOrderId = crypto.randomUUID();
await alpaca.trading.orders.trailingStop({ symbol: "AAPL", side: "sell", qty: 1, trailPercent: 5, clientOrderId });
alpaca.trading.orders.bracket​

Place one bracket order (entry plus take-profit and stop-loss legs) with a stable, unique client ID.

const clientOrderId = crypto.randomUUID();
await alpaca.trading.orders.bracket({ symbol: "AAPL", side: "buy", qty: 1, takeProfit: { limitPrice: 160 }, stopLoss: { stopPrice: 140 }, clientOrderId });
alpaca.trading.orders.oco​

Place one one-cancels-other order on a held position with a stable, unique client ID.

const clientOrderId = crypto.randomUUID();
await alpaca.trading.orders.oco({ symbol: "AAPL", side: "sell", qty: 1, takeProfit: { limitPrice: 160 }, stopLoss: { stopPrice: 140 }, clientOrderId });
alpaca.trading.orders.oto​

Place one one-triggers-other order with a stable, unique client ID.

const clientOrderId = crypto.randomUUID();
await alpaca.trading.orders.oto({ symbol: "AAPL", side: "buy", qty: 1, limitPrice: 150, takeProfit: { limitPrice: 160 }, clientOrderId });
alpaca.trading.orders.submit​

Place one near-raw order shape; include a stable, unique client ID and reconcile transport ambiguity explicitly.

const clientOrderId = crypto.randomUUID();
await alpaca.trading.orders.submit({ type: "market", symbol: "AAPL", side: "buy", qty: 1, clientOrderId });

alpaca.trading — workflow helpers​

High-level trading flows that would otherwise be boilerplate.

alpaca.trading.validateConnection​

Verify credentials/connectivity without throwing; returns { ok, account } or { ok: false, status, code, message }.

const check = await alpaca.trading.validateConnection();
alpaca.trading.submitAndWait​

After server listening acknowledgement, place once and await a terminal update under one workflow deadline.

const clientOrderId = crypto.randomUUID();
const terminalOrder = await alpaca.trading.submitAndWait({ type: "market", symbol: "AAPL", side: "buy", qty: 1, clientOrderId }, { timeoutMs: 30_000 });
if (terminalOrder.status === "filled") console.log(terminalOrder.filledAvgPrice);
alpaca.trading.closeAllPositions​

Close every open position (optionally cancel open orders first).

await alpaca.trading.closeAllPositions({ cancelOrders: true });

alpaca.trading — pagination helpers​

Auto-paginated iterate/collect helpers for option contracts and account activities.

alpaca.trading.iterateOptionsContracts​

Lazily yield option contracts across all pages.

for await (const contract of alpaca.trading.iterateOptionsContracts({
  underlyingSymbols: "AAPL",
})) console.log(contract.symbol);
alpaca.trading.collectOptionsContracts​

Eagerly collect all option contracts across pages into one array.

const contracts = await alpaca.trading.collectOptionsContracts({
  underlyingSymbols: "AAPL",
});
alpaca.trading.iterateActivities​

Lazily yield account activities across all pages.

for await (const activity of alpaca.trading.iterateActivities({
  activityTypes: ["FILL"],
})) console.log(activity.id);
alpaca.trading.collectActivities​

Eagerly collect all account activities across pages into one array.

const activities = await alpaca.trading.collectActivities({
  activityTypes: ["FILL"],
});
alpaca.trading.iterateActivitiesByType​

Lazily yield activities of a single type across all pages.

for await (const fill of alpaca.trading.iterateActivitiesByType({
  activityType: "FILL",
})) console.log(fill.id);
alpaca.trading.collectActivitiesByType​

Eagerly collect activities of a single type into one array.

const fills = await alpaca.trading.collectActivitiesByType({
  activityType: "FILL",
});

alpaca.marketData — workflow helpers​

High-level market-data flows that would otherwise be boilerplate.

alpaca.marketData.getLatestPrice​

Latest trade price for a symbol as a number (or undefined).

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

alpaca.marketData — normalized accessors​

Auto-paginated, symbol-keyed accessors returning canonical Bar/Trade/Quote shapes (and chart-ready Candles), unified with the streaming layer. Each single-symbol *For(symbol) reads only the exact requested key and returns an empty array/Candles when absent.

alpaca.marketData.getStockBars​

Historical stock bars as canonical Bars, auto-paginated and keyed by symbol.

const bars = await alpaca.marketData.getStockBars({
  symbols: ["AAPL"],
  timeframe: TimeFrame.Day,
  start: new Date("2024-01-01"),
});
alpaca.marketData.getCryptoBars​

Historical crypto bars as canonical Bars, keyed by symbol.

const bars = await alpaca.marketData.getCryptoBars({
  loc: "us",
  symbols: ["BTC/USD"],
  timeframe: TimeFrame.Day,
  start: new Date("2024-01-01"),
});
alpaca.marketData.getOptionBars​

Historical option bars as canonical Bars, keyed by symbol.

const bars = await alpaca.marketData.getOptionBars({
  symbols: ["AAPL250117C00150000"],
  timeframe: TimeFrame.Day,
  start: new Date("2024-01-01"),
});
alpaca.marketData.getStockTrades​

Historical stock trades as canonical Trades, keyed by symbol.

const trades = await alpaca.marketData.getStockTrades({
  symbols: ["AAPL"],
  start: new Date("2024-01-02"),
});
alpaca.marketData.getCryptoTrades​

Historical crypto trades as canonical Trades, keyed by symbol.

const trades = await alpaca.marketData.getCryptoTrades({
  loc: "us",
  symbols: ["BTC/USD"],
  start: new Date("2024-01-02"),
});
alpaca.marketData.getStockQuotes​

Historical stock quotes as canonical Quotes, keyed by symbol.

const quotes = await alpaca.marketData.getStockQuotes({
  symbols: ["AAPL"],
  start: new Date("2024-01-02"),
});
alpaca.marketData.getCryptoQuotes​

Historical crypto quotes as canonical Quotes, keyed by symbol.

const quotes = await alpaca.marketData.getCryptoQuotes({
  loc: "us",
  symbols: ["BTC/USD"],
  start: new Date("2024-01-02"),
});
alpaca.marketData.getIndexValues​

Historical index values as canonical IndexValues (with full-precision timestampRaw), keyed by symbol.

const values = await alpaca.marketData.getIndexValues({
  symbols: ["SPX"],
  start: new Date("2024-01-02"),
});
alpaca.marketData.getStockAuctions​

Historical stock auctions as canonical DailyAuctions (each print with full-precision timestampRaw), keyed by symbol.

const auctions = await alpaca.marketData.getStockAuctions({
  symbols: ["AAPL"],
  start: new Date("2024-01-02"),
});
alpaca.marketData.getStockCandles​

Historical stock bars as chart-ready columnar Candles, keyed by symbol.

const candles = await alpaca.marketData.getStockCandles({
  symbols: ["AAPL"],
  timeframe: TimeFrame.Day,
  start: new Date("2024-01-01"),
});
alpaca.marketData.getCryptoCandles​

Historical crypto bars as chart-ready columnar Candles, keyed by symbol.

const candles = await alpaca.marketData.getCryptoCandles({
  loc: "us",
  symbols: ["BTC/USD"],
  timeframe: TimeFrame.Day,
  start: new Date("2024-01-01"),
});
alpaca.marketData.getStockBarsFor​

Exact-key stock bars as canonical Bar[]; returns [] when the requested symbol is absent.

const bars = await alpaca.marketData.getStockBarsFor("AAPL", { timeframe: TimeFrame.Day, start: new Date("2024-01-01") });
alpaca.marketData.getCryptoBarsFor​

Exact-key crypto bars as canonical Bar[]; returns [] when the requested pair is absent.

const bars = await alpaca.marketData.getCryptoBarsFor("BTC/USD", { loc: "us", timeframe: TimeFrame.Day, start: new Date("2024-01-01") });
alpaca.marketData.getOptionBarsFor​

Exact-key option bars as canonical Bar[]; returns [] when the requested contract is absent.

const bars = await alpaca.marketData.getOptionBarsFor("AAPL250117C00150000", { timeframe: TimeFrame.Day, start: new Date("2024-01-01") });
alpaca.marketData.getStockTradesFor​

Exact-key stock trades as canonical Trade[]; never substitutes another symbol.

const trades = await alpaca.marketData.getStockTradesFor("AAPL", { start: new Date("2024-01-02") });
alpaca.marketData.getCryptoTradesFor​

Exact-key crypto trades as canonical Trade[]; never substitutes another pair.

const trades = await alpaca.marketData.getCryptoTradesFor("BTC/USD", { loc: "us", start: new Date("2024-01-02") });
alpaca.marketData.getStockQuotesFor​

Exact-key stock quotes as canonical Quote[]; never substitutes another symbol.

const quotes = await alpaca.marketData.getStockQuotesFor("AAPL", { start: new Date("2024-01-02") });
alpaca.marketData.getCryptoQuotesFor​

Exact-key crypto quotes as canonical Quote[]; never substitutes another pair.

const quotes = await alpaca.marketData.getCryptoQuotesFor("BTC/USD", { loc: "us", start: new Date("2024-01-02") });
alpaca.marketData.getStockCandlesFor​

Exact-key stock Candles; returns empty columns when the requested symbol is absent.

const candles = await alpaca.marketData.getStockCandlesFor("AAPL", { timeframe: TimeFrame.Day, start: new Date("2024-01-01") });
alpaca.marketData.getCryptoCandlesFor​

Exact-key crypto Candles; returns empty columns when the requested pair is absent.

const candles = await alpaca.marketData.getCryptoCandlesFor("BTC/USD", { loc: "us", timeframe: TimeFrame.Day, start: new Date("2024-01-01") });

alpaca.marketData — pagination helpers​

Auto-paginated iterate/collect helpers across every paginated market-data endpoint; the page token is managed for you and any revisited token stops traversal.

alpaca.marketData.iterateStockBars​

Lazily yield { symbol, value } stock-bar records across symbols and pages.

for await (const { symbol, value } of alpaca.marketData.iterateStockBars({
  symbols: ["AAPL"],
  timeframe: TimeFrame.Day,
  start: new Date("2024-01-01"),
})) console.log(symbol, value.c);
alpaca.marketData.collectStockBarsBySymbol​

Collect stock bars merged into a { [symbol]: StockBar[] } map.

const bySymbol = await alpaca.marketData.collectStockBarsBySymbol({
  symbols: ["AAPL", "MSFT"],
  timeframe: TimeFrame.Day,
  start: new Date("2024-01-01"),
});
alpaca.marketData.iterateStockTrades​

Lazily yield stock-trade records across symbols and pages.

for await (const { symbol, value } of alpaca.marketData.iterateStockTrades({
  symbols: ["AAPL"],
  start: new Date("2024-01-02"),
})) console.log(symbol, value.p);
alpaca.marketData.collectStockTradesBySymbol​

Collect stock trades merged into a { [symbol]: StockTrade[] } map.

const bySymbol = await alpaca.marketData.collectStockTradesBySymbol({
  symbols: ["AAPL"],
  start: new Date("2024-01-02"),
});
alpaca.marketData.iterateStockQuotes​

Lazily yield stock-quote records across symbols and pages.

for await (const { symbol, value } of alpaca.marketData.iterateStockQuotes({
  symbols: ["AAPL"],
  start: new Date("2024-01-02"),
})) console.log(symbol, value.bp);
alpaca.marketData.collectStockQuotesBySymbol​

Collect stock quotes merged into a { [symbol]: StockQuote[] } map.

const bySymbol = await alpaca.marketData.collectStockQuotesBySymbol({
  symbols: ["AAPL"],
  start: new Date("2024-01-02"),
});
alpaca.marketData.iterateStockAuctions​

Lazily yield daily-auction records across symbols and pages.

for await (const { symbol, value } of alpaca.marketData.iterateStockAuctions({
  symbols: ["AAPL"],
  start: new Date("2024-01-02"),
})) console.log(symbol, value.d);
alpaca.marketData.collectStockAuctionsBySymbol​

Collect stock auctions merged into a { [symbol]: StockDailyAuctions[] } map.

const bySymbol = await alpaca.marketData.collectStockAuctionsBySymbol({
  symbols: ["AAPL"],
  start: new Date("2024-01-02"),
});
alpaca.marketData.iterateCryptoBars​

Lazily yield crypto-bar records across symbols and pages.

for await (const { symbol, value } of alpaca.marketData.iterateCryptoBars({
  loc: "us",
  symbols: ["BTC/USD"],
  timeframe: TimeFrame.Day,
  start: new Date("2024-01-01"),
})) console.log(symbol, value.c);
alpaca.marketData.collectCryptoBarsBySymbol​

Collect crypto bars merged into a { [symbol]: CryptoBar[] } map.

const bySymbol = await alpaca.marketData.collectCryptoBarsBySymbol({
  loc: "us",
  symbols: ["BTC/USD"],
  timeframe: TimeFrame.Day,
  start: new Date("2024-01-01"),
});
alpaca.marketData.iterateCryptoTrades​

Lazily yield crypto-trade records across symbols and pages.

for await (const { symbol, value } of alpaca.marketData.iterateCryptoTrades({
  loc: "us",
  symbols: ["BTC/USD"],
  start: new Date("2024-01-02"),
})) console.log(symbol, value.p);
alpaca.marketData.collectCryptoTradesBySymbol​

Collect crypto trades merged into a { [symbol]: CryptoTrade[] } map.

const bySymbol = await alpaca.marketData.collectCryptoTradesBySymbol({
  loc: "us",
  symbols: ["BTC/USD"],
  start: new Date("2024-01-02"),
});
alpaca.marketData.iterateCryptoQuotes​

Lazily yield crypto-quote records across symbols and pages.

for await (const { symbol, value } of alpaca.marketData.iterateCryptoQuotes({
  loc: "us",
  symbols: ["BTC/USD"],
  start: new Date("2024-01-02"),
})) console.log(symbol, value.bp);
alpaca.marketData.collectCryptoQuotesBySymbol​

Collect crypto quotes merged into a { [symbol]: CryptoQuote[] } map.

const bySymbol = await alpaca.marketData.collectCryptoQuotesBySymbol({
  loc: "us",
  symbols: ["BTC/USD"],
  start: new Date("2024-01-02"),
});
alpaca.marketData.iterateOptionBars​

Lazily yield option-bar records across symbols and pages.

for await (const { symbol, value } of alpaca.marketData.iterateOptionBars({
  symbols: ["AAPL250117C00150000"],
  timeframe: TimeFrame.Day,
  start: new Date("2024-01-01"),
})) console.log(symbol, value.c);
alpaca.marketData.collectOptionBarsBySymbol​

Collect option bars merged into a { [symbol]: OptionBar[] } map.

const bySymbol = await alpaca.marketData.collectOptionBarsBySymbol({
  symbols: ["AAPL250117C00150000"],
  timeframe: TimeFrame.Day,
  start: new Date("2024-01-01"),
});
alpaca.marketData.iterateOptionTrades​

Lazily yield option-trade records across symbols and pages.

for await (const { symbol, value } of alpaca.marketData.iterateOptionTrades({
  symbols: ["AAPL250117C00150000"],
  start: new Date("2024-01-02"),
})) console.log(symbol, value.p);
alpaca.marketData.collectOptionTradesBySymbol​

Collect option trades merged into a { [symbol]: OptionTrade[] } map.

const bySymbol = await alpaca.marketData.collectOptionTradesBySymbol({
  symbols: ["AAPL250117C00150000"],
  start: new Date("2024-01-02"),
});
alpaca.marketData.iterateIndexValues​

Lazily yield index-value records across symbols and pages.

for await (const { symbol, value } of alpaca.marketData.iterateIndexValues({
  symbols: ["SPX"],
  start: new Date("2024-01-01"),
})) console.log(symbol, value);
alpaca.marketData.collectIndexValuesBySymbol​

Collect index values merged into a { [symbol]: IndexValue[] } map.

const bySymbol = await alpaca.marketData.collectIndexValuesBySymbol({
  symbols: ["SPX"],
  start: new Date("2024-01-01"),
});
alpaca.marketData.iterateForexRates​

Lazily yield forex-rate records across currency pairs and pages.

for await (const { symbol, value } of alpaca.marketData.iterateForexRates({
  currencyPairs: ["EUR/USD"],
  start: new Date("2024-01-01"),
})) console.log(symbol, value);
alpaca.marketData.collectForexRatesBySymbol​

Collect forex rates merged into a { [pair]: ForexRate[] } map.

const byPair = await alpaca.marketData.collectForexRatesBySymbol({
  currencyPairs: ["EUR/USD"],
  start: new Date("2024-01-01"),
});
alpaca.marketData.iterateOptionSnapshots​

Lazily yield { symbol, value } option-snapshot records across symbols and pages.

for await (const { symbol, value } of alpaca.marketData.iterateOptionSnapshots({
  symbols: ["AAPL250117C00150000"],
})) console.log(symbol, value);
alpaca.marketData.collectOptionSnapshotsBySymbol​

Collect option snapshots into a { [symbol]: OptionSnapshot } map.

const bySymbol = await alpaca.marketData.collectOptionSnapshotsBySymbol({
  symbols: ["AAPL250117C00150000"],
});
alpaca.marketData.iterateOptionChain​

Lazily yield an underlying's option-chain snapshots across symbols and pages.

for await (const { symbol, value } of alpaca.marketData.iterateOptionChain({
  underlyingSymbol: "AAPL",
})) console.log(symbol, value);
alpaca.marketData.collectOptionChainBySymbol​

Collect an option chain's snapshots into a { [symbol]: OptionSnapshot } map.

const chain = await alpaca.marketData.collectOptionChainBySymbol({
  underlyingSymbol: "AAPL",
});
alpaca.marketData.iterateStockBarSingle​

Lazily yield a single symbol's stock bars across all pages.

for await (const bar of alpaca.marketData.iterateStockBarSingle({
  symbol: "AAPL",
  timeframe: TimeFrame.Day,
  start: new Date("2024-01-01"),
})) console.log(bar.c);
alpaca.marketData.collectStockBarSingle​

Collect a single symbol's stock bars into one StockBar[] array.

const bars = await alpaca.marketData.collectStockBarSingle({
  symbol: "AAPL",
  timeframe: TimeFrame.Day,
  start: new Date("2024-01-01"),
});
alpaca.marketData.iterateStockTradeSingle​

Lazily yield a single symbol's stock trades across all pages.

for await (const trade of alpaca.marketData.iterateStockTradeSingle({
  symbol: "AAPL",
  start: new Date("2024-01-02"),
})) console.log(trade.p);
alpaca.marketData.collectStockTradeSingle​

Collect a single symbol's stock trades into one StockTrade[] array.

const trades = await alpaca.marketData.collectStockTradeSingle({
  symbol: "AAPL",
  start: new Date("2024-01-02"),
});
alpaca.marketData.iterateStockQuoteSingle​

Lazily yield a single symbol's stock quotes across all pages.

for await (const quote of alpaca.marketData.iterateStockQuoteSingle({
  symbol: "AAPL",
  start: new Date("2024-01-02"),
})) console.log(quote.bp);
alpaca.marketData.collectStockQuoteSingle​

Collect a single symbol's stock quotes into one StockQuote[] array.

const quotes = await alpaca.marketData.collectStockQuoteSingle({
  symbol: "AAPL",
  start: new Date("2024-01-02"),
});
alpaca.marketData.iterateStockAuctionSingle​

Lazily yield a single symbol's daily auctions across all pages.

for await (const auction of alpaca.marketData.iterateStockAuctionSingle({
  symbol: "AAPL",
  start: new Date("2024-01-02"),
})) console.log(auction.d);
alpaca.marketData.collectStockAuctionSingle​

Collect a single symbol's daily auctions into one array.

const auctions = await alpaca.marketData.collectStockAuctionSingle({
  symbol: "AAPL",
  start: new Date("2024-01-02"),
});
alpaca.marketData.iterateNews​

Lazily yield news articles across all pages.

for await (const article of alpaca.marketData.iterateNews({
  symbols: ["AAPL"],
})) console.log(article.headline);
alpaca.marketData.collectNews​

Collect news articles into one News[] array.

const articles = await alpaca.marketData.collectNews({ symbols: ["AAPL"] });
alpaca.marketData.iterateCorporateActionsPages​

Yield valid corporate-action pages and stop before any revisited token, including longer cycles.

for await (const page of alpaca.marketData.iterateCorporateActionsPages({
  symbols: ["AAPL"],
})) console.log(page.cashDividends);
alpaca.marketData.collectCorporateActions​

Merge valid corporate-action pages, stopping before any revisited pagination token.

const actions = await alpaca.marketData.collectCorporateActions({
  symbols: ["AAPL"],
  start: new Date("2024-01-01"),
});