openapi: 3.0.0
info:
  version: 0.10.0 beta
  title: StocksTrader REST API
  description: StocksTrader REST API

servers:
  - url: https://api.stockstrader.com/
    description: Trading server

paths:
  /api/v1/logout:
    post:
      summary: Logout
      operationId: Logout
      tags:
        - Authorization
      description: Terminate the user session (or perform the logout flow).
      security:
        - BearerToken: []
      responses:
        200:
          description: response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/SuccessResponse'
                  - $ref: '#/components/schemas/ErrorResponse'
        401:
          description: "Unauthorized"

  /api/v1/instruments:
    get:
      summary: Instruments common info
      operationId: GetInstrumentList
      tags:
        - Instruments
      description: Get a list of all trading instruments available in StocksTrader in general (excluding the rules and restrictions for a specific trading account).
      responses:
        200:
          description: response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/InstrumentsResponse'
                  - $ref: '#/components/schemas/ErrorResponse'
          
  /api/v1/accounts/{account_id}/instruments/{ticker}:
    get:
      summary: Get instrument trading info
      operationId: GetInstrumentInfo
      tags:
        - Instruments
      parameters:
        - $ref: '#/components/parameters/account_id'
        - $ref: '#/components/parameters/ticker'
      security:
        - BearerToken: []
      description: Get trading conditions of trading instrument (including availability) for a specific account. Need to be used before placing an order for a particular trading instrument, not for all trading instruments
      responses:
        200:
          description: response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/InstrumentResponse'
                  - $ref: '#/components/schemas/ErrorResponse'
        401:
          description: "Unauthorized"

  /api/v1/accounts/{account_id}/instruments/{ticker}/quote:
    get:
      summary: Get quotes data
      operationId: GetQuoteData
      tags:
        - Quotes
      parameters:
        - $ref: '#/components/parameters/account_id'
        - $ref: '#/components/parameters/ticker'
      security:
        - BearerToken: []
      description: Get the latest ask/bid/last quotes for an instrument.
      responses:
        200:
          description: response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/QuoteDataResponse'
                  - $ref: '#/components/schemas/ErrorResponse'
        401:
          description: "Unauthorized"

  /api/v1/accounts:
    get:
      summary: Accounts
      operationId: GetAccounts
      tags:
        - Account
      description: Get a list of user accounts.
      security:
        - BearerToken: []
      responses:
        200:
          description: response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/AccountResponse'
                  - $ref: '#/components/schemas/ErrorResponse'
        401:
          description: "Unauthorized"
          
  /api/v1/accounts/{account_id}:
    get:
      summary: Account State
      operationId: GetAccountState
      tags:
        - Account
      description: Get account information.
      parameters:
        - $ref: '#/components/parameters/account_id'
      security:
        - BearerToken: []
      responses:
        200:
          description: response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/AccountStateResponse'
                  - $ref: '#/components/schemas/ErrorResponse'
        401:
          description: "Unauthorized"

  /api/v1/accounts/{account_id}/orders:
    get:
      summary: Orders
      operationId: GetOrders
      tags:
        - Account
      description: Get a list of orders or perform searches through order history if optional parameters are specified.
      parameters:
        - $ref: '#/components/parameters/account_id'
        - $ref: '#/components/parameters/status'
        - $ref: '#/components/parameters/history_from'
        - $ref: '#/components/parameters/history_to'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/limit'
      security:
        - BearerToken: []
      responses:
        200:
          description: response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/OrdersResponse'
                  - $ref: '#/components/schemas/ErrorResponse'
        401:
          description: "Unauthorized"
    post:
      summary: Place Order
      operationId: PlaceOrder
      tags:
        - Trading
      description: |
        Place a new order (Market, Limit, Stop).
      parameters:
        - $ref: '#/components/parameters/account_id'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              allOf:
                - $ref: '#/components/schemas/PlaceOrderCommon'
                - $ref: '#/components/schemas/PlaceModifyOrderCommon'
              required:
                - ticker
                - volume
                - side
                - type
      security:
        - BearerToken: []
      responses:
        200:
          description: response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/PostOrderResponse'
                  - $ref: '#/components/schemas/ErrorResponse'
        401:
          description: "Unauthorized"
          
  /api/v1/accounts/{account_id}/deals:
    get:
      summary: Deals
      operationId: GetDeals
      tags:
        - Account
      description: Get a list of deals or deals history if optional parameters are specified.
      parameters:
        - $ref: '#/components/parameters/account_id'
        - $ref: '#/components/parameters/history_from'
        - $ref: '#/components/parameters/history_to'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/limit'
      security:
        - BearerToken: []
      responses:
        200:
          description: response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/DealsResponse'
                  - $ref: '#/components/schemas/ErrorResponse'
        401:
          description: "Unauthorized"

  /api/v1/accounts/{account_id}/orders/{order_id}:
    put:
      summary: Modify Order
      operationId: modifyOrder
      tags:
        - Trading
      description: Modify Limit or Stop order parameters.
      parameters:
        - $ref: '#/components/parameters/account_id'
        - $ref: '#/components/parameters/order_id'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              allOf:
                - $ref: '#/components/schemas/PlaceModifyOrderCommon'

      security:
        - BearerToken: []
      responses:
        200:
          description: response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/SuccessResponse'
                  - $ref: '#/components/schemas/ErrorResponse'
        401:
          description: "Unauthorized"
          
    delete:
      summary: Cancel Order
      operationId: cancelOrder
      tags:
        - Trading
      description: Delete unfulfilled Limit or Stop order.
      parameters:
        - $ref: '#/components/parameters/account_id'
        - $ref: '#/components/parameters/order_id'
      security:
        - BearerToken: []
      responses:
        200:
          description: response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/SuccessResponse'
                  - $ref: '#/components/schemas/ErrorResponse'
        401:
          description: "Unauthorized"
          
  /api/v1/accounts/{account_id}/deals/{deal_id}:
    put:
      summary: Modify Deal
      operationId: ModifyDeal
      tags:
        - Trading
      description: |
        Set Stop Loss/Take Profit order for an open deal or edit them.
      parameters:
        - $ref: '#/components/parameters/account_id'
        - $ref: '#/components/parameters/deal_id'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ModifyDealRequestBody'
      security:
        - BearerToken: []
      responses:
        200:
          description: response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/SuccessResponse'
                  - $ref: '#/components/schemas/ErrorResponse'
        401:
          description: "Unauthorized"
          
    delete:
      summary: Close Deal
      operationId: CloseDeal
      tags:
        - Trading
      description: Close an open deal.
      parameters:
        - $ref: '#/components/parameters/account_id'
        - $ref: '#/components/parameters/deal_id'
      security:
        - BearerToken: []
      responses:
        200:
          description: response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/SuccessResponse'
                  - $ref: '#/components/schemas/ErrorResponse'
        401:
          description: "Unauthorized"
          
components:
  securitySchemes:
    BearerToken:
      type: http
      scheme: bearer
      bearerFormat: Bearer ACCESS_TOKEN

  parameters:
    history_from:
      name: history_from
      in: query
      description: Unix timestamp (UTC) of left boundary of the search.
      schema:
        type: number
      required: false

    history_to:
      name: history_to
      in: query
      description: Unix timestamp (UTC) of right boundary of the search.
      schema:
        type: number
      required: false

    order_id:
      name: order_id
      description: Order identifier.
      in: path
      schema:
        type: string
      required: true

    account_id:
      name: account_id
      in: path
      description: Account identifier.
      schema:
        type: string
      required: true
      
    ticker:
      name: ticker
      in: path
      description: Instrument identifier.
      schema:
        type: string
      required: true

    deal_id:
      name: deal_id
      description: Deal identifier.
      in: path
      schema:
        type: string
      required: true

    symbol:
      name: symbol
      in: query
      description: Symbol name or ticker.
      schema:
        type: string
      required: true
      
    status:
      name: status
      description: Type of orders.
      in: query
      schema:
        type: string
        enum:
          - filled
          - rejected
          - canceled
          - active
          - in_execution
      required: false
      
    skip:
      name: skip
      in: query
      description: Defines the number of elements to skip from the beginning of the original dataset (used for data pagination). Default 0. For example, if skip = 100, the first 100 elements will be skipped, and the selection will start from the 101st element.
      schema:
        type: number
      required: false
      
    limit:
      name: limit
      in: query
      description: Defines the maximum number of elements to be included in the response (used for data pagination). Default 100. Limited from above by the value 500. For example, if limit = 200, the response will return a maximum of 200 elements. Or for example (combined), if skip =100 and limit=200, the response will return a list of 200 orders, starting from the 101st to the 300th order.
      schema:
        type: number
      required: false
      
  schemas:
    Account:
      title: Account
      type: object
      properties:
        id:
          description: Unique account identifier.
          type: string
          example: '93012898'
        name:
          description: Account title that is displayed to a user.
          type: string
          example: 'My Demo-Hedg account'
        type:
          description: Account type (Real/Demo)
          type: string
          enum:
            - real
            - demo
          example: 'demo'
        system:
          description: Account trade system (Hedging/Netting).
          type: string
          enum:
            - hedging
            - netting
          example: 'netting'
        currency:
          description: Abbreviation of account currency.
          type: string
          example: 'USD'
        status:
          description: Status of the account
          type: string
          enum:
            - enabled
            - disabled
            - no_new_deals
          example: 'enabled'
      required:
        - id
        - name
        - description
        - type
        - system
        - currency
        - status
      additionalProperties: false

    AccountResponse:
      title: AccountResponse
      type: object
      properties:
        code:
          $ref: '#/components/schemas/CodeOk'
        data:
          type: array
          items:
            $ref: '#/components/schemas/Account'
          minItems: 1
      required:
        - code
        - data
      additionalProperties: false

    AccountMarginState:
      type: object
      properties:
        balance:
          description: Account Balance.
          type: number
        unrealized_pl:
          description: Unrealized profit/loss.
          type: number
          example: '-1512.32'
        equity:
          description: Equity.
          type: number
          example: '32000.00'
        margin:
          description: Required Margin.
          type: number
          example: '-8300.68'
        free_margin:
          description: Free Margin.
          type: number
          example: '-145278.98'
      required:
        - balance
        - unrealized_pl
        - equity
        - margin
        - free_margin
      additionalProperties: false
      
    AccountCashState:
      type: object
      properties:
        my_portfolio:
          description: Equity.
          type: number
          example: '12300.00'
        investments:
          description: Investments.
          type: number
          example: '1512.32'
        available_to_invest:
          description: Available To Invest.
          type: number
          example: '32000.00'
      required:
        - my_portfolio
        - investments
        - available_to_invest
      additionalProperties: false
      
    AccountState:
      type: object
      properties:
          cash:
            $ref: '#/components/schemas/AccountCashState'
          margin:
            $ref: '#/components/schemas/AccountMarginState'
      additionalProperties: false

    AccountStateResponse:
      title: AccountStateResponse
      type: object
      properties:
        code:
          $ref: '#/components/schemas/CodeOk'
        data:
          $ref: '#/components/schemas/AccountState'
      required:
        - code
        - data
      additionalProperties: false
      
    ErrorResponse:
      title: ErrorResponse
      type: object
      properties:
        code:
          type: string
          description: Code will always be `error`.
          enum:
            - error
          example: 'error'
        msg:
          type: string
          description: Error message.
          example: 'An error occurred.'
      required:
        - code
        - msg
      additionalProperties: false

    InstrumentShort:
      title: InstrumentShort
      type: object
      properties:
        ticker:
          description: Instrument name.
          type: string
          example: 'EURUSD'
        description:
          description: Instrument description.
          type: string
          example: 'EUR/USD'
        contract_size:
          description: Financial instrument units standardized number as set by the exchange or broker for buying or selling.
          type: number
          example: 1
        units:
          description: Units of quantity or amount.
          type: string
          example: Share(s)
      required:
        - ticker
        - description
        - contract_size
        - units
      additionalProperties: false
      
    Instrument:
      title: Instrument
      type: object
      properties:
        min_volume:
          description: Minimum volume for trading.
          type: number
          example: 1
        max_volume:
          description: Maximum volume for trading.
          type: number
          example: 100000000
        volume_step:
          description: Volume step.
          type: number
          example: 0.01
        min_tick:
          description: Minimum price movement. For example, for IBM `min_tick` is 0.01, for EURCAD `min_tick` is 0.00001.
          type: number
          example: 0.00001
        leverage:
          description: Leverage for this instrument.
          type: number
          example: 0.05
        trade_mode:
          description: Trade mode
          type: string
          enum:
            - full
            - buy_only
            - sell_only
            - close_only
            - disabled
          example: full
      required:
        - min_volume
        - max_volume
        - volume_step
        - min_tick
        - leverage
        - trade_mode
      additionalProperties: false

    InstrumentsResponse:
      title: InstrumentsResponse
      type: object
      properties:
        code:
          $ref: '#/components/schemas/CodeOk'
        data:
          type: array
          items:
            $ref: '#/components/schemas/InstrumentShort'
      required:
        - code
        - data
      additionalProperties: false
      
      
    InstrumentResponse:
      title: InstrumentResponse
      type: object
      properties:
        code:
          $ref: '#/components/schemas/CodeOk'
        data:
          $ref: '#/components/schemas/Instrument'
      required:
        - code
        - data
      additionalProperties: false

    CodeOk:
      title: CodeOk
      type: string
      description: Code will always be `ok`.
      enum:
        - ok
      example: 'ok'

    Order:
      title: Order
      allOf:
        - $ref: '#/components/schemas/OrderCommon'
        - $ref: '#/components/schemas/OrderStatus'

    OrderCommon:
      title: OrderCommon
      type: object
      properties:
        id:
          description: Unique identifier.
          type: string
          example: '002212096'
        ticker:
          description: Instrument identifier that is used on a broker's side.
          type: string
          example: 'AAPL'
        volume:
          description: Quantity.
          type: number
          example: '13'
        side:
          description: Side.
          type: string
          enum:
            - buy
            - sell
          example: 'buy'
        type:
          description: Type.
          type: string
          enum:
            - market
            - stop
            - limit
            - stop_out
            - stop_loss 
            - take_profit
          example: 'limit'
        filled_price:
          description: |
            Price of order fills.
          type: number
          example: '137.82'
        price:
          description: Limit Price for Limit or StopPrice for stop.
          type: number
          example: '137.84'
        expiration:
          description: Expiration date time, Unix timestamp (UTC).
          type: number
          example: '1705888778'
        last_modified:
          description: Indicates the time when the order was last modified, Unix timestamp (UTC).
          type: number
          example: '1704879978'
        comment:
          description: Additional text information.
          type: string
        deals:
          description: Related deals.
          type: array
          items:
            type: string
            example: '001389'
      required:
        - id
        - ticker
        - volume
        - side
        - type
        - deals

    QuoteDataResponse:
      title: QuoteDataResponse
      type: object
      properties:
        code:
          $ref: '#/components/schemas/CodeOk'
        data:
          type: object
          properties:
            ask_price:
              description: Ask price.
              type: number
              example: '100.75'
            bid_price:
              description: Bid price.
              type: number
              example: '100.25'
            last_price:
              description: Last price.
              type: number
              example: '100.50'
          additionalProperties: false
      required:
        - code
        - data
      additionalProperties: false

    OrdersResponse:
      title: OrdersResponse
      type: object
      properties:
        code:
          $ref: '#/components/schemas/CodeOk'
        data:
          type: array
          items:
            $ref: '#/components/schemas/Order'
      required:
        - code
        - data
      additionalProperties: false

    OrderStatus:
      title: OrderStatus
      type: object
      properties:
        status:
          description: String constants to describe an order status.
          type: string
          enum:
            - in_execution
            - active
            - rejected
            - filled
            - canceled
          example: 'filled'
      required:
        - status
        
    DealStatus:
      title: DealStatus
      type: object
      properties:
        status:
          description: String constants to describe an deal status.
          type: string
          enum:
            - open
            - closing
            - closed
            - trade
          example: 'closed'
      required:
        - status

    PlaceModifyOrderCommon:
      title: PlaceModifyOrderCommon
      type: object
      properties:
        volume:
          description: The number of units.
          type: number
          example: 1
        price:
          description: Limit Price for Limit or Stop Price for Stop.
          type: number
          example: 1.23456
        expiration:
          description: Unix timestamp (UTC) in seconds. 0 value means gtc (good till cancel).
          type: number
          example: 1706528750
        stop_loss:
          description: Stop Loss price.
          type: number
        take_profit:
          description: Take Profit price.
          type: number
      additionalProperties: false

    PlaceOrderCommon:
      title: PlaceOrderCommon
      type: object
      properties:
        ticker:
          description: Ticker.
          type: string
          example: EURUSD
        side:
          description: Side.
          type: string
          enum:
            - buy
            - sell
          example: buy
        type:
          description: Type.
          type: string
          enum:
            - market
            - stop
            - limit
          example: limit

    DealCommon:
      title: DealCommon
      type: object
      properties:
        id:
          description: Unique identifier.
          type: string
          example: '001389'
        ticker:
          description: Instrument identifier that is used on a broker's side.
          type: string
          example: 'TSLA'
        volume:
          description: Quantity.
          type: number
          example: 1
        side:
          description: Side.
          type: string
          enum:
            - buy
            - sell
          example: 'buy'
        open_price:
          description: Open price of deal.
          type: number
          example: 142.13
        open_time:
          description: Unix timestamp (UTC)
          type: number
          example: 1704880553
        profit:
          description: Realized/Unrealized profit.
          type: number
          example: 19.47
        close_price:
          description: Close price of deal.
          type: number
          example: 142.13
        close_time:
          description: Unix timestamp (UTC).
          type: number
          example: 1704880553
      required:
        - id
        - ticker
        - volume
        - side
        - open_price
        - open_time
        - profit
      additionalProperties: false
    
    Deal:
      title: Deal
      allOf:
        - $ref: '#/components/schemas/DealCommon'
        - $ref: '#/components/schemas/DealStatus'
        
    DealsResponse:
      title: DealsResponse
      type: object
      properties:
        code:
          $ref: '#/components/schemas/CodeOk'
        data:
          type: array
          items:
            $ref: '#/components/schemas/Deal'
      required:
        - code
        - data
      additionalProperties: false

    ModifyDealRequestBody:
      type: object
      properties:
        stop_loss:
          description: Stop Loss price.
          type: number
          example: 1.283568
        take_profit:
          description: Take Profit price.
          type: number
          example: 1.294436

    PostOrderResponse:
      title: PostOrderResponse
      type: object
      properties:
        code:
          $ref: '#/components/schemas/CodeOk'
        data:
          type: object
          properties:
            order_id:
              type: string
              description: New order identifier.
              example: '001518'
          additionalProperties: false
      required:
        - code
        - data
      additionalProperties: false

    SuccessResponse:
      title: SuccessResponse
      type: object
      properties:
        code:
          type: string
          description: Code will always be `ok`.
          enum:
            - ok
          example: 'ok'
      required:
        - code
      additionalProperties: false
