Alpaca Broker API

openapi: 3.0.3
info:
  title: Alpaca API (Trading, Market Data, Broker)
  description: >-
    A grounded, curated OpenAPI description of Alpaca's public REST surface.
    Alpaca is a developer-first, commission-free brokerage whose stock, ETF,
    options, and crypto trading and market data are exposed entirely through
    APIs. This document covers the three REST products - the Trading API
    (api.alpaca.markets/v2, with a free paper sandbox at
    paper-api.alpaca.markets/v2), the Market Data API (data.alpaca.markets, with
    v2 stocks, v1beta3 crypto, and v1beta1 options/news/screener namespaces),
    and the Broker API (broker-api.alpaca.markets/v1). Real-time WebSocket
    streaming for market data is described in the companion AsyncAPI document at
    asyncapi/alpaca-markets-asyncapi.yml. Trading and Market Data authenticate
    with the APCA-API-KEY-ID and APCA-API-SECRET-KEY headers (or OAuth2 for
    third-party apps); the Broker API uses HTTP Basic auth. This spec is a
    representative subset of the full API for discovery purposes, not an
    exhaustive vendor specification.
  version: '1.0'
  contact:
    name: Alpaca
    url: https://alpaca.markets
  license:
    name: API documentation - Alpaca Terms of Service
    url: https://alpaca.markets/terms
servers:
  - url: https://api.alpaca.markets/v2
    description: Trading API - live
  - url: https://paper-api.alpaca.markets/v2
    description: Trading API - paper (free sandbox)
  - url: https://data.alpaca.markets
    description: Market Data API
  - url: https://broker-api.alpaca.markets/v1
    description: Broker API - production
security:
  - apcaKey: []
    apcaSecret: []
tags:
  - name: Account
    description: Trading account details, configuration, and activities.
  - name: Orders
    description: Submit, list, replace, and cancel orders.
  - name: Positions
    description: Open positions and liquidation.
  - name: Portfolio
    description: Portfolio history and performance.
  - name: Assets
    description: Tradable asset catalog.
  - name: Watchlists
    description: User watchlists.
  - name: Market
    description: Market calendar and clock.
  - name: Market Data - Stocks
    description: Historical and latest stock bars, trades, quotes, snapshots, and auctions.
  - name: Market Data - Crypto
    description: Historical and latest crypto bars, trades, quotes, and orderbooks (v1beta3).
  - name: Market Data - Options
    description: Options bars, trades, and snapshots (v1beta1).
  - name: Market Data - News
    description: Real-time and historical market news (v1beta1).
  - name: Market Data - Screener
    description: Most-actives and movers screeners (v1beta1).
  - name: Broker - Accounts
    description: Open and manage end-user brokerage accounts.
  - name: Broker - Funding
    description: Transfers and journals between accounts.
  - name: Broker - Trading
    description: Place orders on behalf of end-user accounts.
paths:
  /account:
    get:
      operationId: getAccount
      tags:
        - Account
      summary: Get account
      description: Returns the authenticated trading account's details, balances, and status.
      responses:
        '200':
          description: The trading account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /account/activities:
    get:
      operationId: getAccountActivities
      tags:
        - Account
      summary: Get account activities
      description: Returns account activity entries (fills, dividends, transfers, fees).
      parameters:
        - name: activity_types
          in: query
          schema:
            type: string
          description: Comma-separated activity types to filter by (for example FILL, DIV).
      responses:
        '200':
          description: A list of account activities.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
  /account/portfolio/history:
    get:
      operationId: getPortfolioHistory
      tags:
        - Portfolio
      summary: Get portfolio history
      description: Returns time series of account equity and profit/loss over a period.
      parameters:
        - name: period
          in: query
          schema:
            type: string
          description: The duration of the data, for example 1D, 1M, 1A.
        - name: timeframe
          in: query
          schema:
            type: string
          description: Resolution of time window, for example 1Min, 15Min, 1D.
      responses:
        '200':
          description: Portfolio history time series.
          content:
            application/json:
              schema:
                type: object
  /orders:
    get:
      operationId: listOrders
      tags:
        - Orders
      summary: List orders
      description: Retrieves a list of orders, filterable by status, symbols, and time.
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum:
              - open
              - closed
              - all
          description: Order status to filter by.
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
          description: Maximum number of orders to return.
      responses:
        '200':
          description: A list of orders.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createOrder
      tags:
        - Orders
      summary: Create an order
      description: Submits a new order for stocks, options, or crypto.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderRequest'
      responses:
        '200':
          description: The created order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '403':
          description: Forbidden - insufficient buying power or restricted.
        '422':
          description: Unprocessable - invalid order parameters.
    delete:
      operationId: cancelAllOrders
      tags:
        - Orders
      summary: Cancel all orders
      description: Attempts to cancel all open orders.
      responses:
        '207':
          description: Multi-status list of cancellation results.
  /orders/{order_id}:
    parameters:
      - name: order_id
        in: path
        required: true
        schema:
          type: string
        description: The order UUID.
    get:
      operationId: getOrder
      tags:
        - Orders
      summary: Get an order
      description: Retrieves a single order by ID.
      responses:
        '200':
          description: The order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: replaceOrder
      tags:
        - Orders
      summary: Replace an order
      description: Replaces a single open order with updated parameters.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The replacement order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
    delete:
      operationId: cancelOrder
      tags:
        - Orders
      summary: Cancel an order
      description: Attempts to cancel a single open order by ID.
      responses:
        '204':
          description: Order cancellation accepted.
  /positions:
    get:
      operationId: listPositions
      tags:
        - Positions
      summary: List open positions
      description: Retrieves all open positions in the account.
      responses:
        '200':
          description: A list of open positions.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Position'
    delete:
      operationId: closeAllPositions
      tags:
        - Positions
      summary: Close all positions
      description: Liquidates all open positions.
      responses:
        '207':
          description: Multi-status list of liquidation results.
  /positions/{symbol_or_asset_id}:
    parameters:
      - name: symbol_or_asset_id
        in: path
        required: true
        schema:
          type: string
        description: Symbol or asset UUID.
    get:
      operationId: getPosition
      tags:
        - Positions
      summary: Get an open position
      description: Retrieves the open position for a given symbol or asset.
      responses:
        '200':
          description: The open position.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Position'
    delete:
      operationId: closePosition
      tags:
        - Positions
      summary: Close a position
      description: Liquidates the open position for a symbol or asset.
      responses:
        '200':
          description: The order created to close the position.
  /assets:
    get:
      operationId: listAssets
      tags:
        - Assets
      summary: List assets
      description: Retrieves the catalog of tradable and non-tradable assets.
      parameters:
        - name: status
          in: query
          schema:
            type: string
          description: Filter by asset status, for example active.
        - name: asset_class
          in: query
          schema:
            type: string
            enum:
              - us_equity
              - us_option
              - crypto
          description: Filter by asset class.
      responses:
        '200':
          description: A list of assets.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Asset'
  /assets/{symbol_or_asset_id}:
    get:
      operationId: getAsset
      tags:
        - Assets
      summary: Get an asset
      description: Retrieves a single asset by symbol or asset ID.
      parameters:
        - name: symbol_or_asset_id
          in: path
          required: true
          schema:
            type: string
          description: Symbol or asset UUID.
      responses:
        '200':
          description: The asset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset'
  /watchlists:
    get:
      operationId: listWatchlists
      tags:
        - Watchlists
      summary: List watchlists
      description: Retrieves all watchlists for the account.
      responses:
        '200':
          description: A list of watchlists.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
    post:
      operationId: createWatchlist
      tags:
        - Watchlists
      summary: Create a watchlist
      description: Creates a new named watchlist with an optional set of symbols.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The created watchlist.
  /calendar:
    get:
      operationId: getCalendar
      tags:
        - Market
      summary: Get market calendar
      description: Returns the market calendar (open/close dates and session times).
      responses:
        '200':
          description: The market calendar.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
  /clock:
    get:
      operationId: getClock
      tags:
        - Market
      summary: Get market clock
      description: Returns the current market timestamp, whether the market is open, and next open/close.
      responses:
        '200':
          description: The market clock.
          content:
            application/json:
              schema:
                type: object
  /v2/stocks/bars:
    servers:
      - url: https://data.alpaca.markets
        description: Market Data API
    get:
      operationId: getStockBars
      tags:
        - Market Data - Stocks
      summary: Get historical stock bars
      description: >-
        Returns aggregate OHLCV bars for one or more stock symbols over a time
        range and timeframe. Full path is https://data.alpaca.markets/v2/stocks/bars.
      parameters:
        - name: symbols
          in: query
          required: true
          schema:
            type: string
          description: Comma-separated list of stock symbols.
        - name: timeframe
          in: query
          required: true
          schema:
            type: string
          description: Bar aggregation, for example 1Min, 5Min, 1Hour, 1Day.
        - name: start
          in: query
          schema:
            type: string
            format: date-time
          description: Inclusive RFC-3339 start time.
        - name: feed
          in: query
          schema:
            type: string
            enum:
              - iex
              - sip
              - delayed_sip
          description: Data feed. iex on Basic, sip on Algo Trader Plus.
      responses:
        '200':
          description: Historical bars keyed by symbol.
          content:
            application/json:
              schema:
                type: object
  /v2/stocks/{symbol}/snapshot:
    servers:
      - url: https://data.alpaca.markets
        description: Market Data API
    get:
      operationId: getStockSnapshot
      tags:
        - Market Data - Stocks
      summary: Get stock snapshot
      description: >-
        Returns the latest trade, latest quote, minute bar, daily bar, and
        previous daily bar for a symbol. Full path is
        https://data.alpaca.markets/v2/stocks/{symbol}/snapshot.
      parameters:
        - name: symbol
          in: path
          required: true
          schema:
            type: string
          description: The stock symbol.
      responses:
        '200':
          description: The snapshot.
          content:
            application/json:
              schema:
                type: object
  /v1beta3/crypto/{loc}/bars:
    servers:
      - url: https://data.alpaca.markets
        description: Market Data API
    get:
      operationId: getCryptoBars
      tags:
        - Market Data - Crypto
      summary: Get historical crypto bars
      description: >-
        Returns aggregate OHLCV bars for crypto pairs. Full path is
        https://data.alpaca.markets/v1beta3/crypto/{loc}/bars, where loc is the
        market location, for example us.
      parameters:
        - name: loc
          in: path
          required: true
          schema:
            type: string
            default: us
          description: Crypto market location, for example us.
        - name: symbols
          in: query
          required: true
          schema:
            type: string
          description: Comma-separated crypto pairs, for example BTC/USD,ETH/USD.
        - name: timeframe
          in: query
          required: true
          schema:
            type: string
          description: Bar aggregation, for example 1Min, 1Hour, 1Day.
      responses:
        '200':
          description: Historical crypto bars keyed by symbol.
          content:
            application/json:
              schema:
                type: object
  /v1beta3/crypto/{loc}/latest/orderbooks:
    servers:
      - url: https://data.alpaca.markets
        description: Market Data API
    get:
      operationId: getCryptoLatestOrderbooks
      tags:
        - Market Data - Crypto
      summary: Get latest crypto orderbooks
      description: >-
        Returns the latest Level 2 orderbook for one or more crypto pairs. Full
        path is https://data.alpaca.markets/v1beta3/crypto/{loc}/latest/orderbooks.
      parameters:
        - name: loc
          in: path
          required: true
          schema:
            type: string
            default: us
          description: Crypto market location, for example us.
        - name: symbols
          in: query
          required: true
          schema:
            type: string
          description: Comma-separated crypto pairs.
      responses:
        '200':
          description: Latest orderbooks keyed by symbol.
          content:
            application/json:
              schema:
                type: object
  /v1beta1/options/snapshots/{underlying_symbol}:
    servers:
      - url: https://data.alpaca.markets
        description: Market Data API
    get:
      operationId: getOptionSnapshots
      tags:
        - Market Data - Options
      summary: Get option chain snapshots
      description: >-
        Returns snapshots for the option contracts of an underlying symbol. Full
        path is https://data.alpaca.markets/v1beta1/options/snapshots/{underlying_symbol}.
      parameters:
        - name: underlying_symbol
          in: path
          required: true
          schema:
            type: string
          description: The underlying equity symbol, for example AAPL.
        - name: feed
          in: query
          schema:
            type: string
            enum:
              - indicative
              - opra
          description: Options feed. indicative on Basic, opra on Algo Trader Plus.
      responses:
        '200':
          description: Option snapshots.
          content:
            application/json:
              schema:
                type: object
  /v1beta1/news:
    servers:
      - url: https://data.alpaca.markets
        description: Market Data API
    get:
      operationId: getNews
      tags:
        - Market Data - News
      summary: Get market news
      description: >-
        Returns market news articles, optionally filtered by symbols and time.
        Full path is https://data.alpaca.markets/v1beta1/news.
      parameters:
        - name: symbols
          in: query
          schema:
            type: string
          description: Comma-separated symbols to filter news by.
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
          description: Maximum number of articles to return.
      responses:
        '200':
          description: News articles.
          content:
            application/json:
              schema:
                type: object
  /v1beta1/screener/stocks/most-actives:
    servers:
      - url: https://data.alpaca.markets
        description: Market Data API
    get:
      operationId: getMostActives
      tags:
        - Market Data - Screener
      summary: Get most active stocks
      description: >-
        Returns the most active stocks by volume or trade count. Full path is
        https://data.alpaca.markets/v1beta1/screener/stocks/most-actives.
      parameters:
        - name: by
          in: query
          schema:
            type: string
            enum:
              - volume
              - trades
          description: Ranking metric.
        - name: top
          in: query
          schema:
            type: integer
            default: 10
          description: Number of results to return.
      responses:
        '200':
          description: Most active stocks.
          content:
            application/json:
              schema:
                type: object
  /accounts:
    servers:
      - url: https://broker-api.alpaca.markets/v1
        description: Broker API
    post:
      operationId: createBrokerAccount
      tags:
        - Broker - Accounts
      summary: Create a brokerage account
      description: >-
        Opens a new end-user brokerage account with KYC/onboarding details. Full
        path is https://broker-api.alpaca.markets/v1/accounts. Broker API uses
        HTTP Basic authentication.
      security:
        - brokerBasic: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The created brokerage account.
          content:
            application/json:
              schema:
                type: object
  /accounts/{account_id}:
    servers:
      - url: https://broker-api.alpaca.markets/v1
        description: Broker API
    get:
      operationId: getBrokerAccount
      tags:
        - Broker - Accounts
      summary: Get a brokerage account
      description: >-
        Retrieves a single end-user brokerage account. Full path is
        https://broker-api.alpaca.markets/v1/accounts/{account_id}.
      security:
        - brokerBasic: []
      parameters:
        - name: account_id
          in: path
          required: true
          schema:
            type: string
          description: The brokerage account UUID.
      responses:
        '200':
          description: The brokerage account.
          content:
            application/json:
              schema:
                type: object
  /accounts/{account_id}/transfers:
    servers:
      - url: https://broker-api.alpaca.markets/v1
        description: Broker API
    post:
      operationId: createTransfer
      tags:
        - Broker - Funding
      summary: Create a transfer
      description: >-
        Initiates an ACH or wire transfer to fund an end-user account. Full path
        is https://broker-api.alpaca.markets/v1/accounts/{account_id}/transfers.
      security:
        - brokerBasic: []
      parameters:
        - name: account_id
          in: path
          required: true
          schema:
            type: string
          description: The brokerage account UUID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The created transfer.
          content:
            application/json:
              schema:
                type: object
  /trading/accounts/{account_id}/orders:
    servers:
      - url: https://broker-api.alpaca.markets/v1
        description: Broker API
    post:
      operationId: createBrokerOrder
      tags:
        - Broker - Trading
      summary: Create an order for an account
      description: >-
        Places an order on behalf of an end-user account. Full path is
        https://broker-api.alpaca.markets/v1/trading/accounts/{account_id}/orders.
      security:
        - brokerBasic: []
      parameters:
        - name: account_id
          in: path
          required: true
          schema:
            type: string
          description: The brokerage account UUID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderRequest'
      responses:
        '200':
          description: The created order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
components:
  securitySchemes:
    apcaKey:
      type: apiKey
      in: header
      name: APCA-API-KEY-ID
      description: Alpaca API key ID. Paired with APCA-API-SECRET-KEY.
    apcaSecret:
      type: apiKey
      in: header
      name: APCA-API-SECRET-KEY
      description: Alpaca API secret key. Paired with APCA-API-KEY-ID.
    brokerBasic:
      type: http
      scheme: basic
      description: Broker API HTTP Basic auth using your Broker API key as username and secret as password.
  responses:
    Unauthorized:
      description: Authentication failed or credentials missing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        code:
          type: integer
          description: Alpaca error code.
        message:
          type: string
          description: Human-readable error message.
    Account:
      type: object
      description: A trading account.
      properties:
        id:
          type: string
          description: Account UUID.
        account_number:
          type: string
          description: The account number.
        status:
          type: string
          description: Account status, for example ACTIVE.
        currency:
          type: string
          description: Account currency, for example USD.
        cash:
          type: string
          description: Cash balance.
        portfolio_value:
          type: string
          description: Total value of cash and holdings.
        buying_power:
          type: string
          description: Current buying power.
        pattern_day_trader:
          type: boolean
          description: Whether the account is flagged as a pattern day trader.
    OrderRequest:
      type: object
      required:
        - symbol
        - side
        - type
        - time_in_force
      properties:
        symbol:
          type: string
          description: Symbol or asset ID to trade, for example AAPL or BTC/USD.
        qty:
          type: string
          description: Number of shares/units. Mutually exclusive with notional.
        notional:
          type: string
          description: Dollar amount to trade (fractional). Mutually exclusive with qty.
        side:
          type: string
          enum:
            - buy
            - sell
          description: Order side.
        type:
          type: string
          enum:
            - market
            - limit
            - stop
            - stop_limit
            - trailing_stop
          description: Order type.
        time_in_force:
          type: string
          enum:
            - day
            - gtc
            - opg
            - cls
            - ioc
            - fok
          description: Time in force.
        limit_price:
          type: string
          description: Limit price, required for limit and stop_limit orders.
        stop_price:
          type: string
          description: Stop price, required for stop and stop_limit orders.
    Order:
      type: object
      description: An order.
      properties:
        id:
          type: string
          description: Order UUID.
        client_order_id:
          type: string
          description: Client-supplied order identifier.
        symbol:
          type: string
          description: The order's symbol.
        qty:
          type: string
          description: Ordered quantity.
        filled_qty:
          type: string
          description: Filled quantity.
        side:
          type: string
          description: Order side.
        type:
          type: string
          description: Order type.
        time_in_force:
          type: string
          description: Time in force.
        status:
          type: string
          description: Order status, for example new, filled, canceled.
        submitted_at:
          type: string
          format: date-time
          description: Submission timestamp.
    Position:
      type: object
      description: An open position.
      properties:
        asset_id:
          type: string
          description: Asset UUID.
        symbol:
          type: string
          description: The position's symbol.
        qty:
          type: string
          description: Quantity held.
        side:
          type: string
          description: long or short.
        market_value:
          type: string
          description: Current market value of the position.
        avg_entry_price:
          type: string
          description: Average entry price.
        unrealized_pl:
          type: string
          description: Unrealized profit/loss.
    Asset:
      type: object
      description: A tradable asset.
      properties:
        id:
          type: string
          description: Asset UUID.
        class:
          type: string
          description: Asset class, for example us_equity, us_option, crypto.
        symbol:
          type: string
          description: The asset's symbol.
        name:
          type: string
          description: The asset's name.
        exchange:
          type: string
          description: The listing exchange.
        tradable:
          type: boolean
          description: Whether the asset is tradable on Alpaca.
        fractionable:
          type: boolean
          description: Whether fractional orders are supported.