Skip to main content

Getting Started

Install​

npm install @alpacahq/alpaca-trade-api

Before your first call, create or access a paper account and obtain its paper credentials. See Alpaca's paper-trading documentation, then export the key and secret in your shell:

export APCA_API_KEY_ID="YOUR_PAPER_KEY"
export APCA_API_SECRET_KEY="YOUR_PAPER_SECRET"

Your first call​

Create a paper-trading client and make an authenticated account call:

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,
});

const account = await alpaca.trading.account.getAccount();
console.log(account.status, account.buyingPower);

paper: true is the default, but keeping it explicit makes the environment easy to audit. Set paper: false only in code paths intended for live trading.

The two-layer facade​

The Alpaca client bundles the SDK behind .trading and .marketData. Within those namespaces:

  1. Generated REST methods are always available at alpaca.<group>.<resource>.<method>(...).
  2. Hand-written helpers add typed order builders, workflows, normalized data, and pagination without hiding the generated layer.

For example, alpaca.trading.orders.market(...) is an ergonomic builder. Its raw generated escape hatch remains alpaca.trading.orders.postOrder({ createOrderRequest: ... }). This rule applies throughout the SDK: when no helper fits, call the generated method.

Place one paper order​

This sends a real order to your paper account. A stable, unique clientOrderId lets you correlate logs and reconcile an ambiguous network outcome:

const clientOrderId = `getting-started-${crypto.randomUUID()}`;

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

console.log(order.id, order.status, order.clientOrderId);

Do not automatically resubmit a placement after a timeout or FetchError. Follow the reconciliation workflow in Trading first.

Support​

Next steps​