@master-chief/alpaca

alpaca

A TypeScript Node.js library for the https://alpaca.markets REST API and WebSocket streams.

Contents

• Features
• Install
• Client
• Stream
• Examples
• Contributing

Features

• Fully asynchronous API.
• Fully typed.
• Extensible AlpacaClient and AlpacaStream classes.
• Built-in rate limiting.
• Built-in number and date parsing.
• A 1:1 mapping of the official Alpaca docs.
• Auto-transpiled modern ESM alternative.
• OAuth integration support.
• Minified and nonminified bundles.
• Deno support.
• Various bundles provided:
  • alpaca.js - ESM bundle (for node)
  • alpaca.bundle.js - ESM bundle with dependencies (for node)
  • alpaca.modern.js - ESM Modern bundle (for browser)
  • alpaca.browser.js - UMD bundle (for browser)

Install

From NPM:

> npm i @master-chief/alpaca

From GitHub:

• Typescript
• ES
• ES bundled
• ES bundled with dependencies
• ES6 + UMD (classic)
• ES6 + ESM (modern)
• ES6 + ESM (modern) minified

From these popular CDNs:

• UNPKG
• JSDelivr
• SkyPack

Import

Import with ESM:

import { AlpacaClient, AlpacaStream } from '@master-chief/alpaca'

Import with ESM from CDN (works with Deno):

import { AlpacaClient } from 'https://cdn.skypack.dev/@master-chief/alpaca?dts'

Import as script:

<script src="https://unpkg.com/@master-chief/alpaca@4.0.3/dist/alpaca.browser.min.js"></script>

Import as module:

<script type="module">
  import alpaca from 'alpaca.modern.min.js'
</script>

Client

Creating a new client

If you wish to use env vars, populate these fields with process.env on your own. Paper account key detection is automatic. Using OAuth? Simply pass an access_token in the credentials object.

const client = new AlpacaClient({
  credentials: {
    key: 'xxxxxx',
    secret: 'xxxxxxxxxxxx',
    // access_token: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
  },
  rate_limit: true,
})

Built-in parsing

Alpaca provides numbers as strings. From their docs:

Decimal numbers are returned as strings to preserve full precision across platforms. When making a request, it is recommended that you also convert your numbers to strings to avoid truncation and precision errors.

This package provides numbers as number instead, and date strings as Date objects which is what most developers want out of the box. If you want the original data, as it came from Alpaca, you can call raw() on any entity.

const account = await client.getAccount()

console.log(typeof account.buying_power) // number
console.log(typeof account.raw().buying_power) // string

Methods

The following methods are available on the client.

• isAuthenticated
• getAccount
• getOrder
• getOrders
• placeOrder
• replaceOrder
• cancelOrder
• cancelOrders
• getPosition
• getPositions
• closePosition
• closePositions
• getAsset
• getAssets
• getWatchlist
• getWatchlists
• createWatchlist
• updateWatchlist
• addToWatchlist
• removeFromWatchlist
• deleteWatchlist
• getCalendar
• getClock
• getAccountConfigurations
• updateAccountConfigurations
• getAccountActivities
• getPortfolioHistory
• getBars
• getLastTrade
• getLastQuote

isAuthenticated

await client.isAuthenticated()

getAccount

await client.getAccount()

getOrder

await client.getOrder({ order_id: '6187635d-04e5-485b-8a94-7ce398b2b81c' })

getOrders

await client.getOrders({ limit: 25, status: 'all' })

placeOrder

await client.placeOrder({
  symbol: 'SPY',
  qty: 1,
  side: 'buy',
  type: 'market',
  time_in_force: 'day',
})

replaceOrder

await client.replaceOrder({
  order_id: '69a3db8b-cc63-44da-a26a-e3cca9490308',
  limit_price: 9.74,
})

cancelOrder

await client.cancelOrder({ order_id: '69a3db8b-cc63-44da-a26a-e3cca9490308' })

cancelOrders

await client.cancelOrders()

getPosition

await client.getPosition({ symbol: 'SPY' })

getPositions

await client.getPositions()

closePosition

await client.closePosition({ symbol: 'SPY' })

closePositions

await client.closePositions()

getAsset

await client.getAsset({ asset_id_or_symbol: 'SPY' })

getAssets

await client.getAssets({ status: 'active' })

getWatchlist

await client.getWatchlist({ uuid: '2000e463-6f87-41c0-a8ba-3e40cbf67128' })

getWatchlists

await client.getWatchlists()

createWatchlist

await client.createWatchlist({
  name: 'my watchlist',
  symbols: ['SPY', 'DIA', 'EEM', 'XLF'],
})

updateWatchlist

await client.updateWatchlist({
  uuid: '2000e463-6f87-41c0-a8ba-3e40cbf67128',
  name: 'new watchlist name',
  symbols: ['TSLA', 'AAPL'],
})

addToWatchlist

await client.addToWatchlist({
  uuid: '2000e463-6f87-41c0-a8ba-3e40cbf67128',
  symbol: 'F',
})

removeFromWatchlist

await client.removeFromWatchlist({
  uuid: '2000e463-6f87-41c0-a8ba-3e40cbf67128',
  symbol: 'F',
})

deleteWatchlist

await client.deleteWatchlist({ uuid: '2000e463-6f87-41c0-a8ba-3e40cbf67128' })

getCalender

await client.getCalendar({ start: new Date(), end: new Date() })

getClock

await client.getClock()

getAccountConfigurations

await client.getAccountConfigurations()

updateAccountConfigurations

await client.updateAccountConfigurations({
  no_shorting: true,
  suspend_trade: true,
})

getAccountActivities

await client.getAccountActivities({ activity_type: 'FILL' })

getPortfolioHistory

await client.getPortfolioHistory({ period: '1D', timeframe: '1Min' })

getBars

await client.getBars({ symbols: ['SPY', 'DIA', 'XLF'], timeframe: '1Min' })

getLastTrade

await client.getLastTrade({ symbol: 'SPY' })

getLastQuote

await client.getLastQuote({ symbol: 'SPY' })

Stream

Creating a new stream

If you wish to use env vars, populate these fields with process.env on your own.

import { AlpacaStream } from "alpaca" 
const stream = new AlpacaStream({
  credentials: {
    key: 'xxxxxx',
    secret: 'xxxxxxxxxxxx',
  },
  stream: 'market_data',
})

Sample subscription use:

stream.once("open", () => {
  console.log("opened")
})
stream.once("close", () => {
  console.log("closed")
})
stream.once("authenticated", () => {
  let res = stream.subscribe(["AM.SPY"])
  console.log("authenticated", res)
})

stream.on("message", (x) => console.log("message", x))
stream.on("quote", (x) => console.log("quote", x))
stream.on("aggregate_minute", (x) => console.log("aggregate_minute", x))
stream.on("trade", (x) => console.log("trade", x))
stream.on("error", (x) => console.warn("trade", x))

Events

Event	Stream
aggregate_minute	market_data
quote	market_data
trade	market_data
trade_updates	account
account_updates	account

Methods

The following methods are available on the stream.

• subscribe
• unsubscribe
• on

subscribe

stream.subscribe(['AM.SPY'])

unsubscribe

stream.unsubscribe(["AM.SPY"]));

on

stream.on("aggregate_minute", ...)

Examples

Don't know where to start? Check out our community-made examples here.

Contributing

Feel free to contribute and PR to your 💖's content.