API v2 Reference

The information contained in this section only applies to Power Accounts and is subject to revision. We’ve begun providing qualified U.S. residents with early access to the Alpaca Power Account, a new account plan with our latest features including margin trading, short selling, support for business entities, and more. We’ll be onboarding users over the coming weeks and months, so reserve your spot today by completing this form, or solve our puzzle and gain priority access!

Release Notes

  • Updated Account and Assets entities with new fields for short selling and margin trading
  • Updated Python SDK for API v2.0 support, example usage: api = tradeapi.REST('<key_id>', '<secret_key>', api_version=’v2’)
  • 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.
  • Please also refer to Web API v1.0 documentation for existing API usage

Endpoint

The endpoint host name will be the same as v1 (api.alpaca.markets/paper-api.alpaca.markets) but with different path (“/v2”).

Authentication

API key between v1 and v2 are interchangable.

[GET] Get the account

GET/v2/account
Returns the account associated with the API key.

Response

Account object

Account Entity

Example

{
  "id": "904837e3-3b76-47ec-b432-046db621571b",
  "status": "ACTIVE",
  "currency": "USD",
  "buying_power": "0.0",
  "cash": "1000.00",
  "portfolio_value": "5000.00",
  "pattern_day_trader": false,
  "trade_suspended_by_user": false,
  "trading_blocked": false,
  "transfers_blocked": false,
  "account_blocked": false,
  "created_at": "2018-10-01T13:35:25Z"
  "shorting_enabled": true,
  "multiplier": 2,
  "long_market_value": "7000.00",
  "short_market_value": "-3000.00",
  "equity": "5000.00",
  "last_equity": "5000.00",
  "initial_margin": "5000.00",
  "maintenance_margin": "3000.00",
  "daytrade_count": 0,
  "sma": "0.0"
}

Properties

id
string<uuid>
Account ID.
status
string<account_status>
See Account Status
currency
string
“USD”
buying_power
string<number>
Tradable buying power
cash
string<number>
Cash balance
portfolio_value
string<number>
Total value of cash + holding positions (This field is deprecated. It is equivalent to the equity field.)
pattern_day_trader
boolean
Whether or not the account has been flagged as a pattern day trader
trade_suspended_by_user
boolean
User setting. If true, the account is not allowed to place orders.
trading_blocked
boolean
If true, the account is not allowed to place orders.
transfers_blocked
boolean
If true, the account is not allowed to request money transfers.
account_blocked
boolean
If true, the account activity by user is prohibited.
created_at
string<timestamp>
Timestamp this account was created at
shorting_enabled
boolean
Flag to denote whether or not the account is permitted to short
long_market_value
string<number>
Real-time MtM value of all long positions held in the account
short_market_value
string<number>
Real-time MtM value of all short positions held in the account
equity
string<number>
Cash + long_market_value + short_market_value
last_equity
string<number>
Equity as of previous trading day at 16:00:00 ET
multiplier
string<number>
Buying power multiplier that represents account margin classification; valid values 1 (standard limited margin account with 1x buying power), 2 (reg T margin account with 2x intraday and overnight buying power; this is the default for all non-PDT accounts with $2,000 or more equity), 4 (PDT account with 4x intraday buying power and 2x reg T overnight buying power)
buying_power
string<number>
current available $ buying power; If multiplier = 4, this is your daytrade buying power which is calculated as (last_equity - (last) maintenance_margin) * 4; If multiplier = 2, buying_power = max(equity – initial_margin,0) * 2; If multiplier = 1, buying_power = cash
initial_margin
string<number>
Reg T initial margin requirement (continuously updated value)
maintenance_margin
string<number>
Maintenance margin requirement (continuously updated value)
sma
string<number>
value of special memorandum account (will be used at a later date to provide additional buying_power)
daytrade_count
string<int>
the current number of daytrades that have been made in the last 5 trading days (inclusive of today)

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 403 Forbidden error. 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 403 Forbidden status 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 Forbidden error. 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 Forbidden error.
  • In order to allow the use of margin, the /orders endpoint will use the buying_power field to determine whether an account has enough buying power to buy/short a security. The exception to this rule is that assets marked with marginable:false cannot use margin lending to purchase the asset.
  • Any order that would increase your position (e.g. buy orders when your position is >= 0, sell orders when your position is <= 0) reduce buying power by their 104% of their order value (1.04 * qty * price).
  • Short positions will be reported with negative quantities and negative market values.

[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.
asset_class
string
Defaults to us_equity.

Response

An array of Asset object

[GET] Get assets/:id

GET/v2/assets/:id
Assets returned from this endpoint will have the same new fields marginable, shortable, and easy_to_borrow as the /assets endpoint.

Response

[GET] Get an asset

GET/v2/assets/{symbol}
Get an asset for the given symbol.

Parameters

Path Parameters

symbol
string
symbol or asset_id

Response

An Asset object

Errors

404 Not found
Asset is not found.

Asset Entity

Example

{
  "id": "904837e3-3b76-47ec-b432-046db621571b",
  "asset_class": "us_equity",
  "exchange": "NASDAQ",
  "symbol": "AAPL",
  "status": "active",
  "tradable": true,
  "marginable": true,
  "shortable": true,
  "easy_to_borrow": true
}

Properties

id
string<uuid>
Asset ID.
asset_class
string
“us_equity”
exchange
string
AMEX, ARCA, BATS, NYSE, NASDAQ or NYSEARCA
symbol
string
status
string
active or inactive
tradable
boolean
Asset is tradable on Alpaca or not.
marginable
boolean
Asset is marginable or not.
shortable
boolean
Asset is shortable or not.
easy_to_borrow
boolean
Asset is easy-to-borrow or not (filtering for easy_to_borrow = True is the best way to check whether the name is currently available to short at Alpaca).

Suggestions or questions?
We're always happy to hear from you. You can contribute to these docs on GitHub, or you can join our Community Slack to get help from other community members and the Alpaca team.