openapi: 3.0.3
info:
  title: Firstrade Unofficial 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: Authentication
    description: Session login and MFA flows
  - name: Account
    description: Account list, balances, positions, and history
  - name: Orders
    description: Equity and option order placement, listing, and cancellation
  - name: Market Data
    description: Stock quotes, OHLC chart data, and option chains
  - name: Watchlist
    description: Watchlist CRUD operations

paths:
  /:
    get:
      operationId: initSession
      summary: Initialise session
      description: >-
        Fetches the API root to establish an initial session and receive the
        ftat token that must accompany subsequent requests.
      tags:
        - Authentication
      responses:
        '200':
          description: Session initialised
          content:
            application/json:
              schema:
                type: object

  /sess/login:
    post:
      operationId: login
      summary: Login to Firstrade
      description: >-
        Authenticates a user with username and password. On success returns a
        session ID (sid) and optionally an ftat cookie. When MFA is required the
        response includes a t_token and mfa/otp details.
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - username
                - password
              properties:
                username:
                  type: string
                  description: Firstrade account username
                password:
                  type: string
                  format: password
                  description: Firstrade account password
      responses:
        '200':
          description: Login response (may require MFA step)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '401':
          description: Invalid credentials

  /sess/request_code:
    post:
      operationId: requestMfaCode
      summary: Request OTP code via email or SMS
      description: >-
        Triggers delivery of a one-time passcode to the user's registered email
        or phone number. Used when email/phone MFA is required.
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - recipientId
                - t_token
              properties:
                recipientId:
                  type: string
                  description: OTP recipient ID returned by the login call
                t_token:
                  type: string
                  description: Temporary token from the login response
      responses:
        '200':
          description: Code dispatched
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  /sess/verify_pin:
    post:
      operationId: verifyPin
      summary: Verify MFA code or PIN
      description: >-
        Submits an MFA code (TOTP, PIN, or OTP) to complete authentication.
        On success returns ftat and sid tokens.
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                pin:
                  type: string
                  description: Static PIN (if pin-based MFA)
                mfaCode:
                  type: string
                  description: TOTP or MFA code
                otpCode:
                  type: string
                  description: Email/SMS OTP code
                verificationSid:
                  type: string
                  description: Verification SID from the request_code response
                t_token:
                  type: string
                  description: Temporary token from the login response
                remember_for:
                  type: string
                  enum: ['30']
                  description: Trust this device for 30 days
      responses:
        '200':
          description: MFA verified, session tokens returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'

  /private/userinfo:
    get:
      operationId: getUserInfo
      summary: Get user information
      description: Returns profile details for the authenticated user.
      tags:
        - Account
      security:
        - sessionAuth: []
      responses:
        '200':
          description: User information object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  /private/acct_list:
    get:
      operationId: getAccountList
      summary: List all accounts
      description: >-
        Returns all accounts associated with the authenticated user including
        account numbers and total portfolio values.
      tags:
        - Account
      security:
        - sessionAuth: []
      responses:
        '200':
          description: Account list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountListResponse'

  /private/balances:
    get:
      operationId: getAccountBalances
      summary: Get account balances
      description: >-
        Returns detailed balance information for a specific account including
        cash, buying power, equity, and margin values.
      tags:
        - Account
      security:
        - sessionAuth: []
      parameters:
        - name: account
          in: query
          required: true
          description: Account number
          schema:
            type: string
      responses:
        '200':
          description: Account balances
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  /private/positions:
    get:
      operationId: getAccountPositions
      summary: Get account positions
      description: Returns currently held positions for the specified account.
      tags:
        - Account
      security:
        - sessionAuth: []
      parameters:
        - name: account
          in: query
          required: true
          description: Account number
          schema:
            type: string
        - name: per_page
          in: query
          required: false
          description: Number of positions per page (default 200)
          schema:
            type: integer
            default: 200
      responses:
        '200':
          description: Account positions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  /private/account_history:
    get:
      operationId: getAccountHistory
      summary: Get account history
      description: >-
        Returns transaction history for the specified account. Supports
        predefined date ranges and custom date ranges.
      tags:
        - Account
      security:
        - sessionAuth: []
      parameters:
        - name: account
          in: query
          required: true
          schema:
            type: string
          description: Account number
        - name: range
          in: query
          required: true
          schema:
            type: string
            enum: [today, 1w, 1m, 2m, mtd, ytd, ly, cust]
          description: Date range preset
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          required: false
          schema:
            type: integer
            default: 1000
        - name: range_arr[]
          in: query
          required: false
          schema:
            type: string
          description: Start date (YYYY-MM-DD) when range=cust; provide twice for start and end
      responses:
        '200':
          description: Account history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  /private/order_status:
    get:
      operationId: getOrders
      summary: List orders
      description: Returns open and recent orders for the specified account.
      tags:
        - Orders
      security:
        - sessionAuth: []
      parameters:
        - name: account
          in: query
          required: true
          schema:
            type: string
          description: Account number
        - name: per_page
          in: query
          required: false
          schema:
            type: integer
          description: Number of orders per page (0 = all)
      responses:
        '200':
          description: Order list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  /private/stock_order:
    post:
      operationId: placeEquityOrder
      summary: Place equity order
      description: >-
        Places or previews a stock/ETF order. Set preview=true for dry-run
        validation without submitting. To confirm, re-submit with preview=false
        and stage=P.
      tags:
        - Orders
      security:
        - sessionAuth: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/EquityOrderRequest'
      responses:
        '200':
          description: Order preview or confirmation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  /private/cancel_order:
    post:
      operationId: cancelOrder
      summary: Cancel an order
      description: Cancels an existing open order by order ID.
      tags:
        - Orders
      security:
        - sessionAuth: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - order_id
              properties:
                order_id:
                  type: string
                  description: The ID of the order to cancel
      responses:
        '200':
          description: Cancellation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  /private/option_order:
    post:
      operationId: placeOptionOrder
      summary: Place option order
      description: >-
        Places or previews an options contract order. Set preview=true for
        dry-run validation. Re-submit with preview=false to confirm.
      tags:
        - Orders
      security:
        - sessionAuth: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/OptionOrderRequest'
      responses:
        '200':
          description: Option order preview or confirmation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  /private/greekoptions/analytical:
    post:
      operationId: getGreekOptions
      summary: Get options Greeks
      description: Returns delta, gamma, theta, vega, and rho for an option chain.
      tags:
        - Market Data
      security:
        - sessionAuth: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - type
                - root_symbol
                - exp_date
              properties:
                type:
                  type: string
                  enum: [chain]
                  default: chain
                chains_range:
                  type: string
                  enum: [A]
                  default: A
                  description: "A = all strikes"
                root_symbol:
                  type: string
                  description: Underlying ticker symbol
                exp_date:
                  type: string
                  description: Expiration date (YYYYMMDD)
      responses:
        '200':
          description: Greeks data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  /public/quote:
    get:
      operationId: getQuote
      summary: Get stock quote
      description: >-
        Returns real-time or delayed bid/ask, last price, volume, OHLC, and
        company metadata for a ticker symbol.
      tags:
        - Market Data
      security:
        - sessionAuth: []
      parameters:
        - name: account
          in: query
          required: true
          schema:
            type: string
          description: Account number (required for authentication context)
        - name: q
          in: query
          required: true
          schema:
            type: string
          description: Ticker symbol (e.g. AAPL)
      responses:
        '200':
          description: Stock quote
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuoteResponse'

  /public/ohlc:
    get:
      operationId: getOHLC
      summary: Get OHLC chart data
      description: >-
        Returns open-high-low-close and volume time-series data for charting.
        Timestamps are Unix milliseconds.
      tags:
        - Market Data
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
          description: Ticker symbol
        - name: range
          in: query
          required: true
          schema:
            type: string
            enum: [24h, 1d, 1w, 1m, 1y]
          description: Time range for the OHLC data
        - name: _v
          in: query
          required: false
          schema:
            type: string
            default: v2
          description: API version parameter
      responses:
        '200':
          description: OHLC data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OHLCResponse'

  /public/oc:
    get:
      operationId: getOptionData
      summary: Get option chain data
      description: >-
        Returns option expiration dates (m=get_exp_dates) or full option chain
        quotes (m=get_oc) for a given underlying symbol and expiration date.
      tags:
        - Market Data
      parameters:
        - name: m
          in: query
          required: true
          schema:
            type: string
            enum: [get_exp_dates, get_oc]
          description: Operation mode
        - name: root_symbol
          in: query
          required: true
          schema:
            type: string
          description: Underlying ticker symbol
        - name: exp_date
          in: query
          required: false
          schema:
            type: string
          description: Expiration date (required for m=get_oc), format YYYYMMDD
        - name: chains_range
          in: query
          required: false
          schema:
            type: string
            enum: [A]
            default: A
          description: "A = all strikes"
      responses:
        '200':
          description: Option dates or chain data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  /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:
  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).

  schemas:
    ApiResponse:
      type: object
      properties:
        error:
          type: string
          description: Empty string on success; error message on failure
          example: ''
      additionalProperties: true

    LoginResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
      properties:
        sid:
          type: string
          description: Session ID
        ftat:
          type: string
          description: Session authentication token (set as header on subsequent calls)
        t_token:
          type: string
          description: Temporary token used for MFA verification
        mfa:
          type: boolean
          description: Whether TOTP MFA is required
        otp:
          type: array
          description: OTP delivery options when email/SMS MFA is required
          items:
            type: object
            properties:
              channel:
                type: string
                enum: [email, sms]
              recipientId:
                type: string
              recipientMask:
                type: string

    AccountListResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              account:
                type: string
                description: Account number
              total_value:
                type: string
                description: Total portfolio value

    QuoteResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
      properties:
        result:
          type: object
          properties:
            symbol:
              type: string
            sec_type:
              type: string
              description: Security type
            tick:
              type: string
            bid:
              type: string
            bid_size:
              type: string
            ask:
              type: string
            ask_size:
              type: string
            last:
              type: string
              description: Last traded price
            change:
              type: string
            high:
              type: string
            low:
              type: string
            open:
              type: string
            today_close:
              type: number
            vol:
              type: string
              description: Trading volume
            quote_time:
              type: string
            last_trade_time:
              type: string
            company_name:
              type: string
            exchange:
              type: string
            has_option:
              type: string
            is_etf:
              type: boolean
            is_fractional:
              type: boolean
            realtime:
              type: string
            nls:
              type: string
              description: Nasdaq last sale indicator
            shares:
              type: string
            bid_mmid:
              type: string
            ask_mmid:
              type: string
            last_mmid:
              type: string
            last_size:
              type: integer
            change_color:
              type: string

    OHLCResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
      properties:
        result:
          type: object
          properties:
            startOfDay:
              type: integer
              description: Unix timestamp (ms) for the start of the trading day
            ohlc:
              type: array
              description: Array of [timestamp_ms, open, high, low, close] candles
              items:
                type: array
                items:
                  type: number
            vol:
              type: array
              description: Array of [timestamp_ms, volume] pairs
              items:
                type: array
                items:
                  type: number

    EquityOrderRequest:
      type: object
      required:
        - symbol
        - transaction
        - price_type
        - duration
        - account
      properties:
        symbol:
          type: string
          description: Ticker symbol
        transaction:
          type: string
          enum: [B, S, SS, BC]
          description: >-
            Order side: B=Buy, S=Sell, SS=Sell Short, BC=Buy to Cover
        price_type:
          type: string
          enum: ['1', '2', '3', '4', '5', '6']
          description: >-
            1=Market, 2=Limit, 3=Stop, 4=Stop Limit,
            5=Trailing Stop ($), 6=Trailing Stop (%)
        duration:
          type: string
          enum: ['0', D, N, '1']
          description: >-
            0=Day (9:30-4 ET), D=Day Extended (8-8 ET),
            N=Overnight (8PM-4AM ET), 1=GT90
        account:
          type: string
          description: Account number
        shares:
          type: integer
          description: Number of shares (omit for notional orders)
        dollar_amount:
          type: number
          description: Dollar amount for notional/fractional orders
        limit_price:
          type: number
          description: Limit price (required for Limit and Stop Limit orders)
        stop_price:
          type: number
          description: Stop price (required for Stop and Stop Limit orders)
        instructions:
          type: string
          enum: ['0', '1', '4', '5']
          description: >-
            0=None, 1=All-or-None, 4=At the Open, 5=At the Close
        preview:
          type: string
          enum: ['true', 'false']
          default: 'true'
          description: true=dry-run validation; false=submit order
        stage:
          type: string
          enum: [P]
          description: Set to P when confirming a previewed order

    OptionOrderRequest:
      type: object
      required:
        - symbol
        - transaction
        - price_type
        - duration
        - contracts
        - account
      properties:
        symbol:
          type: string
          description: OCC option symbol
        transaction:
          type: string
          enum: [BO, SO]
          description: BO=Buy Option, SO=Sell Option
        price_type:
          type: string
          enum: ['1', '2', '3', '4', '5', '6']
          description: >-
            1=Market, 2=Limit, 3=Stop, 4=Stop Limit,
            5=Trailing Stop ($), 6=Trailing Stop (%)
        duration:
          type: string
          enum: ['0', D, N, '1']
        contracts:
          type: integer
          description: Number of option contracts
        account:
          type: string
        limit_price:
          type: number
          description: Limit price (required for Limit and Stop Limit orders)
        stop_price:
          type: number
          description: Stop price (required for Stop and Stop Limit orders)
        instructions:
          type: string
          enum: ['0', '1', '4', '5']
        preview:
          type: string
          enum: ['true', 'false']
          default: 'true'