A TypeScript SDK for the https://alpaca.markets REST API and WebSocket streams.
- 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.
🚧 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.
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";
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.
// token: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
});
You can also use the ALPACA_KEY
and ALPACA_SECRET
environment variables to set your API key and secret. The client will automatically use these values if they are set. They will not override any credentials explicitly passed to createClient
.
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.
You can change this by passing the baseURL
option to the createClient
function. Depending on the environment, you may need to use a different API key. Types will be inferred based on the base URL you provide.
baseURL: "https://paper-api.alpaca.markets",
Here are the possible baseURL
values:
URL | Type |
---|---|
https://api.alpaca.markets |
REST |
https://paper-api.alpaca.markets |
REST |
https://data.alpaca.markets |
REST |
wss://api.alpaca.markets/stream |
WebSocket (binary) |
wss://paper-api.alpaca.markets/stream |
WebSocket (binary) |
wss://data.alpaca.markets/stream |
WebSocket (JSON) |
wss://stream.data.alpaca.markets/v2/test |
WebSocket (JSON) |
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.
The methods are named to reflect the structure of their API paths.
{version}.{resource}.{method}()
version
is the API version (ex.v2
)resource
is the REST resource (ex.account
,orders
,assets
, etc.)method
is the HTTP method (ex.get
,post
,put
,delete
, etc.)
Since the client is fully-typed 😁, you can use your IDE to explore the available methods and their parameters. They are also documented below.
These are available on api
and paper-api
baseURL
's:
Path | Method(s) |
---|---|
v2.account |
get |
v2.account.portfolio.history |
get |
v2.account.configurations |
get , patch |
v2.account.activities |
get |
v2.orders |
get , post , patch , delete |
v2.positions |
get , delete |
v2.positions.exercise |
post |
v2.watchlists |
get , post , patch , delete |
v2.calendar |
get |
v2.clock |
get |
v2.assets |
get |
v2.options.contracts |
get |
v2.corporate_actions.announcements |
get |
v2.wallets |
get |
v2.wallets.whitelists |
get , post , delete |
v2.wallets.fees.estimate |
get |
v2.wallets.transfers |
get , post , delete |
These are available on the https://data.alpaca.markets
baseURL
:
Path | Method(s) |
---|---|
v1beta1.corporate_actions |
get |
v1beta1.forex.latest.rates |
get |
v1beta1.forex.rates |
get |
v1beta1.logos |
get |
v1beta1.news |
get |
v1beta1.options.bars |
get |
v1beta1.options.meta.exchanges |
get |
v1beta1.options.quotes.latest |
get |
v1beta1.options.trades.latest |
get |
v1beta1.options.trades |
get |
v1beta1.options.snapshots |
get |
v1beta1.screener.stocks.most_actives |
get |
v1beta1.screener.movers |
get |
v1beta3.crypto.bars |
get |
v1beta3.crypto.latest.bars |
get |
v1beta3.crypto.latest.orderbooks |
get |
v1beta3.crypto.latest.quotes |
get |
v1beta3.crypto.latest.trades |
get |
v1beta3.crypto.quotes |
get |
v1beta3.crypto.snapshots |
get |
v1beta3.crypto.trades |
get |
v2.stocks.auctions |
get |
v2.stocks.bars |
get |
v2.stocks.bars.latest |
get |
v2.stocks.meta.conditions |
get |
v2.stocks.meta.exchanges |
get |
v2.stocks.meta.quotes |
get |
v2.stocks.snapshots |
get |
v2.stocks.trades |
get |
v2.stocks.trades.latest |
get |
When you create a client with a WebSocket baseURL
(wss://
), a connection is automatically established. The SDK provides typed methods on the client for subscribing, unsubscribing, and handling messages. For advanced use cases, you can access the WebSocket client directly through the _context.websocket
property.
todo
todo
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.