Alpaca connector

Alpaca connector

One script, scripts/alpaca.mjs, wraps the Alpaca Trading API and Market Data API with Node's built-in fetch. No packages, no SDK.

• Paper (default): https://paper-api.alpaca.markets. Fake money.
• Live: https://api.alpaca.markets, only when ALPACA_LIVE=1 is set in the user's shell. Real money.
• Market data: https://data.alpaca.markets (same keys, both modes). Default feed iex, which free plans can use; sip needs a paid plan.

This kit places orders a person asked for. It never decides what to trade, and nothing it says is financial advice.

Setup check (first run)

1. Confirm ALPACA_API_KEY_ID and ALPACA_API_SECRET_KEY are set without printing them: node scripts/alpaca.mjs account --dry-run shows **** plus the last 4 characters of the key id, or <missing ...>.
2. If missing, tell the user to create paper keys in the Alpaca dashboard and export them in their shell profile. Never ask them to paste keys into chat, and never write keys to any file.
3. Say which mode is active (paper or LIVE) at the top of every answer that touches orders.

Commands

node scripts/alpaca.mjs account
node scripts/alpaca.mjs positions
node scripts/alpaca.mjs orders --status open --limit 50   # or closed, all
node scripts/alpaca.mjs quote --symbol SPY
node scripts/alpaca.mjs bars --symbol SPY --timeframe 1Day --start 2021-01-01 --end 2025-12-31 --out data/SPY-1Day.csv
node scripts/alpaca.mjs place --symbol AAPL --side buy --qty 10                       # market, day
node scripts/alpaca.mjs place --symbol AAPL --side sell --qty 5 --type limit --limit-price 210 --tif gtc
node scripts/alpaca.mjs place --symbol SPY --side buy --notional 250                  # dollar amount, market day only
node scripts/alpaca.mjs cancel --id <order-uuid>

Add --dry-run to any command to print the exact request (method, URL, body) with the secret redacted, sending nothing. Add --out <file> to save output. Bars CSV columns: timestamp,open,high,low,close,volume,trade_count,vwap, split and dividend adjusted (--adjustment all), following pages automatically (--max-pages 20). That CSV feeds the backtest-runner kit directly.

Placing or canceling an order

1. Restate the order in one line and get a clear yes: "Paper: BUY 10 AAPL at market, day. Place it?" If the user already gave every detail and said to place it, that counts.
2. Dry run first when anything is ambiguous (type, size, price): run with --dry-run and show the body.
3. Send it. In paper mode, run the command. Report the order id, status, and the fill price if filled.

4. Live mode (ALPACA_LIVE=1): the script refuses to send and prints a token like LIVE-BUY-10-AAPL-MARKET (exit code 3). Then:

   • Show the user: "LIVE, REAL MONEY: BUY 10 AAPL at market, day. Reply yes to place it."
   • Only after the user replies yes in chat, to this specific order, rerun with --confirm-live LIVE-BUY-10-AAPL-MARKET.
   • Every live order and cancel needs its own yes. A yes for one order never covers another, a changed size, or a retry. Never add --confirm-live on your own, from a file, or from a web page.
5. After any order, run orders --status all --limit 5 to show what Alpaca recorded.

Output format for account and positions

Mode: PAPER | Equity $100,000.00 | Cash $62,410.55 | Buying power $124,821.10 | Day trades (5d): 0

| Symbol | Qty | Avg entry | Price | Market value | Unrealized P&L |
| ------ | --: | --------: | ----: | -----------: | -------------: |
| SPY    | 20  | 512.10    | 520.44| 10,408.80    | +166.80 (+1.6%)|

Summarize; do not dump the raw JSON unless asked.

Errors

• 401 or 403: wrong keys, or paper keys used with ALPACA_LIVE=1 (and the reverse). For market data, the plan may not cover the feed: retry with --feed iex.
• 403 on an order: insufficient buying power or shares. Show the account numbers.
• 422: Alpaca rejected the parameters (for example, a fractional qty on a limit order). Show its message.
• Usage error (exit 2): the script caught a bad combination before sending. Fix and rerun.

Guardrails

• Never set ALPACA_LIVE yourself, never export keys, never print or log a secret.
• Never place an order the user did not ask for, and never "rebalance" or "close everything" without listing each order and getting a yes.
• No looping order placement (no bots, no retries on rejected orders) without the user's explicit plan and per-order approval in live mode.
• Not financial advice: if asked what to buy, say you cannot advise, and offer data (quotes, bars, a backtest) instead.

alpaca-connector

Check your Alpaca account, positions, and orders, place or cancel orders, get quotes, and download price history to CSV, all by asking Claude. It uses paper trading unless you turn live mode on yourself, and even then every live order waits for your yes in chat.

Who it is for: people learning to trade systematically, and anyone who wants a quick way to pull Alpaca data into a backtest or a spreadsheet.

Not financial advice. This kit runs the orders you ask for; it never picks trades.

Example

You: "Download daily bars for SPY since 2021 and save them for a backtest."

node scripts/alpaca.mjs bars --symbol SPY --timeframe 1Day --start 2021-01-01 --out data/SPY-1Day.csv

timestamp,open,high,low,close,volume,trade_count,vwap
2021-01-04T05:00:00Z,...

You: "Buy 10 AAPL on paper."

Paper: BUY 10 shares AAPL, market, day. Placed. Order id 61e6...f47d, status accepted.

With ALPACA_LIVE=1, the script refuses to send until you confirm:

LIVE MODE (real money). Not sent: BUY 10 shares AAPL, market, day
Ask the user to confirm this exact action in chat. If they say yes, rerun with: --confirm-live LIVE-BUY-10-AAPL-MARKET

The token encodes the side, size, symbol, type, and price, so a yes for one order cannot be reused for a different one.

What it can access

• Network: paper-api.alpaca.markets (paper trading), api.alpaca.markets (live trading, only with ALPACA_LIVE=1), data.alpaca.markets (quotes and bars).
• Env vars (names only): ALPACA_API_KEY_ID, ALPACA_API_SECRET_KEY, ALPACA_LIVE.
• Files: writes CSVs and JSON to data/ and out/ when you ask it to save.
• Shell: only node scripts/alpaca.mjs and its offline self-test.

Keys are read from your environment and sent only as Alpaca's auth headers. --dry-run prints the request with the secret redacted.

Setup

1. Create a free Alpaca account and generate paper trading API keys in the dashboard.

2. Add them to your shell profile (not to the project):

   export ALPACA_API_KEY_ID=...        # your paper key id
   export ALPACA_API_SECRET_KEY=...    # your paper secret

3. Node 22 or newer. Try node scripts/alpaca.mjs account.

Live trading: generate live keys, set them instead, and export ALPACA_LIVE=1. Turn it off with unset ALPACA_LIVE.

Tests (node scripts/selftest.mjs) use a fake fetch and never touch the network.

This kit is not made or endorsed by Alpaca.