API v2
Alpaca is a modern platform for algorithmic trading. Alpaca’s API is the interface for your trading algo to communicate with Alpaca’s brokerage service.
The API allows your trading algo to access real-time price, fundamentals, place orders and manage your portfolio, in either REST (pull) or streaming (push) style.
In order to start trading with Alpaca API, please sign up here.
Once you have signed up and have familiarized yourself with our API, please check out our python client to begin writing your own algo!
Authentication
Every private API call requires key-based authentication. API keys can
be acquired in the developer web console. The client must provide a pair of API
key ID and secret key in the HTTP request headers named
APCA-API-KEY-ID and APCA-API-SECRET-KEY respectively.
Here is an example using curl showing how to authenticate with the API.
curl -X GET \
-H "APCA-API-KEY-ID: {YOUR_API_KEY_ID}" \
-H "APCA-API-SECRET-KEY: {YOUR_API_SECRET_KEY}"\
https://{apiserver_domain}/v2/account
Alpaca’s live API domain is api.alpaca.markets.
Paper Trading
Alpaca’s paper trading service uses a different domain and different credentials from the live API. You’ll need to connect to the right domain so that you don’t run your paper trading algo on your live account.
To use the paper trading api, set APCA-API-KEY-ID and
APCA-API-SECRET-KEY to your paper credentials, and set the domain to paper-api.alpaca.markets.
After you have tested your algo in the paper environment and are ready to start running your algo in the live environment, you can switch the domain to the live domain, and the credentials to your live credentials. Your algo will then start trading with real money.
To learn more about paper trading, visit the paper trading page.
Rate Limit
There is a rate limit for the API requests. When it is exceeded, the API server returns error response with HTTP status code 429. The rate limit is 200 requests every minute per API key.
General Rules
Time Format and Time Zone
All date time type inputs and outputs are serialized according to ISO8601 (more specifically RFC3339). The communication does not assume a particular time zone, and this date time serialization denominates the time offset of each value.
Numbers
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.
IDs
Object ID in Alpaca system uses UUID v4. When making requests, the format with dashes is accepted.
904837e3-3b76-47ec-b432-046db621571b
Assets and Symbology
An asset in this API is a tradable or non-tradable financial instrument. Alpaca maintains our own asset database and assigns an internal ID for each asset which you can use to identify assets to specify in API calls. Assets are also identified by a combination of symbol, exchange, and asset class. The symbol of an asset may change over the time, but the symbol for an asset is always the one at the time API call is made.
When the API accepts a parameter named symbol, you can use one of the
following four different forms unless noted otherwise.
- "{symbol}"
- "{symbol}:{exchange}"
- "{symbol}:{exchange}:{asset_class}"
- "{asset_id}"
Typically the first form is enough, but in the case multiple assets are
found with a symbol (the same symbol may be used in different exchanges or
asset classes), the most commonly-used asset is assumed. To avoid
the ambiguity, you can use the second or third form with suffixes joined
by colons (:) Alternatively, asset_id is guaranteed as unique, in the
form of UUID v4. When the API accepts symbols to specify more than one
symbol in one API call, the general rule is to use commas (,) to separate
them.
All of four symbol forms are case-sensitve.
v2 Release Notes
- Updated Account and Assets entities with new fields for short selling and margin trading
- Orders that encounter account permissioning, insufficient buying power, or lack of available borrow will return a 403 “forbidden” error with an existing or new log message describing the reject.
- The endpoint host name will be the same as v1 (api.alpaca.markets/paper-api.alpaca.markets) but with different path (“/v2”).
- API key between v1 and v2 are interchangeable.
- Updated Python SDK for API v2.0 support, example usage:
api = tradeapi.REST('<key_id>', '<secret_key>', api_version=’v2’)
Notes on Orders and Positions
- If your account is set to
shorting_enabled: false, any attempt to place a sell order in a stock that you have no position or with a quantity that exceeds your current position will result in a 403Forbiddenerror. In the future, users who are approved for shorting will be able to set the shorting_enabled flag in their dashboard. This will extend to the creation of sub-accounts and help ensure strategies that are not supposed to short are never allowed to accidentally short. - For accounts with
shorting_enabled: true, if you place a sell order for an asset on which you are flat, or one that you have a short position in, it will be treated as a short sell. There are no new “side” parameters added for short selling or short covering. The existing values of “sell” and “buy” will be used, respectively. - At this time, you are only allowed to short easy-to-borrow assets. Assets that are easy to borrow are marked
with
easy_to_borrow: true. A short sell order will be rejected with a 403Forbiddenstatus if the asset being sold is hard to borrow or not shortable at all. - At this time, an order that would flip your position in that stock from long to short or short to long is not
supported and will return a 403
Forbiddenerror. Your position must first be <= 0 for shorts and must first be >= 0 for longs. In the future, we plan to support selling (buying) beyond an existing long (short) position directly into a short (long) position. - At this time, if you have no position in a stock, but you have a pending short sell (buy) order, you will not
be permitted to submit a buy (sell) order. The order will return a 403
Forbiddenerror. - In order to allow the use of margin, the /orders endpoint will use the
buying_powerfield to determine whether an account has enough buying power to buy/short a security. The exception to this rule is that assets marked withmarginable:falsecannot use margin lending to purchase the asset. - Market buy orders that would increase your position (e.g. buy order for a stock where your position in that stock is >= 0) are converted to marketable limit orders with a 2.5% to 4% price collar.
- Market sell orders that would increase your position (e.g. sell order for a stock when your position in that stock is <= 0) are NOT converted but are subject to a pre-trade buying power risk check of 102.5 to 104% of the order value.
- Short positions will be reported with negative quantities and negative market values.
API Endpoints
The account API serves important information related to an account, including account status, funds available for trade, funds available for withdrawal, and various flags relevant to an account’s ability to trade. An account maybe be blocked for just for trades (trades_blocked flag) or for both trades and transfers (account_blocked flag) if Alpaca identifies the account to engaging in any suspicious activity. Also, in accordance with FINRA’s pattern day trading rule, an account may be flagged for pattern day trading (pattern_day_trader flag), which would inhibit an account from placing any further day-trades.
Market Data
The Orders API allows a user to monitor, place and cancel their orders with Alpaca. Each order has a unique identifier provided by the client. This client-side unique order ID will be automatically generated by the system if not provided by the client, and will be returned as part of the order object along with the rest of the fields described below. Once an order is placed, it can be queried using the client-side order ID to check the status.
The positions API provides information about an account’s current open positions. The response will include information such as cost basis, shares traded, and market value, which will be updated live as price information is updated. Once a position is closed, it will no longer be queryable through this API. [GET] Get open positions GET/v2/positions Retrieves a list of the account’s open positions. Response An array of Position object [GET] Get an open position GET/v2/positions/{symbol} Retrieves the account’s open position for the given symbol.
The assets API serves as the master list of assets available for trade and data consumption from Alpaca. Assets are sorted by asset class, exchange and symbol. Some assets are only available for data consumption via Polygon, and are not tradable with Alpaca. These assets will be marked with the flag tradable=false. [GET] Get assets GET/v2/assets Get a list of assets Parameters Query Parameters status string e.g. “active”. By default, all statuses are included.
Overview Alpaca’s API offers WebSocket streaming for account and order updates which follows the RFC6455 WebSocket protocol. To connect to the WebSocket follow the standard opening handshake as defined by the RFC specification to wss://paper-api.alpaca.markets/stream or wss://api.alpaca.markets/stream. Alpaca’s streaming service supports both JSON and MessagePack codecs. Once the connection is authorized, the client can listen to one or more streams to get updates on particular changes. These are the streams the client can choose to listen to.
The watchlist API provides CRUD operation for the account’s watchlist. An account can have multiple watchlists and each is uniquely identified by id but can also be addressed by user-defined name. Each watchlist is an ordered list of assets. [GET] Get a list of watchlists GET/v2/watchlists Returns the list of watchlists registered under the account. Response An array of Watchlist object [POST] Create a watchlist POST/v2/watchlists Create a new watchlist with initial set of assets.
The calendar API serves the full list of market days from 1970 to 2029. It can also be queried by specifying a start and/or end time to narrow down the results. In addition to the dates, the response also contains the specific open and close times for the market days, taking into account early closures. [GET] Get the calendar GET/v2/calendar Returns the market calendar. Parameters Query Parameters start timestamp The first date to retrieve data for (inclusive) end timestamp The last date to retrieve data for (inclusive) Response An array of Calendar object Calendar Entity Example { "date": "2018-01-03", "open": "09:30", "close": "16:00" } Properties date string Date string in “%Y-%m-%d” format open string The time the market opens at on this date in “%H:%M” format close string The time the market closes at on this date in “%H:%M” format
The clock API serves the current market timestamp, whether or not the market is currently open, as well as the times of the next market open and close. [GET] Get the clock GET/v2/clock Returns the market clock. Response A Clock object Clock Entity Example { "timestamp": "2018-04-01T12:00:00.000Z", "is_open": true, "next_open": "2018-04-01T12:00:00.000Z", "next_close": "2018-04-01T12:00:00.000Z" } Properties timestamp string<timestamp> Current timestamp is_open boolean Whether or not the market is open next_open string<timestamp> Next market open timestamp next_close string<timestamp> Next market close timestamp
The account configuration API provides custom configurations about your trading account settings. These configurations control various allow you to modify settings to suit your trading needs. For DTMC protection, see Day Trade Margin Call Protection [GET] Get the account configurations GET/v2/account/configurations Returns the current account configuration values Response AccountConfigurations object [PATCH] Update the account configurations PATCH/v2/account/configurations Returns the current account configuration values Response AccountConfigurations object Errors 400 Bad request One of the new values is unacceptable.
The account activities API provides access to a historical record of transaction activities that have impacted your account. Trade execution activities and non-trade activities, such as dividend payments, are both reported through this endpoint. See the bottom of this page for a full list of the types of activities that may be reported. Paging of Results Pagination is handled using the page_token and page_size parameters. page_token represents the ID of the end of your current page of results.
The portfolio history API returns the timeseries data for equity and profit loss information of the account. [GET] Get the account portfolio history GET/v2/account/portfolio/history Returns timeseries data about equity and profit/loss (P/L) of the account in requested timespan. Parameters Query Parameters period string The duration of the data in <number> + <unit>, such as 1D, where <unit> can be D for day, W for week, M for month and A for year.