Alpaca Watchlists API
Head to https://alpaca.markets/docs/api-documentation/api-v2/watchlist/ to view complete documentation on the Watchlist API.
OpenAPI Specification
openapi: 3.0.0
info:
title: Broker Account Activities Watchlists API
description: Open brokerage accounts, enable crypto and stock trading, and manage the ongoing user experience with Alpaca Broker API
version: 1.0.0
contact:
name: Alpaca Support
email: support@alpaca.markets
url: https://alpaca.markets/support
termsOfService: https://s3.amazonaws.com/files.alpaca.markets/disclosures/library/TermsAndConditions.pdf
servers:
- url: https://broker-api.sandbox.alpaca.markets
description: Sandbox endpoint
- url: https://broker-api.alpaca.markets
description: Production endpoint
security:
- BasicAuth: []
tags:
- name: Watchlists
description: Head to https://alpaca.markets/docs/api-documentation/api-v2/watchlist/ to view complete documentation on the Watchlist API.
paths:
/v2/watchlists:
get:
tags:
- Watchlists
summary: Watchlists
parameters: []
responses:
'200':
description: Successful response
content:
application/json:
examples:
example-1:
value:
- id: 3174d6df-7726-44b4-a5bd-7fda5ae6e009
account_id: abe25343-a7ba-4255-bdeb-f7e013e9ee5d
created_at: '2022-01-31T21:49:05.14628Z'
updated_at: '2022-01-31T21:49:05.14628Z'
name: Primary Watchlist
schema:
type: array
items:
$ref: '#/components/schemas/Watchlist'
operationId: getWatchlists
description: Returns the list of watchlists registered under the account.
post:
tags:
- Watchlists
summary: Watchlist
description: Create a new watchlist with initial set of assets.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateWatchlistRequest'
parameters: []
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Watchlist'
operationId: postWatchlist
/v2/watchlists/{watchlist_id}:
parameters:
- schema:
type: string
format: uuid
name: watchlist_id
in: path
required: true
description: watchlist id
get:
tags:
- Watchlists
summary: Get Watchlist by ID
parameters: []
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Watchlist'
operationId: getWatchlistById
description: Returns a watchlist identified by the ID.
put:
tags:
- Watchlists
summary: Update Watchlist By Id
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateWatchlistRequest'
parameters: []
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Watchlist'
operationId: updateWatchlistById
description: Update the name and/or content of watchlist
post:
tags:
- Watchlists
summary: Add Asset to Watchlist
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AddAssetToWatchlistRequest'
parameters: []
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Watchlist'
operationId: addAssetToWatchlist
description: Append an asset for the symbol to the end of watchlist asset list
delete:
tags:
- Watchlists
summary: Delete Watchlist By Id
parameters: []
responses:
'204':
description: No Content
operationId: deleteWatchlistById
description: Delete a watchlist. This is a permanent deletion.
/v2/watchlists:by_name:
parameters: []
get:
tags:
- Watchlists
summary: Get Watchlist by Name
parameters:
- schema:
type: string
in: query
name: name
required: true
description: name of the watchlist
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Watchlist'
operationId: getWatchlistByName
description: Returns a watchlist by name
put:
tags:
- Watchlists
summary: Update Watchlist By Name
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateWatchlistRequest'
parameters:
- schema:
type: string
in: query
name: name
required: true
description: name of the watchlist
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Watchlist'
operationId: updateWatchlistByName
description: Update the name and/or content of watchlist
post:
tags:
- Watchlists
summary: Add Asset to Watchlist By Name
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AddAssetToWatchlistRequest'
parameters:
- schema:
type: string
in: query
name: name
required: true
description: name of the watchlist
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Watchlist'
operationId: addAssetToWatchlistByName
description: Append an asset for the symbol to the end of watchlist asset list
delete:
tags:
- Watchlists
summary: Delete Watchlist By Name
parameters:
- schema:
type: string
in: query
name: name
required: true
description: name of the watchlist
responses:
'204':
description: No Content
operationId: deleteWatchlistByName
description: Delete a watchlist. This is a permanent deletion.
/v2/watchlists/{watchlist_id}/{symbol}:
parameters:
- schema:
type: string
format: uuid
name: watchlist_id
in: path
required: true
description: Watchlist ID
- schema:
type: string
name: symbol
in: path
required: true
description: symbol name to remove from the watchlist content
delete:
tags:
- Watchlists
summary: Symbol from Watchlist
parameters: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Watchlist'
description: Returns the updated watchlist
operationId: removeAssetFromWatchlist
description: Delete one entry for an asset by symbol name
components:
schemas:
Assets:
description: '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.
'
type: object
x-examples:
example-1:
id: b0b6dd9d-8b9b-48a9-ba46-b9d54906e415
class: us_equity
exchange: NASDAQ
symbol: AAPL
name: Apple Inc. Common Stock
status: active
tradable: true
marginable: true
shortable: true
easy_to_borrow: true
fractionable: true
title: Assets
properties:
id:
type: string
format: uuid
description: Asset ID
class:
$ref: '#/components/schemas/AssetClass'
exchange:
$ref: '#/components/schemas/Exchange'
symbol:
type: string
description: The symbol of the asset
example: AAPL
name:
type: string
minLength: 1
description: The official name of the asset
status:
type: string
description: active or inactive
example: active
enum:
- active
- inactive
tradable:
type: boolean
description: Asset is tradable on Alpaca or not
marginable:
type: boolean
description: Asset is marginable or not
shortable:
type: boolean
description: Asset is shortable or not
easy_to_borrow:
type: boolean
description: 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).
fractionable:
type: boolean
description: Asset is fractionable or not
required:
- id
- class
- exchange
- symbol
- name
- status
- tradable
- marginable
- shortable
- easy_to_borrow
- fractionable
Watchlist:
description: '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.
'
type: object
x-examples:
example-1:
id: 3174d6df-7726-44b4-a5bd-7fda5ae6e009
account_id: abe25343-a7ba-4255-bdeb-f7e013e9ee5d
created_at: '2022-01-31T21:49:05.14628Z'
updated_at: '2022-01-31T21:49:05.14628Z'
name: Primary Watchlist
assets:
- id: 8ccae427-5dd0-45b3-b5fe-7ba5e422c766
class: us_equity
exchange: NASDAQ
symbol: TSLA
name: Tesla, Inc. Common Stock
status: active
tradable: true
marginable: true
shortable: true
easy_to_borrow: true
fractionable: true
title: Watchlist
properties:
id:
type: string
format: uuid
description: watchlist id
account_id:
type: string
format: uuid
description: account ID
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
name:
type: string
minLength: 1
description: user-defined watchlist name (up to 64 characters)
assets:
type: array
description: the content of this watchlist, in the order as registered by the client
items:
$ref: '#/components/schemas/Assets'
required:
- id
- account_id
- created_at
- updated_at
- name
Exchange:
title: Exchange
type: string
description: 'Represents the current exchanges Alpaca supports. List is currently:
- AMEX
- ARCA
- BATS
- NYSE
- NASDAQ
- NYSEARCA
- OTC'
enum:
- AMEX
- ARCA
- BATS
- NYSE
- NASDAQ
- NYSEARCA
- OTC
example: NYSE
AssetClass:
type: string
title: AssetClass
enum:
- us_equity
- crypto
example: us_equity
description: Represents what class of asset this is. Currently only supports `us_equity` or `crypto`
x-examples:
example-1: us_equity
AddAssetToWatchlistRequest:
title: AddAssetToWatchlistRequest
type: object
description: Append an asset for the symbol to the end of watchlist asset list
properties:
symbol:
type: string
example: AAPL
description: symbol name to append to watchlist
UpdateWatchlistRequest:
title: PostWatchlistRequest
type: object
description: Request format used for creating a new watchlist or updating an existing watchlist with a set of assets and name.
properties:
name:
type: string
symbols:
type: array
items:
type: string
nullable: true
required:
- name
securitySchemes:
BasicAuth:
type: http
scheme: basic