@master-chief/alpaca

New!
Support for the Market Data API v2 is here. This library's version has been incremented to 5.1.3-beta as some breaking changes were made to the AlpacaStream class. It will remain beta until Alpaca marks a stable version of the data API.

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 typed.
• Fully asynchronous promise based API.
• 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 non-minified bundles.
• Various bundles provided:
  • alpaca.js - ESM bundle (for node)
  • alpaca.bundle.js - ESM bundle with dependencies (for node)
  • alpaca.browser.js - UMD bundle (for browser)
  • alpaca.browser.modern.js - ESM modern bundle (for browser)

Install

From NPM:

> npm i @master-chief/alpaca

From GitHub:

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

From these popular CDNs:

• UNPKG
• JSDelivr
• SkyPack

Import

Import with CommonJS:

let { AlpacaClient, AlpacaStream } = require('@master-chief/alpaca')

Import with ESM:

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

Import as script:

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

Import as module:

<script type="module">
  import alpaca from 'alpaca.browser.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',
    paper: true,
  },
  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.

Account

• 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

Market Data

• getTrades
• getQuotes
• getBars

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' })

getTrades

await client.getTrades({
  symbol: 'SPY',
  start: new Date('2021-02-26T14:30:00.007Z'),
  end: new Date('2021-02-26T14:35:00.007Z'),
})

getQuotes

await client.getQuotes({
  symbol: 'SPY',
  start: new Date('2021-02-26T14:30:00.007Z'),
  end: new Date('2021-02-26T14:35:00.007Z'),
})

getBars

await client.getBars({
  symbol: 'SPY',
  start: new Date('2021-02-26T14:30:00.007Z'),
  end: new Date('2021-02-26T14:35:00.007Z'),
  timeframe: '1Min',
})

Stream

Creating a new stream

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

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

const stream = new AlpacaStream({
  credentials: {
    key: 'xxxxxx',
    secret: 'xxxxxxxxxxxx',
    paper: true,
  },
  type: 'market_data', // or "account"
  source: 'iex', // or "sip" depending on your subscription
})

Methods

The following methods are available on the stream.

• subscribe
• unsubscribe
• on

Channels

Channel	Type
trade_updates	account
trades	market_data
quotes	market_data
bars	market_data

subscribe

stream.once('authenticated', () =>
  stream.subscribe('bars', ['SPY', 'AAPL', 'TSLA']),
)

unsubscribe

stream.unsubscribe('bars', ['SPY'])

on

stream.on('message', (message) => console.log(message))
stream.on('trade', (trade) => console.log(trade))
stream.on('bar', (bar) => console.log(bar))
stream.on('quote', (quote) => console.log(quote))
stream.on('trade_updates', (update) => console.log(update))
stream.on('error', (error) => console.warn(error))

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.