openapi: 3.0.3
info:
  title: IBKR Trading Engine Webhook API
  version: 1.0.2
  description: |
    Receive webhook alerts from TradingView, MetaTrader, Pine Script, or any JSON-capable system.
    Triggers live orders in IBKR via ib_insync. Replace `{{SECRET}}` with your actual token.
servers:
  - url: https://tradingwhale.io/api/v1
paths:
  /webhook:
    post:
      summary: Receive a trading alert and execute an order
      description: |
        Accepts JSON payloads specifying your bot ID, symbol, asset type, action, quantity,
        order type, time-in-force, alert price, exit flag, and strategy ID.
      operationId: receiveWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - secret
                - bot_id
                - symbol
                - asset_type
                - action
                - quantity
                - order_type
                - tif
                - alert_price
                - is_exit
                - strategy_id
              properties:
                secret:
                  type: string
                  description: Your webhook secret token
                  example: "sjibcbwecbewbcebjbwejvb"
                bot_id:
                  type: string
                  description: Identifier for your bot instance
                  example: "BOT1"
                symbol:
                  type: string
                  description: Ticker symbol, e.g. 'AAPL'
                  example: "AAPL"
                asset_type:
                  type: string
                  enum: [STOCK, OPTION, FUTURE, CASH]
                  description: Asset class
                  example: "STOCK"
                action:
                  type: string
                  enum: [BUY, SELL]
                  description: Order direction
                  example: "BUY"
                quantity:
                  type: number
                  description: Number of shares or contracts
                  example: 10
                order_type:
                  type: string
                  enum: [MKT, LMT]
                  description: Order type (MKT=market, LMT=limit)
                  example: "MKT"
                tif:
                  type: string
                  enum: [GTC, DAY]
                  description: Time in force (GTC=good-till-cancelled, DAY=today only)
                  example: "GTC"
                alert_price:
                  type: number
                  description: Price at which the alert fired
                  example: 150.25
                is_exit:
                  type: boolean
                  description: True if this order is an exit from a position
                  example: false
                strategy_id:
                  type: string
                  description: Your internal strategy identifier
                  example: "SOXL"
      responses:
        '200':
          description: Alert received and order sent to IBKR
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "success"
                  orderId:
                    type: integer
                    example: 123456789
        '401':
          description: Unauthorized (invalid secret)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '400':
          description: Bad request (missing or invalid fields)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        status:
          type: string
          example: "error"
        message:
          type: string
          example: "Invalid secret token"