alpaca-trade-api-python

by alpacahq

Python client for Alpaca's trade API

654 Stars 221 Forks Last release: about 2 months ago (v0.50.1) Apache License 2.0 608 Commits 52 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

PyPI version CircleCI Updates Python 3

alpaca-trade-api-python

alpaca-trade-api-python
is a python library for the Alpaca Commission Free Trading API. It allows rapid trading algo development easily, with support for both REST and streaming data interfaces. For details of each API behavior, please see the online API document.
diff
- To use the Streaming abilities go to section called StreamConn

Note this module supports only python version 3.6 and above, due to the async/await and websockets module dependency.

Install

$ pip3 install alpaca-trade-api

Example

In order to call Alpaca's trade API, you need to sign up for an account and obtain API key pairs. Replace and with what you get from the web console.

REST example

import alpaca_trade_api as tradeapi

api = tradeapi.REST('', '', base_url='https://paper-api.alpaca.markets') # or use ENV Vars shown below account = api.get_account() api.list_positions()

Example Scripts

Please see the

examples/
folder for some example scripts that make use of this API

API Document

The HTTP API document is located at https://docs.alpaca.markets/

API Version

API Version now defaults to 'v2', however, if you still have a 'v1' account, you may need to specify api_version='v1' to properly use the API until you migrate.

Authentication

The Alpaca API requires API key ID and secret key, which you can obtain from the web console after you sign in. You can pass

key_id
and
secret_key
to the initializers of
REST
or
StreamConn
as arguments, or set up environment variables as outlined below.

Alpaca Environment Variables

The Alpaca SDK will check the environment for a number of variables that can be used rather than hard-coding these into your scripts.

| Environment | default | Description | | -------------------------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | APCAAPIKEYID=<keyid> | | Your API Key | | APCAAPISECRETKEY=<secretkey> | | Your API Secret Key | | APCAAPIBASEURL=url | https://api.alpaca.markets (for live)
https://paper-api.alpaca.markets (for paper) | Specify the URL for API calls, Default is live, you must specify this to switch to paper endpoint! | | APCA
APIDATAURL=url | https://data.alpaca.markets | Endpoint for data API | | APCARETRYMAX=3 | 3 | The number of subsequent API calls to retry on timeouts | | APCARETRYWAIT=3 | 3 | seconds to wait between each retry attempt | | APCARETRYCODES=429,504 | 429,504 | comma-separated HTTP status code for which retry is attempted | | POLYGONWSURL | wss://socket.polygon.io/stocks | Endpoint for streaming polygon data. You likely don't need to change this unless you want to proxy it for example | | POLYGONKEYID | | Your Polygon key, if it's not the same as your Alpaca API key. Most users will not need to set this to access Polygon. | | DATAPROXYWS | | When using the alpaca-proxy-agent you need to set this environment variable as described here |

REST

The

REST
class is the entry point for the API request. The instance of this class provides all REST API calls such as account, orders, positions, and bars.

Each returned object is wrapped by a subclass of the

Entity
class (or a list of it). This helper class provides property access (the "dot notation") to the json object, backed by the original object stored in the
_raw
field. It also converts certain types to the appropriate python object.
import alpaca_trade_api as tradeapi

api = tradeapi.REST() account = api.get_account() account.status => 'ACTIVE'

The

Entity
class also converts the timestamp string field to a pandas.Timestamp object. Its
_raw
property returns the original raw primitive data unmarshaled from the response JSON text.

Please note that the API is throttled, currently 200 requests per minute, per account. If your client exceeds this number, a 429 Too many requests status will be returned and this library will retry according to the retry environment variables as configured.

If the retries are exceeded, or other API error is returned,

alpaca_trade_api.rest.APIError
is raised. You can access the following information through this object. - the API error code:
.code
property - the API error message:
str(error)
- the original request object:
.request
property - the original response objecgt:
.response
property - the HTTP status code:
.status_code
property

API REST Methods

| Rest Method | End Point | Result | | -------------------------------- | -------------------| ------------------------------------------------------------------ | | getaccount() |

GET /account
and |
Account
entity.| | get
orderbyclientorderid(clientorderid) |

GET /orders
with clientorderid |
Order
entity.| | listorders(status=None, limit=None, after=None, until=None, direction=None, nested=None) |
GET /orders
| list of
Order
entities.
after
and
until
need to be string format, which you can obtain by
pd.Timestamp().isoformat()
| | submit
order(symbol, qty, side, type, timeinforce, limitprice=None, stopprice=None, clientorderid=None, orderclass=None, takeprofit=None, stoploss=None, trailprice=None, trailpercent=None)|
POST /orders
|
Order
entity. | | get
order(orderid) | `GET /orders/{orderid}
|
Order
entity.|
| cancel_order(order_id)                           |
DELETE /orders/{orderid}` | | | cancelallorders() |
DELETE /orders
| | | list
positions() |
GET /positions
| list of
Position
entities| | getposition(symbol) |
GET /positions/{symbol}
|
Position
entity.| | list
assets(status=None, assetclass=None) |
GET /assets
| list of
Asset
entities| | get
asset(symbol) |
GET /assets/{symbol}
|
Asset
entity| | getbarset(symbols, timeframe, limit, start=None, end=None, after=None, until=None) |
GET /bars/{timeframe}
| Barset with
limit
Bar objects for each of the the requested symbols.
timeframe
can be one of
minute
,
1Min
,
5Min
,
15Min
,
day
or
1D
.
minute
is an alias of
1Min
. Similarly,
day
is an alias of
1D
.
start
,
end
,
after
, and
until
need to be string format, which you can obtain with
pd.Timestamp().isoformat()
after
cannot be used with
start
and
until
cannot be used with
end
.| | get
aggs(symbol, timespan, multiplier, from, to)|
GET /aggs/ticker/{symbol}/range/{multiplier}/{timespan}/{from}/{to}
|
Aggs
entity.
multiplier
is the size of the timespan multiplier.
timespan
is the size of the time window, can be one of
minute
,
hour
,
day
,
week
,
month
,
quarter
or
year
. `
from
and
to
must be in
YYYY-MM-DD
format, e.g.
2020-01-15
.| 
| get_last_trade(symbol)                           |
GET /last/stocks/{symbol}
|
Trade
entity|
| get_last_quote(symbol)                           |
GET /lastquote/stocks/{symbol}
|
Quote` entity| | get
clock() |
GET /clock
|
Clock
entity| | getcalendar(start=None, end=None) |
GET /calendar
|
Calendar
entity| | get
portfoliohistory(datestart=None, dateend=None, period=None, timeframe=None, extendedhours=None) |
GET /account/portfolio/history
| PortfolioHistory entity. PortfolioHistory.df can be used to get the results as a dataframe|

Rest Examples

Below is an example of submitting a bracket order.

py
api.submit_order(
    symbol='SPY',
    side='buy',
    type='market',
    qty='100',
    time_in_force='day',
    order_class='bracket',
    take_profit=dict(
        limit_price='305.0',
    ),
    stop_loss=dict(
        stop_price='295.5',
        limit_price='295.5',
    )
)

StreamConn

The

StreamConn
class provides WebSocket-based event-driven interfaces. Using the
on
decorator of the instance, you can define custom event handlers that are called when the pattern is matched on the channel name. Once event handlers are set up, call the
run
method which runs forever until a critical exception is raised. This module itself does not provide any threading capability, so if you need to consume the messages pushed from the server, you need to run it in a background thread.

We provide 2 price data websockets. The polygon data, and the alpaca data. We default to Alpaca data, and one must explicitly specify the polygon data stream in order to use that. It is done by passing the

data_stream
keyword to the
__init__()
function of
StreamConn
(options:
'alpacadatav1', 'polygon'
)

This class provides a unique interface to the two interfaces, both Alpaca's account/trade updates events and Polygon's price updates. One connection is established when the

subscribe()
is called with the corresponding channel names. For example, if you subscribe to
trade_updates
, a WebSocket connects to Alpaca stream API, and if
AM.*
given to the
subscribe()
method, a WebSocket connection is established to Polygon's interface. If your account is enabled for Alpaca Data API streaming, adding
alpacadatav1/
prefix to
T.
,
Q.
and
AM.
will also connect to the data stream interface.

The

run
method is a short-cut to start subscribing to channels and running forever. The call will be blocked forever until a critical exception is raised, and each event handler is called asynchronously upon the message arrivals.

The

run
method tries to reconnect to the server in the event of connection failure. In this case, you may want to reset your state which is best in the
connect
event. The method still raises an exception in the case any other unknown error happens inside the event loop.

The

msg
object passed to each handler is wrapped by the entity helper class if the message is from the server.

Each event handler has to be a marked as

async
. Otherwise, a
ValueError
is raised when registering it as an event handler.
conn = StreamConn()

@conn.on(r'^trade_updates$') async def on_account_updates(conn, channel, account): print('account', account)

@conn.on(r'^status$') async def on_status(conn, channel, data): print('polygon status update', data)

@conn.on(r'^AM$') async def on_minute_bars(conn, channel, bar): print('bars', bar)

@conn.on(r'^A$') async def on_second_bars(conn, channel, bar): print('bars', bar)

blocks forever

conn.run(['trade_updates', 'AM.*'])

if Data API streaming is enabled

conn.run(['trade_updates', 'alpacadatav1/AM.SPY'])

You will likely call the

run
method in a thread since it will keep running unless an exception is raised.

| StreamConn Method | Description | | -------------------------------- | -------------------------------------------------------------------------------------- | | subscribe(channels) | Request "listen" to the server.

channels
must be a list of string channel names.| | unsubscribe(channels) | Request to stop "listening" to the server.
channels
must be a list of string channel names.| | run(channels) | Goes into an infinite loop and awaits for messages from the server. You should set up event listeners using the
on
or
register
method before calling
run
. | | on(channelpat) | As in the above example, this is a decorator method to add an event handler function. `channelpat
is used as a regular expression pattern to filter stream names.|
| register(channel_pat, func)           |  Registers a function as an event handler that is triggered by the stream events that match with
channelpath
regular expression. Calling this method with the same
channel
pat
will overwrite the old handler.|
| deregister(channel_pat)               | Deregisters the event handler function that was previously registered via
on
or
register` method. |

Debugging

Websocket exceptions may occur during execution. It will usually happen during the

consume()
method, which basically is the websocket steady-state.
exceptions during the consume method may occur due to: - server disconnections - error while handling the response data

We handle the first issue by reconnecting the websocket every time there's a disconnection. The second issue, is usually a user's code issue. To help you find it, we added a flag to the StreamConn object called

debug
. It is set to False by default, but you can turn it on to get a more verbose logs when this exception happens. Turn it on like so
StreamConn(debug=True)

Logging

You should define a logger in your app in order to make sure you get all the messages from the different components.
It will help you debug, and make sure you don't miss issues when they occur.
The simplest way to define a logger, if you have no experience with the python logger - will be something like this:

py
import logging
logging.basicConfig(format='%(asctime)s %(message)s', level=logging.INFO)

Polygon API Service

Alpaca's API key ID can be used to access Polygon API, the documentation for which is found here. This python SDK wraps their API service and seamlessly integrates it with the Alpaca API.

alpaca_trade_api.REST.polygon
will be the
REST
object for Polygon.

The example below gives AAPL daily OHLCV data in a DataFrame format.

import alpaca_trade_api as tradeapi

api = tradeapi.REST()

all of these examples work

aapl = api.polygon.historic_agg_v2('AAPL', 1, 'day', _from='2019-01-01', to='2019-02-01').df aapl = api.polygon.historic_agg_v2('AAPL', 1, 'day', _from=datetime.datetime(2019, 1, 1), to='2019-02-01').df aapl = api.polygon.historic_agg_v2('AAPL', 1, 'day', _from=datetime.date(2019, 1, 1), to='2019-02-01').df aapl = api.polygon.historic_agg_v2('AAPL', 1, 'day', _from=pd.Timestamp('2019-01-01'), to='2019-02-01').df

timestamp should be in milliseconds datetime.datetime(2019, 1, 1).timestamp()*1000 == 1546293600000

aapl = api.polygon.historic_agg_v2('AAPL', 1, 'day', _from=1546293600000, to='2019-02-01').df

and here's a minute example usage: ```py import pytz NY = 'America/New_York'

start = pytz.timezone(NY).localize(datetime(2020,1,2,9,30)).timestamp()*1000 # timestamp in micro seconds

another alternative will be: start = pd.Timestamp('2020-01-02 09:30', tz=NY).value/1e6

end = pytz.timezone(NY).localize(datetime(2020,1,2,16,0)).timestamp()*1000 df = api.polygon.historicaggv2('AAPL', 1, 'minute', _from=start, to=end).df

## polygon/REST
It is initialized through the alpaca `REST` object.

REST Method Description
exchanges() Returns a list of Exchange entity.
symbol_type_map() Returns a SymbolTypeMap object.
historic_trades_v2(symbol, date, timestamp=None, timestamp_limit=None, reverse=None, limit=None) Returns a TradesV2 which is a list of Trade entities. date is a date string such as '2018-2-2'. The returned quotes are from this day only. timestamp is an integer in Unix Epoch nanoseconds as the lower bound filter, exclusive. timestamp_limit is an integer in Unix Epoch nanoseconds as the maximum timestamp allowed in the results. limit is an integer for the number of ticks to return. Default and max is 50000.
TradesV2.df Returns a pandas DataFrame object with the ticks returned by historic_trades_v2.
historic_quotes_v2(symbol, date, timestamp=None, timestamp_limit=None, reverse=None, limit=None) Returns a QuotesV2 which is a list of Quote entities. date is a date string such as '2018-2-2'. The returned quotes are from this day only. timestamp is an integer in Unix Epoch nanoseconds as the lower bound filter, exclusive. timestamp_limit is an integer in Unix Epoch nanoseconds as the maximum timestamp allowed in the results. limit is an integer for the number of ticks to return. Default and max is 50000.
QuotesV2.df Returns a pandas DataFrame object with the ticks returned by the historic_quotes_v2.
historic_agg_v2(self, symbol, multiplier, timespan, _from, to, unadjusted=False, limit=None) Returns an AggsV2 which is a list of Agg entities. AggsV2.df gives you the DataFrame object.
- multiplier is an integer affecting the amount of data contained in each Agg object.
-timespan is a string affecting the length of time represented by each Agg object. It is one of the following values: minute, hour, day, week, month, quarter, year.
- _from is an Eastern Time timestamp string/object that filters the result for the lower bound, inclusive. we accept the date in these formats: datetime.datetime, datetime.date, pd.Timestamp, datetime.timestamp, isoformat string (YYYY-MM-DD).
- to is an Eastern Time timestamp string that filters the result for the upper bound, inclusive. we support the same formats as the _from field.
- unadjusted can be set to true if results should not be adjusted for splits.
- limit is an integer to limit the number of results. 3000 is the default and max value.
The returned entities have fields relabeled with the longer name instead of shorter ones. For example, the o field is renamed to open.
Aggs.df Returns a pandas DataFrame object with the ticks returned by historic_agg_v2.
daily_open_close(symbol, date) Returns a DailyOpenClose entity.
last_trade(symbol) Returns a Trade entity representing the last trade for the symbol.
last_quote(symbol) Returns a Quote entity representing the last quote for the symbol.
condition_map(ticktype='trades') Returns a ConditionMap entity.
company(symbol) Returns a Company entity if symbol is string, or a dict[symbol -> Company] if symbol is a list of string.
dividends(symbol) Returns a Dividends entity if symbol is string, or a dict[symbol -> Dividends] if symbol is a list of string.
splits(symbol) Returns a Splits entity for the symbol.
earnings(symbol) Returns an Earnings entity if symbol is string, or a dict[symbol -> Earnings] if symbol is a list of string.
financials(symbol) Returns an Financials entity if symbol is string, or a dict[symbol -> Financials] if symbol is a list of string.
news(symbol) Returns a NewsList entity for the symbol.

Support and Contribution

For technical issues particular to this module, please report the issue on this GitHub repository. Any API issues can be reported through Alpaca's customer support.

New features, as well as bug fixes, by sending a pull request is always welcomed.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.