Alpaca FPSL Program API

openapi: 3.2.0
info:
  contact:
    email: support@alpaca.markets
    name: Alpaca Support
    url: https://alpaca.markets/support
  description: Open brokerage accounts, enable stock, options and crypto trading. Manage the ongoing user experience and brokerage customer lifecycle with the Alpaca Broker API
  termsOfService: https://s3.amazonaws.com/files.alpaca.markets/disclosures/library/TermsAndConditions.pdf
  title: Broker FPSL Program API
  version: 1.1.1
servers:
- description: Sandbox endpoint
  url: https://broker-api.sandbox.alpaca.markets
- description: Production endpoint
  url: https://broker-api.alpaca.markets
security:
- BasicAuth: []
tags:
- name: FPSL Program
paths:
  /v1/fpsl/analytics/{account_id}/loans:
    get:
      description: 'Returns aggregated FPSL interest and loan-activity counts for one account over a date range. Use this for "earned so far this month" customer UIs and for supervisory spot-checks against your internal accrual model.


        The `{account_id}` path parameter accepts a account UUID (aggregation for that account).'
      operationId: get-v1-fpsl-analytics-account-loans
      parameters:
      - description: The account identifier (account UUID).
        in: path
        name: account_id
        required: true
        schema:
          format: uuid
          type: string
      - description: Filter loans after or on this start date (inclusive). Defaults to the first day of the current month, New York timezone.
        in: query
        name: start
        required: false
        schema:
          format: date
          type: string
      - description: Filter loans before this end date (exclusive). Defaults to the day after the current date, New York timezone.
        in: query
        name: end
        required: false
        schema:
          format: date
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FPSLAnalyticsLoansResponse'
          description: Returns the aggregated FPSL loan analytics for the account.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FPSLError'
          description: One of the request parameters is invalid. See the returned message for details.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FPSLError'
          description: Authentication headers are missing or invalid. Make sure you authenticate your request with a valid API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FPSLError'
          description: User has no access to a resource.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FPSLError'
          description: Internal server error. We recommend retrying these later. If the issue persists, please contact us on Slack or on the Community Forum.
      summary: Read FPSL Loans Analytics for an Account
      tags:
      - FPSL Program
  /v1/fpsl/loans:
    get:
      description: Returns a list of all FPSL loans that match the specified filter criteria, ordered in ascending order by `date`, `account_number`, and `symbol`. Each entry represents a loan of a `symbol` on a given `date`, made on behalf of the specified `account_number`.
      operationId: get-v1-list-fpsl-loans
      parameters:
      - description: The account identifier
        in: query
        name: account_id
        required: false
        schema:
          format: uuid
          type: string
      - description: Filter loans after or on this start date.
        in: query
        name: start
        required: false
        schema:
          format: date
          type: string
      - description: Filter loans before this end date.
        in: query
        name: end
        required: false
        schema:
          format: date
          type: string
      - description: The pagination token used to continue retrieving results. This value is returned in certain responses when additional data is available, typically due to a response size limit.
        in: query
        name: page_token
        required: false
        schema:
          type: string
      - description: The maximum number of data points to return in the response page.
        in: query
        name: limit
        required: false
        schema:
          default: 1000
          maximum: 10000
          minimum: 1
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListFPSLLoansResponse'
          description: Returns a list of FPSL loans for the account, or an empty list if no loans are found.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FPSLError'
          description: One of the request parameters is invalid. See the returned message for details.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FPSLError'
          description: Authentication headers are missing or invalid. Make sure you authenticate your request with a valid API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FPSLError'
          description: User has no access to a resource.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FPSLError'
          description: Internal server error. We recommend retrying these later. If the issue persists, please contact us on Slack or on the Community Forum.
      summary: List FPSL Loans
      tags:
      - FPSL Program
  /v1/fpsl/tiers:
    get:
      description: List all available FPSL tiers. These tiers may be assigned to an account.
      operationId: get-v1-list-fpsl-tiers
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/FPSLTier'
                type: array
          description: Successful response, returns a list of FPSL tiers or none if no tiers are available.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized. Please check your API key and try again.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Too many requests. Please wait a moment and try again.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: A server error occurred. Please contact Alpaca.
      summary: List FPSL Tiers
      tags:
      - FPSL Program
components:
  schemas:
    Error:
      properties:
        code:
          description: Alpaca error code, such as `40310000`. Usually the HTTP status code followed by a five-digit suffix. Several errors can share the same code, so check `message` for the specific reason.
          type: number
        message:
          description: Human-readable reason for the rejection.
          type: string
      required:
      - code
      - message
      title: Error
      type: object
    ListFPSLLoansResponse:
      description: 'Response to a successful request for a list of FPSL loans.

        '
      properties:
        loans:
          description: All FPSL loans matching the filter criteria
          items:
            $ref: '#/components/schemas/FPSLLoan'
          type: array
        next_page_token:
          description: 'The token to use to retrieve the next page of results. If `null`, there are no more pages.

            '
          type:
          - string
          - 'null'
      required:
      - loans
      - next_page_token
      type: object
    FPSLLoan:
      description: A loan of a security by an account on a date.
      properties:
        account_id:
          description: Account's ID at Alpaca
          example: 06d83e79-5bea-4ce9-a362-a25251a700ec
          type: string
        account_number:
          description: Account's number at Alpaca
          example: '286873545'
          type: string
        collateral:
          description: The collateral posted for the loan.
          example: 1161.015
          format: double
          type: number
        correspondent:
          description: Account's correspondent
          example: LPCA
          type: string
        date:
          example: '2006-01-02'
          format: date
          type: string
        interest:
          $ref: '#/components/schemas/FPSLInterest'
        market_value:
          description: The total market value of the shares on loan.
          example: 1138.25
          format: double
          type: number
        quantity:
          description: The number of shares in the loan. This may be less than the total number of eligible shares held by the account.
          example: 5
          format: int64
          type: integer
        symbol:
          description: Stock/Ticker symbol of a stock or security
          example: AAPL
          type: string
        updated_at:
          description: 'Timestamp of the last update to this loan in RFC-3339 format with microsecond precision with timezone.

            An updated value may indicate adjusted interest values.

            '
          example: '2025-03-21T15:54:19.857034+01:00'
          format: date-time
          type: string
      required:
      - date
      - account_id
      - account_number
      - correspondent
      - symbol
      - quantity
      - market_value
      - collateral
      type: object
    FPSLTier:
      properties:
        created_at:
          description: The timestamp the FPSL tier was created, in RFC 3339 format.
          example: '2024-09-16T20:06:32.207729Z'
          format: date-time
          type: string
        customer_split:
          description: Percentage of the customer split represented as a value between 0 and 1.00. Max 2 decimal places are allowed.
          example: 0.25
          type: number
        id:
          description: The unique identifier of the FPSL tier
          example: 150df7eb-31e7-46b3-8848-a54ca21ff3bc
          format: uuid
          type: string
        market:
          description: The market of the FPSL tier
          example: US
          type: string
        partner_split:
          description: Percentage of the partner split represented as a value between 0 and 1.00. Max 2 decimal places are allowed.
          example: 0.3
          type: number
        tier_name:
          description: The name of the FPSL tier
          example: gold
          type: string
        updated_at:
          description: The timestamp of the last update to the FPSL tier, in RFC 3339 format.
          example: '2024-09-16T20:06:32.207729Z'
          format: date-time
          type: string
      type: object
    FPSLAnalyticsLoansResponse:
      description: 'Aggregated FPSL interest and loan-activity counts for one account over a date range.

        '
      properties:
        account_number:
          description: Account's number at Alpaca
          example: '286873545'
          type: string
        in_progress_lending_activities:
          description: The number of FPSL lending activities currently in progress for the account.
          example: 2
          format: int64
          type: integer
        interest:
          $ref: '#/components/schemas/FPSLInterest'
        total_lending_activities:
          description: The total number of FPSL lending activities for the account within the specified date range.
          example: 7
          format: int64
          type: integer
      required:
      - account_number
      - total_lending_activities
      - in_progress_lending_activities
      type: object
    FPSLError:
      description: FPSL API error response
      properties:
        message:
          example: Internal Server Error
          type: string
      type: object
    FPSLInterest:
      description: 'The interest''s details.

        Please note that the object might not be set if interest has not yet been calculated for the loan.

        Additionally, interest details may be adjusted retroactively at any time until interests are finalized for the month.

        The loan''s changed `updated_at` field can indicate such an adjustment.

        '
      properties:
        customer:
          description: The interest accrued by the customer for this loan.
          example: 1.23
          format: double
          type: number
        partner:
          description: The interest accrued by the partner for this loan.
          example: 1.65
          format: double
          type: number
      required:
      - customer
      - partner
      type: object
  securitySchemes:
    BasicAuth:
      scheme: basic
      type: http
x-readme:
  explorer-enabled: true
  proxy-enabled: false