Alpaca Trading API

openapi: 3.0.0
info:
  title: Trader API
  description: |-
    Alpaca's Trading API is a modern platform for algorithmic trading.

    For complete documentation on the Trading API and to obtain your keys head to https://alpaca.markets/docs/api-documentation/api-v2/. Once you have your keys, head to the environments tab to quickly get started.
  version: 2.0.0
  contact:
    name: Alpaca Support
    email: [email protected]
    url: 'https://alpaca.markets/support'
  termsOfService: 'https://s3.amazonaws.com/files.alpaca.markets/disclosures/library/TermsAndConditions.pdf'
servers:
  - url: 'https://paper-api.alpaca.markets'
    description: Paper
  - url: 'https://api.alpaca.markets'
    description: Live
tags:
  - name: Accounts
    description: 'Head to https://alpaca.markets/docs/api-references/trading-api/account/ to view complete documentation on the Accounts API.'
  - name: Orders
    description: 'Head to https://alpaca.markets/docs/api-documentation/api-v2/orders/ to view complete documentation on the Orders API.'
  - name: Positions
    description: 'Head to https://alpaca.markets/docs/api-documentation/api-v2/positions/ to view complete documentation on the Positions API.'
  - name: Portfolio History
    description: 'Head to https://alpaca.markets/docs/api-documentation/api-v2/portfolio-history/ to view complete documentation on the Portfolio History API.'
  - name: Watchlists
    description: 'Head to https://alpaca.markets/docs/api-documentation/api-v2/watchlist/ to view complete documentation on the Watchlist API.'
  - name: Account Configurations
    description: 'Head to https://alpaca.markets/docs/api-documentation/api-v2/account-configuration/ to view complete documentation on the Account Configurations API.'
  - name: Account Activities
    description: 'Head to https://alpaca.markets/docs/api-references/trading-api/account-activities/ to view complete documentation on the Account Activities API.'
  - name: Calendar
    description: 'Head to https://alpaca.markets/docs/api-references/trading-api/calendar/ to view complete documentation on the Market Calendar API.'
  - name: Clock
    description: 'Head to https://alpaca.markets/docs/api-references/trading-api/clock/ to view complete documentation on the Market Clock API.'
paths:
  /v2/account:
    get:
      summary: Get account
      tags:
        - Accounts
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
      operationId: getAccount
      parameters: []
      description: Returns the account associated with the API key.
  /v2/orders:
    post:
      tags:
        - Orders
      summary: Order
      operationId: postOrder
      description: 'Places a new order for the given account. An order request may be rejected if the account is not authorized for trading, or if the tradable balance is insufficient to fill the order..'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
        description: ''
      parameters: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '403':
          description: |-
            Forbidden

            Buying power or shares is not sufficient.
        '422':
          description: |-
            Unprocessable

            Input parameters are not recognized.
    get:
      tags:
        - Orders
      summary: All Orders
      parameters:
        - schema:
            type: string
            enum:
              - open
              - closed
              - all
            example: open
          in: query
          name: status
          description: 'Order status to be queried. open, closed or all. Defaults to open.'
        - schema:
            type: integer
          in: query
          name: limit
          description: The maximum number of orders in response. Defaults to 50 and max is 500.
        - schema:
            type: string
          in: query
          name: after
          description: The response will include only ones submitted after this timestamp (exclusive.)
        - schema:
            type: string
          in: query
          name: until
          description: The response will include only ones submitted until this timestamp (exclusive.)
        - schema:
            type: string
            enum:
              - asc
              - desc
          in: query
          name: direction
          description: The chronological order of response based on the submission time. asc or desc. Defaults to desc.
        - schema:
            type: boolean
          in: query
          name: nested
          description: 'If true, the result will roll up multi-leg orders under the legs field of primary order.'
        - schema:
            type: string
          in: query
          name: symbols
          description: 'A comma-separated list of symbols to filter by (ex. “AAPL,TSLA,MSFT”). A currency pair is required for crypto orders (ex. “BTCUSD,BCHUSD,LTCUSD,ETCUSD”).'
      responses:
        '200':
          description: |-
            Successful response

            An array of Order objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'
      operationId: getAllOrders
      description: 'Retrieves a list of orders for the account, filtered by the supplied query parameters.'
      x-internal: false
    delete:
      tags:
        - Orders
      summary: All Orders
      parameters: []
      responses:
        '207':
          description: |-
            Multi-Status with body.

            an array of objects that include the order id and http status code for each status request.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CanceledOrderResponse'
        '500':
          description: Failed to cancel order.
      operationId: deleteAllOrders
      description: 'Attempts to cancel all open orders. A response will be provided for each order that is attempted to be cancelled. If an order is no longer cancelable, the server will respond with status 500 and reject the request.'
  '/v2/orders/{order_id}':
    get:
      tags:
        - Orders
      summary: Order by Order ID
      parameters:
        - schema:
            type: boolean
          in: query
          name: nested
          description: 'If true, the result will roll up multi-leg orders under the legs field of primary order.'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
      operationId: getOrderByOrderID
      description: Retrieves a single order for the given order_id.
    patch:
      tags:
        - Orders
      summary: Order
      description: |
        Replaces a single order with updated parameters. Each parameter overrides the corresponding attribute of the existing order. The other attributes remain the same as the existing order.

        A success return code from a replaced order does NOT guarantee the existing open order has been replaced. If the existing open order is filled before the replacing (new) order reaches the execution venue, the replacing (new) order is rejected, and these events are sent in the trade_updates stream channel. 

        While an order is being replaced, buying power is reduced by the larger of the two orders that have been placed (the old order being replaced, and the newly placed order to replace it). If you are replacing a buy entry order with a higher limit price than the original order, the buying power is calculated based on the newly placed order. If you are replacing it with a lower limit price, the buying power is calculated based on the old order.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchOrderRequest'
      responses:
        '200':
          description: |-
            Successful response

            The new Order object with the new order ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
      operationId: patchOrderByOrderId
    delete:
      tags:
        - Orders
      summary: Order by Order ID
      parameters: []
      responses:
        '204':
          description: No Content
        '422':
          description: The order status is not cancelable.
      operationId: deleteOrderByOrderID
      description: 'Attempts to cancel an Open Order. If the order is no longer cancelable, the request will be rejected with status 422; otherwise accepted with return status 204.'
    parameters:
      - schema:
          type: string
          format: uuid
        name: order_id
        in: path
        required: true
        description: order id
  /v2/positions:
    get:
      tags:
        - Positions
      summary: All Open Positions
      parameters: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Position'
      operationId: getAllOpenPositions
      description: |-
        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

        Retrieves a list of the account’s open positions
    delete:
      tags:
        - Positions
      summary: All Positions
      parameters:
        - schema:
            type: boolean
          in: query
          name: cancel_orders
          description: 'If true is specified, cancel all open orders before liquidating all positions.'
      responses:
        '207':
          description: |-
            Multi-Status with body.

            an array of PositionClosed responses
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PositionClosedReponse'
        '500':
          description: Failed to liquidate
      operationId: deleteAllOpenPositions
      description: 'Closes (liquidates) all of the account’s open long and short positions. A response will be provided for each order that is attempted to be cancelled. If an order is no longer cancelable, the server will respond with status 500 and reject the request.'
  '/v2/positions/{symbol_or_asset_id}':
    get:
      tags:
        - Positions
      summary: Open Position
      description: Retrieves the account’s open position for the given symbol or assetId.
      parameters: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Position'
      operationId: getOpenPosition
    delete:
      tags:
        - Positions
      summary: Position
      parameters:
        - schema:
            type: number
          in: query
          name: qty
          description: the number of shares to liquidate. Can accept up to 9 decimal points. Cannot work with percentage
        - schema:
            type: number
          in: query
          name: percentage
          description: percentage of position to liquidate. Must be between 0 and 100. Would only sell fractional if position is originally fractional. Can accept up to 9 decimal points. Cannot work with qty
      responses:
        '200':
          description: |-
            Successful response

            Returns the order created to close out this position
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
      description: Closes (liquidates) the account’s open position for the given symbol. Works for both long and short positions.
      operationId: deleteOpenPosition
    parameters:
      - schema:
          type: string
        name: symbol_or_asset_id
        in: path
        required: true
        description: symbol or assetId
  /v2/account/portfolio/history:
    get:
      tags:
        - Portfolio History
      summary: Account Portfolio History
      parameters:
        - schema:
            type: string
          in: query
          name: period
          description: '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. Defaults to 1M.'
        - schema:
            type: string
          in: query
          name: timeframe
          description: 'The resolution of time window. 1Min, 5Min, 15Min, 1H, or 1D. If omitted, 1Min for less than 7 days period, 15Min for less than 30 days, or otherwise 1D.'
        - schema:
            type: string
            format: date
            example: '2022-05-15'
          in: query
          name: date_end
          description: 'The date the data is returned up to, in “YYYY-MM-DD” format. Defaults to the current market date (rolls over at the market open if extended_hours is false, otherwise at 7am ET)'
        - schema:
            type: string
          in: query
          name: extended_hours
          description: 'If true, include extended hours in the result. This is effective only for timeframe less than 1D.'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortfolioHistory'
      operationId: getAccountPortfolioHistory
      description: Returns timeseries data about equity and profit/loss (P/L) of the account in requested timespan.
  /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}':
    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.
    parameters:
      - schema:
          type: string
          format: uuid
        name: watchlist_id
        in: path
        required: true
        description: watchlist id
  '/v2/watchlists:by_name':
    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.
    parameters: []
  '/v2/watchlists/{watchlist_id}/{symbol}':
    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
    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
  /v2/account/configurations:
    get:
      tags:
        - Account Configurations
      summary: Account Configurations
      parameters: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountConfigurations'
      operationId: getAccountConfig
      description: gets the current account configuration values
    patch:
      tags:
        - Account Configurations
      summary: Account Configurations
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountConfigurations'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountConfigurations'
      operationId: patchAccountConfig
      description: Updates and returns the current account configuration values
  /v2/account/activities:
    get:
      summary: Get account activities of one type
      tags:
        - Account Activities
      responses:
        '200':
          description: returns an array of Account activities
          content:
            application/json:
              schema:
                type: array
                items:
                  anyOf:
                    - $ref: '#/components/schemas/TradingActivities'
                    - $ref: '#/components/schemas/NonTradeActivities'
                  description: Will be a mix of TradingActivity or NonTradeActivity objects based on what is passed in the activity_types parameter
      operationId: getAccountActivities
      description: Returns account activity entries for many types of activities.
      parameters:
        - schema:
            type: string
            format: date-time
          in: query
          name: date
          description: The date for which you want to see activities.
        - schema:
            type: string
            format: date-time
          in: query
          description: The response will contain only activities submitted before this date. (Cannot be used with date.)
          name: until
        - schema:
            type: string
            format: date-time
          in: query
          description: The response will contain only activities submitted after this date. (Cannot be used with date.)
          name: after
        - schema:
            type: string
            enum:
              - asc
              - desc
            example: desc
          in: query
          name: direction
          description: asc or desc (default desc if unspecified.)
        - schema:
            type: integer
          in: query
          name: page_size
          description: The maximum number of entries to return in the response. (See the section on paging above.)
        - schema:
            type: string
          in: query
          description: 'The ID of the end of your current page of results. '
          name: page_token
        - schema:
            type: string
            example: FILL
          in: query
          name: activity_types
          description: 'A comma-separated list of the activity types to include in the response. If unspecified, activities of all types will be returned. See ActivityType model for values'
  '/v2/account/activities/{activity_type}':
    parameters:
      - schema:
          type: string
        name: activity_type
        in: path
        description: The activity type you want to view entries for. A list of valid activity types can be found at the bottom of this page.
        required: true
    get:
      summary: Get account activities of one type
      tags:
        - Account Activities
      responses:
        '200':
          description: returns an array of Account activities
          content:
            application/json:
              schema:
                type: array
                items:
                  oneOf:
                    - $ref: '#/components/schemas/TradingActivities'
                    - $ref: '#/components/schemas/NonTradeActivities'
                  description: Will be one of a TradingActivity or NonTradeActivity based on activity_type used in path
      operationId: getAccountActivitiesByActivityType
      description: Returns account activity entries for a specific type of activity.
      parameters:
        - schema:
            type: string
            format: date-time
          in: query
          name: date
          description: The date for which you want to see activities.
        - schema:
            type: string
            format: date-time
          in: query
          description: The response will contain only activities submitted before this date. (Cannot be used with date.)
          name: until
        - schema:
            type: string
            format: date-time
          in: query
          description: The response will contain only activities submitted after this date. (Cannot be used with date.)
          name: after
        - schema:
            type: string
            enum:
              - asc
              - desc
            example: desc
          in: query
          name: direction
          description: asc or desc (default desc if unspecified.)
        - schema:
            type: integer
          in: query
          name: page_size
          description: The maximum number of entries to return in the response. (See the section on paging above.)
        - schema:
            type: string
          in: query
          description: 'The ID of the end of your current page of results. '
          name: page_token
  /v2/calendar:
    get:
      summary: Get Market Calendar info
      tags:
        - Calendar
      parameters:
        - schema:
            type: string
            format: date-time
          in: query
          name: start
          description: The first date to retrieve data for (inclusive)
        - schema:
            type: string
            format: date-time
          in: query
          name: end
          description: The last date to retrieve data for (inclusive)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Calendar'
      operationId: getCalendar
      description: Returns the market calendar.
  /v2/clock:
    get:
      summary: Get Market Clock info
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Clock'
      operationId: getClock
      description: |-
        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.

        Returns the market clock.
      tags:
        - Clock
components:
  securitySchemes:
    API_Key:
      name: APCA-API-KEY-ID
      type: apiKey
      in: header
      description: ''
    API_Secret:
      name: APCA-API-SECRET-KEY
      type: apiKey
      in: header
      description: ''
  schemas:
    Account:
      title: Account
      type: object
      description: |
        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. Please note that cryptocurrencies are not eligible assets to be used as collateral for margin accounts and will require the asset be traded using cash only.
      x-examples:
        example-1:
          account_blocked: false
          account_number: 010203ABCD
          buying_power: '262113.632'
          cash: '-23140.2'
          created_at: '2019-06-12T22:47:07.99658Z'
          currency: USD
          daytrade_count: 0
          daytrading_buying_power: '262113.632'
          equity: '103820.56'
          id: e6fe16f3-64a4-4921-8928-cadf02f92f98
          initial_margin: '63480.38'
          last_equity: '103529.24'
          last_maintenance_margin: '38000.832'
          long_market_value: '126960.76'
          maintenance_margin: '38088.228'
          multiplier: '4'
          pattern_day_trader: false
          portfolio_value: '103820.56'
          regt_buying_power: '80680.36'
          short_market_value: '0'
          shorting_enabled: true
          sma: '0'
          status: ACTIVE
          trade_suspended_by_user: false
          trading_blocked: false
          transfers_blocked: false
      properties:
        id:
          type: string
          description: |
            Account Id.
          format: uuid
        account_number:
          type: string
          description: Account number.
        status:
          $ref: '#/components/schemas/AccountStatus'
        currency:
          type: string
          description: |
            USD
          example: USD
        cash:
          description: |
            Cash Balance
          type: string
        portfolio_value:
          description: Total value of cash + holding positions (This field is deprecated. It is equivalent to the equity field.)
          type: string
        pattern_day_trader:
          type: boolean
          description: Whether or not the account has been flagged as a pattern day trader
        trade_suspended_by_user:
          type: boolean
          description: 'User setting. If true, the account is not allowed to place orders.'
        trading_blocked:
          type: boolean
          description: |
            If true, the account is not allowed to place orders.
        transfers_blocked:
          type: boolean
          description: 'If true, the account is not allowed to request money transfers.'
        account_blocked:
          type: boolean
          description: 'If true, the account activity by user is prohibited.'
        created_at:
          type: string
          description: |
            Timestamp this account was created at
          format: date-time
        shorting_enabled:
          type: boolean
          description: Flag to denote whether or not the account is permitted to short
        long_market_value:
          description: |
            Real-time MtM value of all long positions held in the account
          type: string
        short_market_value:
          description: Real-time MtM value of all short positions held in the account
          type: string
        equity:
          description: Cash + long_market_value + short_market_value
          type: string
        last_equity:
          description: 'Equity as of previous trading day at 16:00:00 ET'
          type: string
        multiplier:
          description: '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 (

# --- truncated at 32 KB (69 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/alpaca/refs/heads/main/openapi/alpaca-trading-api-openapi.yml