Skip to content

alpacahq/typescript-sdk

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

42 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

🚧 WARNING 🚧
This SDK is currently in development and not yet stable. The API may change. Please report any issues you find. Thank you! 🙏 When the version number loses the -preview suffix, the SDK is ready for production use. You can track progress and join the discussion here 😃.

typescript-sdk

version code test coverage build

A TypeScript SDK for the https://alpaca.markets REST API and WebSocket streams.

Features

  • REST API
  • WebSocket Streams
  • Built-in Rate Limiting (Token Bucket)
  • TypeScript
  • Deno
  • Node (ESM)
  • > 35% Test Coverage (and growing)
  • Tree-shakable
  • Both ESM and CJS Support
  • Zero Dependencies 🤯 (you read that right)
  • Community Driven 🚀

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

Install

From NPM:

npm install @alpacahq/typescript-sdk

From Skypack (or any CDN that supports ESM):

import { createClient } from "https://cdn.skypack.dev/@alpacahq/typescript-sdk";

Usage

Create a Client

First, you'll need to create an API key on the Alpaca website. You can do that here. Once you have an API key, you can use it to create a client.

import { createClient } from "@alpacahq/typescript-sdk";

const client = createClient({
  key: "YOUR_API_KEY_ID",
  secret: "YOUR_API_SECRET_KEY",
  // Or, provide an access token if you're using OAuth.
  // accessToken: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
});

By default, the client will make requests to the paper trading environment (https://paper-api.alpaca.markets). This is a safety measure to prevent accidental trades.

Configuration

Environment Variables

You can set the following environment variables to configure the client:

  • APCA_KEY_ID: Your API key.
  • APCA_KEY_SECRET: Your API secret.
  • APCA_ACCESS_TOKEN: Your access token (if using OAuth).
  • APCA_DEBUG: Enables debug logging.

The client will automatically use these values if they are set. They will not override any credentials explicitly passed to createClient.

Rate Limiting

You can customize the rate limiting by passing a tokenBucket object to the createClient function. This object should contain the capacity and fillRate for the rate limiter.

tokenBucket: {
  // Maximum number of tokens that can be stored
  capacity: 200,
  // Number of tokens refilled per second
  fillRate: 60,
}

Bursting is allowed, but the client will block requests if the token bucket is empty. The token bucket is shared across all requests. If you have multiple clients they will not share the same bucket.

Methods

Trading API

Market Data API

getAccount

Retrieves the account information.

client.getAccount().then(console.log);

createOrder

Creates a new order.

client
  .createOrder({
    symbol: "AAPL",
    qty: 1,
    side: "buy",
    type: "market",
    time_in_force: "day",
  })
  .then(console.log);

getOrder

Retrieves a specific order by its ID.

client
  .getOrder({ order_id: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" })
  .then(console.log);

getOrders

Retrieves a list of orders based on the specified parameters.

client
  .getOrders({
    status: "open",
    limit: 10,
    direction: "desc",
  })
  .then(console.log);

replaceOrder

Replaces an existing order with updated parameters.

client
  .replaceOrder({
    qty: 2,
    limit_price: 150.0,
    order_id: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  })
  .then(console.log);

cancelOrder

Cancels a specific order by its ID.

client
  .cancelOrder({ order_id: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" })
  .then(console.log);

cancelOrders

Cancels all open orders.

client.cancelOrders().then(console.log);

getPosition

Retrieves a specific position by symbol or asset ID.

client
  .getPosition({
    symbol_or_asset_id: "AAPL",
  })
  .then(console.log);

getPositions

Retrieves all positions.

client.getPositions().then(console.log);

closePosition

Closes a specific position by symbol or asset ID.

client
  .closePosition({
    symbol_or_asset_id: "AAPL",
  })
  .then(console.log);

closePositions

Closes all positions.

client.closePositions().then(console.log);

exerciseOption

Exercises an options contract.

client
  .exerciseOption({
    symbol_or_contract_id: "xxxxxxxx",
  })
  .then(console.log);

getCalendar

Retrieves the market calendar.

client
  .getCalendar({
    start: "2023-01-01",
    end: "2023-12-31",
  })
  .then(console.log);

getClock

Retrieves the current market clock.

client.getClock().then(console.log);

getAsset

Retrieves a specific asset by symbol or asset ID.

client
  .getAsset({
    symbol_or_asset_id: "AAPL",
  })
  .then(console.log);

getAssets

Retrieves a list of assets based on the specified parameters.

client
  .getAssets({
    status: "active",
    asset_class: "us_equity",
  })
  .then(console.log);

getWatchlist

Retrieves a specific watchlist by ID.

client
  .getWatchlist({
    watchlist_id: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  })
  .then(console.log);

getWatchlists

Retrieves all watchlists.

client.getWatchlists().then(console.log);

createWatchlist

Creates a new watchlist.

client
  .createWatchlist({
    name: "My Watchlist",
    symbols: ["AAPL", "GOOGL", "AMZN"],
  })
  .then(console.log);

updateWatchlist

Updates an existing watchlist.

client
  .updateWatchlist({
    name: "Updated Watchlist",
    symbols: ["AAPL", "GOOGL", "MSFT"],
    watchlist_id: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  })
  .then(console.log);

deleteWatchlist

Deletes a specific watchlist by ID.

client
  .deleteWatchlist({
    watchlist_id: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  })
  .then(console.log);

getPortfolioHistory

Retrieves the portfolio history.

client
  .getPortfolioHistory({
    period: "1M",
    timeframe: "1D",
  })
  .then(console.log);

getConfigurations

Retrieves the account configurations.

client.getConfigurations().then(console.log);

updateConfigurations

Updates the account configurations.

client
  .updateConfigurations({
    trade_confirm_email: "all",
    suspend_trade: false,
  })
  .then(console.log);

getActivity

Retrieves a specific activity type.

client
  .getActivity({
    activity_type: "FILL",
  })
  .then(console.log);

getActivities

Retrieves all activities.

client.getActivities().then(console.log);

getOptionsContract

Retrieves a specific options contract by symbol or contract ID.

client
  .getOptionsContract({
    symbol_or_contract_id: "AAPL230616C00150000",
  })
  .then(console.log);

getOptionsContracts

Retrieves a list of options contracts based on the specified parameters.

client
  .getOptionsContracts({
    underlying_symbols: "AAPL",
    expiration_date: "2023-06-16",
  })
  .then(console.log);

getCorporateAction

Retrieves a specific corporate action by ID.

client
  .getCorporateAction({
    id: "xxxxxxxx",
  })
  .then(console.log);

getCorporateActions

Retrieves a list of corporate actions based on the specified parameters.

client
  .getCorporateActions({
    ca_types: "MERGER",
    since: "2023-01-01",
    until: "2023-12-31",
  })
  .then(console.log);

getCryptoWallet

Retrieves a specific crypto wallet by asset.

client
  .getCryptoWallet({
    asset: "BTCUSD",
  })
  .then(console.log);

getCryptoWallets

Retrieves all crypto wallets.

client.getCryptoWallets().then(console.log);

getFeeEstimate

Retrieves the fee estimate for a crypto withdrawal.

client
  .getFeeEstimate({
    asset: "BTCUSD",
    from_address: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    to_address: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    amount: "0.1",
  })
  .then(console.log);

getCryptoTransfer

Retrieves a specific crypto transfer by ID.

client
  .getCryptoTransfer({
    transfer_id: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  })
  .then(console.log);

getCryptoTransfers

Retrieves a list of crypto transfers based on the specified parameters.

client
  .getCryptoTransfers({
    asset: "BTCUSD",
  })
  .then(console.log);

createCryptoTransfer

Creates a new crypto withdrawal.

client
  .createCryptoTransfer({
    amount: "0.1",
    address: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    asset: "BTCUSD",
  })
  .then(console.log);

getCryptoWhitelistedAddress

Retrieves a specific whitelisted crypto address.

client
  .getCryptoWhitelistedAddress({
    address: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    asset: "BTCUSD",
  })
  .then(console.log);

getCryptoWhitelistedAddresses

Retrieves all whitelisted crypto addresses.

client.getCryptoWhitelistedAddresses().then(console.log);

requestCryptoWhitelistedAddress

Requests a new whitelisted crypto address.

client
  .requestCryptoWhitelistedAddress({
    address: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    asset: "BTCUSD",
  })
  .then(console.log);

removeCryptoWhitelistedAddress

Removes a specific whitelisted crypto address.

client
  .removeCryptoWhitelistedAddress({
    whitelisted_address_id: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  })
  .then(console.log);

getStocksCorporateActions

Retrieves a list of corporate actions based on the specified parameters.

client
  .getStocksCorporateActions({
    symbols: "AAPL",
    types: "cash_dividends",
  })
  .then(console.log);

getLogo

Retrieves the logo for a specific symbol.

client
  .getLogo({
    symbol: "AAPL",
  })
  .then(console.log);

getNews

Retrieves the latest news.

client
  .getNews({
    symbols: "AAPL,TSLA",
    limit: 10,
  })
  .then(console.log);

getStocksMostActives

Retrieves a list of the most active stocks.

client
  .getStocksMostActives({
    by: "volume",
    top: 10,
  })
  .then(console.log);

getStocksMarketMovers

Retrieves a list of the top market movers.

client
  .getStocksMarketMovers({
    by: "change",
    top: 10,
  })
  .then(console.log);

getStocksQuotes

Retrieves a list of stock quotes.

client
  .getStocksQuotes({
    symbols: "AAPL,TSLA",
    limit: 10,
  })
  .then(console.log);

getStocksQuotesLatest

Retrieves the latest stock quotes.

client
  .getStocksQuotesLatest({
    symbols: "AAPL,TSLA",
  })
  .then(console.log);

getStocksBars

Retrieves a list of stock bars.

client
  .getStocksBars({
    symbols: "AAPL,TSLA",
    timeframe: "1Day",
    limit: 10,
  })
  .then(console.log);

getStocksBarsLatest

Retrieves the latest stock bars.

client
  .getStocksBarsLatest({
    symbols: "AAPL,TSLA",
  })
  .then(console.log);

getForexRates

Retrieves a list of forex rates.

client
  .getForexRates({
    currency_pairs: "EURUSD,GBPUSD",
    timeframe: "1Min",
    limit: 10,
  })
  .then(console.log);

getLatestForexRates

Retrieves the latest forex rates.

client
  .getLatestForexRates({
    currency_pairs: "EURUSD,GBPUSD",
  })
  .then(console.log);

getStocksSnapshots

Retrieves a list of stock snapshots.

client
  .getStocksSnapshots({
    symbols: "AAPL,TSLA",
  })
  .then(console.log);

getStocksAuctions

Retrieves a list of stock auctions.

client
  .getStocksAuctions({
    symbols: "AAPL,TSLA",
    limit: 10,
  })
  .then(console.log);

getStocksConditions

Retrieves a list of stock conditions.

client
  .getStocksConditions({
    tickType: "trades",
    tape: "xxx",
  })
  .then(console.log);

getStocksExchangeCodes

Retrieves a list of stock exchange codes.

client.getStocksExchangeCodes().then(console.log);

getStocksTrades

Retrieves a list of stock trades.

client
  .getStocksTrades({
    symbols: "AAPL,TSLA",
    limit: 10,
  })
  .then(console.log);

getStocksTradesLatest

Retrieves the latest stock trades.

client
  .getStocksTradesLatest({
    symbols: "AAPL,TSLA",
  })
  .then(console.log);

getOptionsBars

Retrieves a list of options bars.

client
  .getOptionsBars({
    symbols: "AAPL220617C00270000,TSLA220617C01000000",
    timeframe: "1Day",
    limit: 10,
  })
  .then(console.log);

getOptionsExchanges

Retrieves a list of options exchanges.

client.getOptionsExchanges().then(console.log);

getOptionsSnapshots

Retrieves a list of options snapshots.

client
  .getOptionsSnapshots({
    symbols: "AAPL220617C00270000,TSLA220617C01000000",
  })
  .then(console.log);

getOptionsTrades

Retrieves a list of options trades.

client
  .getOptionsTrades({
    symbols: "AAPL220617C00270000,TSLA220617C01000000",
    limit: 10,
  })
  .then(console.log);

getOptionsTradesLatest

Retrieves the latest options trades.

client
  .getOptionsTradesLatest({
    symbols: "AAPL220617C00270000,TSLA220617C01000000",
  })
  .then(console.log);

getCryptoBars

Retrieves a list of crypto bars.

client
  .getCryptoBars({
    symbols: "BTCUSD,ETHUSD",
    timeframe: "1Min",
    limit: 10,
  })
  .then(console.log);

getLatestCryptoBars

Retrieves the latest crypto bars.

client
  .getLatestCryptoBars({
    loc: "US",
    symbols: "BTCUSD,ETHUSD",
  })
  .then(console.log);

getCryptoQuotes

Retrieves a list of crypto quotes.

client
  .getCryptoQuotes({
    symbols: "BTCUSD,ETHUSD",
    limit: 10,
  })
  .then(console.log);

getCryptoQuotesLatest

Retrieves the latest crypto quotes.

client
  .getCryptoQuotesLatest({
    loc: "US",
    symbols: "BTCUSD,ETHUSD",
  })
  .then(console.log);

getCryptoSnapshots

Retrieves a list of crypto snapshots.

client
  .getCryptoSnapshots({
    loc: "US",
    symbols: "BTCUSD,ETHUSD",
  })
  .then(console.log);

getCryptoTrades

Retrieves a list of crypto trades.

client
  .getCryptoTrades({
    loc: "US",
    symbols: "BTCUSD,ETHUSD",
    limit: 10,
  })
  .then(console.log);

getCryptoTradesLatest

Retrieves the latest crypto trades.

client
  .getCryptoTradesLatest({
    loc: "US",
    symbols: "BTCUSD,ETHUSD",
  })
  .then(console.log);

getLatestCryptoOrderbooks

Retrieves the latest crypto orderbooks.

client
  .getLatestCryptoOrderbooks({
    loc: "US",
    symbols: "BTCUSD,ETHUSD",
  })
  .then(console.log);

WebSocket

How It Works

todo

Channels

todo

Examples

todo

Need Help?

The primary maintainer of this project is @117. Feel free to reach out on Slack 👋 or by opening an issue on this repo. I'm happy to help with any questions or issues you may have.