Getting Started #

This is a quick guide on how to start consuming market data via APIs. Starting from beginning to end, this section outlines how to install Alpaca’s software development kit (SDK), create a free alpaca account, locate your API keys, and how to request both historical and real-time data.

Installing Alpaca’s Client SDK #

In this guide, we’ll be making use of the SDKs provided by Alpaca. Alpaca maintains SDKs in four languages: Python, JavaScript, C#, and Go. Follow the steps in the installation guide below to install the SDK of your choice before proceeding to the next section.

Alpaca requires Python >= 3.7. To install the Python client SDK, Alpaca-py, use pip:

pip install alpaca-py

Install the JavaScript client SDK using npm:

npm install --save @alpacahq/alpaca-trade-api

Please note the following runtime dependencies:

  • Node.js v14.x or newer
  • npm version 6 and above

Navigate to inside of your .NET application folder and run:

dotnet add package Alpaca.Markets

Install the Go SDK by running the command:

go get -u github.com/alpacahq/alpaca-trade-api-go/v2/alpaca

Creating an Alpaca Account and Finding Your API Keys #

To request data from Alpaca you’ll need to include your API keys in your requests. This section outlines how one can create an account and generate the keys necessary to start querying for market data.

  1. Navigate to Alpaca’s Website

  2. Sign up for a free account using the sign up button

    Alpaca homepage

  3. After confirming your account and logging in, navigate to your paper trading dashboard

    Paper trading link

  4. On the dashboard, click the button to view your API keys

    view keys

  5. After expanding your API keys section, generate new keys

    generate keys

  6. After your keys have been generated, securely save them for future use

    copy keys

How to Request Market Data Through the SDK #

With the SDK installed and our API keys ready, you can start requesting market data. Alpaca offers many options for both historical and real-time data, so to keep this guide succint, these examples are on obtaining historical and real-time bar data. Information on what other data is available can be found in the Market Data API reference.

Querying for Historical Data #

To start using the SDK for historical data, import the SDK and instantiate the crypto historical data client. It’s not required for this client to pass in API keys or a paper URL.

from alpaca.data.historical import CryptoHistoricalDataClient

# No keys required for crypto data
client = CryptoHistoricalDataClient()

Next we’ll define the parameters for our request. Import the request class for crypto bars, CryptoBarsRequest and TimeFrame class to access time frame units more easily. This example queries for historical daily bar data of Bitcoin in the first week of September 2022.

from alpaca.data.requests import CryptoBarsRequest
from alpaca.data.timeframe import TimeFrame

# Creating request object
request_params = CryptoBarsRequest(
                        symbol_or_symbols=["BTC/USD"],
                        timeframe=TimeFrame.Day,
                        start="2022-09-01",
                        end="2022-09-07"
                        )

Finally, send the request using the client’s built-in method, get_crypto_bars. Additionally, we’ll access the .df property which returns a pandas DataFrame of the response.

# Retrieve daily bars for Bitcoin in a DataFrame and printing it
btc_bars = client.get_crypto_bars(request_params)

# Convert to dataframe
btc_bars.df

		open	high	low	close	volume	trade_count	vwap
symbol	timestamp							
BTC/USD	
        2022-09-01 05:00:00+00:00	20049.0	20285.0	19555.0	20160.0	2396.3504	18060.0	19920.278135
        2022-09-02 05:00:00+00:00	20159.0	20438.0	19746.0	19924.0	1688.0641	16730.0	20045.987764
        2022-09-03 05:00:00+00:00	19924.0	19963.0	19661.0	19802.0	624.1013	9853.0	19794.111057
        2022-09-04 05:00:00+00:00	19801.0	20060.0	19599.0	19892.0	1361.6668	8489.0	19885.445568
        2022-09-05 05:00:00+00:00	19892.0	20173.0	19640.0	19762.0	2105.0539	11900.0	19814.853546
        2022-09-06 05:00:00+00:00	19763.0	20025.0	18539.0	18720.0	3291.1657	19591.0	19272.505607
        2022-09-07 05:00:00+00:00	18723.0	19459.0	18678.0	19351.0	2259.2351	16204.0	19123.487500

To enable access to the tools in the SDK, first load the module that was installed previously.

const Alpaca = require("@alpacahq/alpaca-trade-api");

Next, instantiate the Alpaca class and define the parameters that go along with it. These are the API key, API secret key, and a boolean indicating whether the keys belong to a paid data plan or not.

API_KEY = "<Your API Key>";
API_SECRET = "<Your Secret Key>";

const alpaca = new Alpaca({
  keyId: API_KEY,
  secretKey: API_SECRET,
  paper: true,
});

Now define an object that parameterizes the options for the request. If one wants the most recent daily bar for Bitcoin, then they can define the object as below. Two parameters that aren’t set here are limit and exchanges.

const options = {
  start: new Date(new Date().setDate(new Date().getDate() - 1)), // 1 day ago
  end: new Date(), // Current date
  timeframe: "1Day",
};

The Alpaca class instantiated has a method, getCryptoBars, that is used for getting crypto bars. Place this method inside an asynchronous function that pushes the bars into an array as they come, returning the final array. After that, define the symbol to query data for and print each of the bars in the resulting array.

async function getHistoricalBars(symbol) {
  let bars = [];
  let resp = alpaca.getCryptoBars(symbol, options);
  for await (let bar of resp) {
    bars.push(bar);
  }
  return bars;
}

symbol = "BTCUSD";
barsPromise = getHistoricalBars(symbol);
barsPromise.then((bars) =>
  bars.forEach((bar) => {
    console.log(bar);
  })
);

{
  Symbol: 'BTCUSD',
  Timestamp: '2022-07-07T05:00:00Z',
  Exchange: 'CBSE',
  Open: 20400.28,
  High: 20445.5,
  Low: 20224.8,
  Close: 20404.32,
  Volume: 1029.86433895,
  TradeCount: 43372,
  VWAP: 20350.5220346576
}
{
  Symbol: 'BTCUSD',
  Timestamp: '2022-07-07T05:00:00Z',
  Exchange: 'ERSX',
  Open: 20303.8,
  High: 20439.4,
  Low: 20254.9,
  Close: 20404.3,
  Volume: 2.759,
  TradeCount: 26,
  VWAP: 20292.1438274737
}
{
  Symbol: 'BTCUSD',
  Timestamp: '2022-07-07T05:00:00Z',
  Exchange: 'FTXU',
  Open: 20398,
  High: 20443,
  Low: 20236,
  Close: 20405,
  Volume: 99.3202,
  TradeCount: 512,
  VWAP: 20352.1984752346
}

Create a new .NET application to work with by running this command:

dotnet new console -o MyApp -f net6.0

Then, navigate to the new directory that you’ll be working inside:

cd MyApp

Open the Program.cs main file in your editor and set it up as follows:

using System;
using Alpaca.Markets;
using System.Threading.Tasks;

namespace AlpacaExample
{
    internal sealed class Program
    {
        public static async Task Main()
        {

        }
    }
}

This setup adds the necessary namespaces used to code this example. Next, create constants for your API authentication information and use them to instantiate the Alpaca Crypto Data Client. Instantiate the paper client using the special extension method of the IEnvironment interface, GetAlpacaCryptoDataClient. If you’d like to use the live client, replace Paper with Live.

internal sealed class Program
{
    private const String API_KEY = "<Your API Key>";

    private const String API_SECRET = "<Your Secret Key>";

    public static async Task Main()
    {
        var client = Environments.Paper.GetAlpacaCryptoDataClient(new SecretKey(API_KEY, API_SECRET));
    }
}

With an instance of the client now available, we can access its methods to make queries. Let’s get the historical daily bar data of Bitcoin in the last 24 hours. This type of request needs 4 parameters: the symbol of the desired asset, the start of the time interval from which you’d like data from, the end of the time interval from which you’d like data from, and the timeframe on which you’d like your data to be aggregated.

public static async Task Main()
{
    var client = Environments.Paper.GetAlpacaCryptoDataClient(new SecretKey(API_KEY, API_SECRET));

    String symbol = "BTCUSD";
    DateTime start = DateTime.Today.AddDays(-1);  // Yesterday
    DateTime end = DateTime.Today;                // Today
    var timeframe = BarTimeFrame.Day;             // Denotes daily bars
}

Use the client’s method, ListHistoricalBarsAsync, to make the request and print the result to see Bitcoin’s latest bar data.

public static async Task Main()
{
    var client = Environments.Paper.GetAlpacaCryptoDataClient(new SecretKey(API_KEY, API_SECRET));

    String symbol = "BTCUSD";
    DateTime start = DateTime.Today.AddDays(-1);  // Yesterday
    DateTime end = DateTime.Today;                // Today
    var timeframe = BarTimeFrame.Day;             // Denotes daily bars

    var bars = await client.ListHistoricalBarsAsync(
        new HistoricalCryptoBarsRequest(symbol, start, end, timeframe));

    Console.WriteLine(bars);
}

{
   "bars":[
      {
         "o":21237.19,
         "c":20871.47,
         "l":20500.0,
         "h":21520.0,
         "v":11881.7097405,
         "t":"2022-06-27T05:00:00Z",
         "vw":20972.0411669989,
         "n":349271
      },
      {
         "o":21229.7,
         "c":20843.1,
         "l":20505.3,
         "h":21465.6,
         "v":133.191979,
         "t":"2022-06-27T05:00:00Z",
         "vw":20800.918343989,
         "n":689
      },
      {
         "o":21231.0,
         "c":20864.0,
         "l":20476.0,
         "h":21539.0,
         "v":1091.384,
         "t":"2022-06-27T05:00:00Z",
         "vw":20896.2606985259,
         "n":4876
      }
   ],
   "symbol":"BTCUSD",
   "next_page_token":null
}

The output shows 3 bars for Bitcoin in the last day. Each of these bars come from one of Alpaca’s crypto exchange partners, ErisX, Coinbase, and FTX.

After installing the SDK, import it along with the other libraries necessary to run this example.

package main

import (
	"fmt"
	"time"

	"github.com/alpacahq/alpaca-trade-api-go/v2/marketdata"
)

func main() {

}

Instantiate the Alpaca data client with the method marketdata.NewClient, which takes a client options object (ClientOpts) as a parameter. Pass your API credentials into the client options constructor, and that resulting object into marketdata.NewClient.

// Alternatively, you can set your API key and secret using environment
// variables named APCA_API_KEY_ID and APCA_API_SECRET_KEY respectively
apiKey := "<Your API Key>"
apiSecret := "<Your Secret Key>"

// Instantiating new Alpaca data client
dataClient := marketdata.NewClient(marketdata.ClientOpts{
  ApiKey:     apiKey,
  ApiSecret:  apiSecret,
})

Next, define the parameters for the request. This example will query for the daily bars of Bitcoin in the last 24 hours.

// Request parameters
symbol := "BTCUSD"
timeframe := marketdata.OneDay			    // Daily bars
start := time.Now().Add(-24*time.Hour)	// Exactly one day ago
end := time.Now()	                      // Current time

Use the data client’s method GetCryptoBars to query for crypto bars. This function takes two parameters: the asset as a string and a GetCryptoBarsParams object. Pass the request parameters into the GetCryptoBarsParams constructor, and the resulting object into GetCryptoBars to make the request. The result wil be a []CryptoBar, so we’ll print each bar upon a sucessful request.

// Sending GET request for crypto bars
bars, err := dataClient.GetCryptoBars(symbol, marketdata.GetCryptoBarsParams{
  TimeFrame: 	timeframe,
  Start: 	  	start,
  End: 		    end,
}); if err != nil {
  // Print error
  fmt.Printf("Failed to get bars: %v\n", err)
} else {
  // Print each bar with its index
  for idx, bar := range bars {
    fmt.Printf("Bar %v: %+v\n", idx, bar)
  }
}

Bar 0: {Timestamp:2022-07-07 05:00:00 +0000 UTC Exchange:CBSE Open:20400.28 High:20445.5 Low:20224.8 Close:20427.28 Volume:990.65565169 TradeCount:41454 VWAP:20348.0875811236}
Bar 1: {Timestamp:2022-07-07 05:00:00 +0000 UTC Exchange:ERSX Open:20303.8 High:20439.4 Low:20254.9 Close:20431.1 Volume:2.7154 TradeCount:24 VWAP:20290.3038521028}
Bar 2: {Timestamp:2022-07-07 05:00:00 +0000 UTC Exchange:FTXU Open:20398 High:20443 Low:20236 Close:20430 Volume:87.2949 TradeCount:458 VWAP:20342.856462405}

Streaming Real-Time Data #

After installing the SDK and securing API keys, you can start streaming real-time data. Similar to our historical data example, we’ll stream bar data for one cryptocurrency, Bitcoin. To learn more about what data are available for streaming, visit the docs for real-time stocks data and real-time crypto data.

To start streaming real-time data, first import the CryptoDataStream class from the SDK.

from alpaca.data.live import CryptoDataStream

Now instantiate the streaming class using your API keys.

API_KEY = "<Your API Key>"
SECRET_KEY = "<Your Secret Key>"

# Initiate class
crypto_stream = CryptoDataStream(API_KEY, SECRET_KEY)

Next, define a simple callback function that will print the bar upon receiving it. Then, define the symbol and subscribe to that symbol’s bars. The Stream class includes a method for subscribing to bars, subscribe_bars, that takes a callback function and symbol as parameters. After calling that method, run the stream and wait for the callback function to print bars.

async def bar_callback(bar):
    for property_name, value in bar:
        print(f"\"{property_name}\": {value}")

# Subscribing to bar event 
symbol = "BTC/USD"
crypto_stream.subscribe_bars(bar_callback, symbol)

crypto_stream.run()

"symbol": BTC/USD
"timestamp": 2022-09-09 12:33:00+00:00
"open": 21087.0
"high": 21122.0
"low": 21087.0
"close": 21114.0
"volume": 1.5202
"trade_count": 28.0
"vwap": 21104.0542691751
"symbol": BTC/USD
"timestamp": 2022-09-09 12:34:00+00:00
"open": 21115.0
"high": 21115.0
"low": 21095.0
"close": 21107.0
"volume": 1.8952
"trade_count": 23.0
"vwap": 21103.6209898691

This section is based off of the working stock example that can be found on the official GitHub repository for the JavaScript SDK. As usual, the first step is to load the Alpaca module.

const Alpaca = require("@alpacahq/alpaca-trade-api");

Next, define our options that parameterize our data stream. These are the API key, API key secret, data feed, and symbol.

API_KEY = "<Your API Key>";
API_SECRET = "<Your Secret Key>";
const feed = "iex"; // Change to "sip" if on a paid plan
const symbol = "BTCUSD";

Now we’ll modify the stock example. To simplify this example, remove all socket methods except for onConnect, onError, onDisconnect, and connect. Add symbol to the DataStream constructor to give us access to the symbol, change the socket to crypto_stream_v2 so we can stream crypto, and add the method onCryptoBar which handles crypto bar events.

class DataStream {
  constructor({ apiKey, secretKey, feed, symbol }) {
    this.alpaca = new Alpaca({
      keyId: apiKey,
      secretKey,
      feed,
    });

    const socket = this.alpaca.crypto_stream_v2;

    socket.onConnect(function () {
      console.log("Connected");
      socket.subscribeForBars([symbol]);
    });

    socket.onError((err) => {
      console.log(err);
    });

    socket.onCryptoBar((bar) => {
      console.log(bar);
    });

    socket.onDisconnect(() => {
      console.log("Disconnected");
    });

    socket.connect();
  }
}

Finally, instantiate the DataStream class we’ve created and wait for the bars to be printed.

let stream = new DataStream({
  apiKey: API_KEY,
  secretKey: API_SECRET,
  feed: feed,
  symbol: symbol,
  paper: true,
});

{
  T: 'b',
  Symbol: 'BTCUSD',
  Exchange: 'ERSX',
  Open: 21569.4,
  High: 21569.4,
  Low: 21543,
  Close: 21543,
  Volume: 0.465657,
  Timestamp: 2022-06-15T13:57:00.000Z,
  TradeCount: 2,
  VWAP: 21543.0850411354
}

Create a new .NET application to work with by running this command:

dotnet new console -o MyApp -f net6.0

Then, navigate to the new directory that you’ll be working inside:

cd MyApp

Open the Program.cs main file in your editor and set it up as follows:

using System;
using Alpaca.Markets;
using System.Threading.Tasks;

namespace AlpacaExample
{
    internal sealed class Program
    {
        public static async Task Main()
        {

        }
    }
}

This setup adds the namespaces used to code this example. Next, create constants for your API authentication information and use them to instantiate the Alpaca Crypto Streaming Client. Instantiate the paper client using the special extension method of the IEnvironment interface, GetAlpacaCryptoStreamingClient. If you’d like to use the live client, replace Paper with Live. After instantiation, connect and authenticate your streaming client via its method, ConnectAndAuthenticateAsync.

internal sealed class Program
{
    private const String API_KEY = "<Your API Key>";

    private const String API_SECRET = "<Your Secret Key>";

    public static async Task Main()
    {
        var client = Environments.Paper.GetAlpacaCryptoStreamingClient(new SecretKey(API_KEY, API_SECRET));

        await client.ConnectAndAuthenticateAsync();
    }
}

After establishing a connection, your client is ready to subscribe to events. Let’s subscribe to Bitcoin’s daily bars and print them as they come in. To subscribe to an event, you’ll need to create an IAlpacaDataSubscription object configured to your use case. Creating minute-bar subscriptions can be done with the method GetMinuteBarSubscription. It requires the asset’s symbol as a parameter and the returned object will be used to subscribe to the asset’s minute bars. You can define what to do upon receiving the subscription using one of its properties, Received.

Putting these ideas together, define the symbol you’d like to subscribe to, create a subscription for its minute bars, and write the callback functionality.

public static async Task Main()
{
    var client = Environments.Paper.GetAlpacaCryptoStreamingClient(new SecretKey(API_KEY, API_SECRET));

    await client.ConnectAndAuthenticateAsync();

    String symbol = "BTCUSD";

    var barSubscription = client.GetMinuteBarSubscription(symbol);
    barSubscription.Received += (bar) =>
    {
        Console.WriteLine(bar);
    };
}

Finally, subscribe to Bitcoin’s minute bars by passing your subscription object into the streaming client’s subscription method, SubscribeAsync. This example will run indefinitely, printing bars as they’re received.

public static async Task Main()
{
    var client = Environments.Paper.GetAlpacaCryptoStreamingClient(new SecretKey(API_KEY, API_SECRET));

    await client.ConnectAndAuthenticateAsync();

    String symbol = "BTCUSD";

    var barSubscription = client.GetMinuteBarSubscription(symbol);
    barSubscription.Received += (bar) =>
    {
        Console.WriteLine(bar);
    };

    await client.SubscribeAsync(barSubscription);
    while(true);
}

{
   "o":20840.4,
   "h":20840.4,
   "l":20840.4,
   "c":20840.4,
   "v":0.719755,
   "vw":20840.4,
   "n":1,
   "T":"b",
   "S":"BTCUSD",
   "t":"2022-06-27T19:55:00Z"
}

To start streaming real-time data, we’ll first import the SDK and the necessary libraries for this example.

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/alpacahq/alpaca-trade-api-go/v2/marketdata/stream"
)

func main() {

}

Instantiate the Alpaca crypto streaming client with the method stream.NewCryptoClient, which takes ...CryptoOption as a parameter. The only option we’ll configure is our API credentials. This option’s constructor is stream.WithCredentials. Pass your credentials into this constructor, and its return value into stream.NewCryptoClient.

We’ll also use WithCancel to allow for safe cancellation of our WebSocket connection.

// Necessary for safe cancellation
ctx, cancel := context.WithCancel(context.Background())
defer cancel()

// Alternatively, you can set your API key and secret using environment
// variables named APCA_API_KEY_ID and APCA_API_SECRET_KEY respectively
apiKey := "<Your API Key>"
apiSecret := "<Your Secret Key>"

// Instantiating a new Alpaca crypto data streaming client
streamClient := stream.NewCryptoClient(stream.WithCredentials(apiKey, apiSecret))

With our streaming client instantiated, let’s connect it to Alpaca. Do this with the client’s method, Connect.

// Establishing WebSocket connection
if err := streamClient.Connect(ctx); err != nil {
  log.Fatalf("Failed to connect to the marketdata stream: %v\n", err)
}

After connecting, we can subscribe to events. This example will subscribe to Bitcoin’s 1-minute bars and print them as they come in.

First let’s define the callback function to be executed upon receiving the event.

// Callback function to print streamed bars
func onBar(bar stream.CryptoBar) {
	fmt.Printf("Bar received: %+v\n", bar)
}

To subscribe to bars, use the client’s method, SubscribeToBars. This function takes two parameters: the callback function and the asset’s symbol to subscribe to. This example will run indefinitely, printing bars as they’re received.

symbol := "BTCUSD"

// Subscribing to our symbol's bars with a callback function
if err := streamClient.SubscribeToBars(onBar, symbol); err != nil {
  log.Fatalf("Failed to subscribe to the bars stream: %v\n", err)
}

// Loop indefinitely
for (true) {
}

Bar received: {Symbol:BTCUSD Exchange:CBSE Open:20429.36 High:20437.28 Low:20423.62 Close:20436.74 Volume:3.20785062 Timestamp:2022-07-07 02:13:00 -0600 MDT TradeCount:192 VWAP:20432.6125707711}
Edit Edit this page
© 2023 Alpaca Securities LLC All rights reserved.
© 2023 Alpaca Crypto LLC All rights reserved.
© 2023 AlpacaDB, Inc. All rights reserved.

Securities brokerage services are provided by Alpaca Securities LLC ("Alpaca Securities"), member FINRA/SIPC, a wholly-owned subsidiary of AlpacaDB, Inc. Technology and services are offered by AlpacaDB, Inc.

Cryptocurrency services are made available by Alpaca Crypto LLC ("Alpaca Crypto"), a FinCEN registered money services business (NMLS # 2160858), and a wholly-owned subsidiary of AlpacaDB, Inc. Alpaca Crypto is not a member of SIPC or FINRA. Cryptocurrencies are not stocks and your cryptocurrency investments are not protected by either FDIC or SIPC. Please see the Disclosure Library for more information.

This is not an offer, solicitation of an offer, or advice to buy or sell securities or cryptocurrencies, or open a brokerage account or cryptocurrency account in any jurisdiction where Alpaca Securities or Alpaca Crypto respectively, are not registered or licensed, as applicable.