openapi: 3.0.3
info:
  title: Firstrade Unofficial Account Watchlist API
  description: 'Community-reverse-engineered REST API for the Firstrade Securities brokerage platform (https://www.firstrade.com). This is NOT an official Firstrade API. Endpoints are discovered from network traffic analysis and are subject to change without notice. The base URL is the internal mobile/web gateway used by the Firstrade app. Authentication uses a session-based flow with cookie tokens (ftat, sid) obtained after login. All requests require the Accept-Encoding: gzip and access-token header values documented below. Source: MaxxRK/firstrade-api (MIT licence).'
  version: 0.1.0
  contact:
    name: Firstrade Customer Support
    url: https://www.firstrade.com/support
  license:
    name: MIT (community SDK)
    url: https://opensource.org/licenses/MIT
  x-official: false
  x-source-repo: https://github.com/MaxxRK/firstrade-api
servers:
- url: https://api3x.firstrade.com
  description: Firstrade mobile / web API gateway
tags:
- name: Watchlist
  description: Watchlist CRUD operations
paths:
  /private/watchlists:
    get:
      operationId: listWatchlists
      summary: List all watchlists
      description: Returns all watchlists for the authenticated user.
      tags:
      - Watchlist
      security:
      - sessionAuth: []
      responses:
        '200':
          description: Watchlist collection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
    post:
      operationId: createWatchlist
      summary: Create a watchlist
      description: Creates a new watchlist.
      tags:
      - Watchlist
      security:
      - sessionAuth: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Watchlist name
      responses:
        '200':
          description: Created watchlist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /private/watchlists/{list_id}:
    get:
      operationId: getWatchlist
      summary: Get a watchlist
      description: Returns a single watchlist by ID.
      tags:
      - Watchlist
      security:
      - sessionAuth: []
      parameters:
      - name: list_id
        in: path
        required: true
        schema:
          type: integer
        description: Watchlist ID
      responses:
        '200':
          description: Watchlist details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
    delete:
      operationId: deleteWatchlist
      summary: Delete a watchlist
      description: Deletes the specified watchlist.
      tags:
      - Watchlist
      security:
      - sessionAuth: []
      parameters:
      - name: list_id
        in: path
        required: true
        schema:
          type: integer
        description: Watchlist ID
      responses:
        '200':
          description: Deletion result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /private/all_watchlist_items:
    get:
      operationId: getAllWatchlistItems
      summary: Get all watchlist items
      description: Returns every symbol across all watchlists for the authenticated user.
      tags:
      - Watchlist
      security:
      - sessionAuth: []
      responses:
        '200':
          description: All watchlist items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /private/watchlist/{list_id}:
    post:
      operationId: addWatchlistItem
      summary: Add symbol to watchlist
      description: Adds a ticker symbol to the specified watchlist.
      tags:
      - Watchlist
      security:
      - sessionAuth: []
      parameters:
      - name: list_id
        in: path
        required: true
        schema:
          type: integer
        description: Watchlist ID
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                symbol:
                  type: string
                  description: Ticker symbol to add
      responses:
        '200':
          description: Item added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
    delete:
      operationId: deleteWatchlistItem
      summary: Delete a watchlist item
      description: Removes a symbol from the specified watchlist.
      tags:
      - Watchlist
      security:
      - sessionAuth: []
      parameters:
      - name: list_id
        in: path
        required: true
        schema:
          type: integer
        description: Watchlist item ID
      responses:
        '200':
          description: Item deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
components:
  schemas:
    ApiResponse:
      type: object
      properties:
        error:
          type: string
          description: Empty string on success; error message on failure
          example: ''
      additionalProperties: true
  securitySchemes:
    sessionAuth:
      type: apiKey
      in: header
      name: ftat
      description: 'Session token obtained after login. The ftat header must be accompanied by a sid header (session ID) and the static access-token header (value: 833w3XuIFycv18ybi).'