bitburner-src/doc/source/netscript/netscriptixapi.rst

.. _netscript_tixapi:

Netscript Trade Information eXchange (TIX) API
==============================================

The Trade Information eXchange (TIX) is the communications protocol supported by the World Stock Exchange (WSE).
The WSE provides an API that allows you to automatically communicate with the
:ref:`Stock Market <gameplay_stock_market>`.
This API lets you write code using Netscript
to build automated trading systems and create your own algorithmic trading strategies. Access to this
TIX API can be purchased by visiting the World Stock Exchange in-game.

Access to the TIX API currently costs $5 billion. After you purchase it, you will retain this
access even after you 'reset' by installing Augmentations

getStockSymbols
---------------

.. js:function:: getStockSymbols()

    :RAM cost: 2 GB

    Returns an array of the symbols of the tradable stocks

getStockPrice
-------------

.. js:function:: getStockPrice(sym)

    :param string sym: Stock symbol
    :RAM cost: 2 GB

    Returns the price of a stock, given its symbol (NOT the company name). The symbol is a sequence
    of two to four capital letters.

    Example::

        getStockPrice("FISG");

getStockPosition
----------------

.. js:function:: getStockPosition(sym)

    :param string sym: Stock symbol
    :RAM cost: 2 GB

    Returns an array of four elements that represents the player's position in a stock.

    The first element is the returned array is the number of shares the player owns of the stock in the
    `Long position <http://bitburner.wikia.com/wiki/Stock_Market#Positions:_Long_vs_Short>`_. The second
    element in the array is the average price of the player's shares in the Long position.

    The third element in the array is the number of shares the player owns of the stock in the
    `Short position <http://bitburner.wikia.com/wiki/Stock_Market#Positions:_Long_vs_Short>`_. The fourth
    element in the array is the average price of the player's Short position.

    All elements in the returned array are numeric.

    Example::

        pos = getStockPosition("ECP");
        shares      = pos[0];
        avgPx       = pos[1];
        sharesShort = pos[2];
        avgPxShort  = pos[3];

getStockMaxShares
-----------------


.. js:function:: getStockMaxShares(sym)

    :param string sym: Stock symbol
    :RAM cost: 2 GB

    Returns the maximum number of shares that the stock has. This is the maximum
    amount of the stock that can be purchased in both the Long and Short
    positions combined

buyStock
--------

.. js:function:: buyStock(sym, shares)

    :param string sym: Symbol of stock to purchase
    :param number shares: Number of shares to purchased. Must be positive. Will be rounded to nearest integer
    :RAM cost: 2.5 GB

    Attempts to purchase shares of a stock using a `Market Order <http://bitburner.wikia.com/wiki/Stock_Market#Order_Types>`_.

    If the player does not have enough money to purchase the specified number of shares, then no shares will be purchased. Remember
    that every transaction on the stock exchange costs a certain commission fee.

    If this function successfully purchases the shares, it will return the stock price at which each share was purchased. Otherwise,
    it will return 0.

sellStock
---------

.. js:function:: sellStock(sym, shares)

    :param string sym: Symbol of stock to sell
    :param number shares: Number of shares to sell. Must be positive. Will be rounded to nearest integer
    :RAM cost: 2.5 GB

    Attempts to sell shares of a stock using a `Market Order <http://bitburner.wikia.com/wiki/Stock_Market#Order_Types>`_.

    If the specified number of shares in the function exceeds the amount that the player actually owns, then this function will
    sell all owned shares. Remember that every transaction on the stock exchange costs a certain commission fee.

    The net profit made from selling stocks with this function is reflected in the script's statistics.
    This net profit is calculated as::

        shares * (sell price - average price of purchased shares)

    If the sale is successful, this function will return the stock price at which each share was sold. Otherwise, it will return 0.

shortStock
----------

.. js:function:: shortStock(sym, shares)

    :param string sym: Symbol of stock to short
    :param number shares: Number of shares to short. Must be positive. Will be rounded to nearest integer
    :RAM cost: 2.5 GB

    Attempts to purchase a `short <http://bitburner.wikia.com/wiki/Stock_Market#Positions:_Long_vs_Short>`_ position of a stock
    using a `Market Order <http://bitburner.wikia.com/wiki/Stock_Market#Order_Types>`_.

    The ability to short a stock is **not** immediately available to the player and must be unlocked later on in the game.

    If the player does not have enough money to purchase the specified number of shares, then no shares will be purchased.
    Remember that every transaction on the stock exchange costs a certain commission fee.

    If the purchase is successful, this function will return the stock price at which each share was purchased. Otherwise, it will return 0.

sellShort
---------

.. js:function:: sellShort(sym, shares)

    :param string sym: Symbol of stock to sell
    :param number shares: Number of shares to sell. Must be positive. Will be rounded to nearest integer
    :RAM cost: 2.5 GB

    Attempts to sell a `short <http://bitburner.wikia.com/wiki/Stock_Market#Positions:_Long_vs_Short>`_ position of a stock
    using a `Market Order <http://bitburner.wikia.com/wiki/Stock_Market#Order_Types>`_.

    The ability to short a stock is **not** immediately available to the player and must be unlocked later on in the game.

    If the specified number of shares exceeds the amount that the player actually owns, then this function will sell all owned
    shares. Remember that every transaction on the stock exchange costs a certain commission fee.

    If the sale is successful, this function will return the stock price at which each share was sold. Otherwise it will return 0.

placeOrder
----------

.. js:function:: placeOrder(sym, shares, price, type, pos)

    :param string sym: Symbol of stock to player order for
    :param number shares: Number of shares for order. Must be positive. Will be rounded to nearest integer
    :param number price: Execution price for the order
    :param string type: Type of order. It must specify "limit" or "stop", and must also specify "buy" or "sell". This is NOT
        case-sensitive. Here are four examples that will work:

        * limitbuy
        * limitsell
        * stopbuy
        * stopsell

    :param string pos:
        Specifies whether the order is a "Long" or "Short" position. The Values "L" or "S" can also be used. This is
        NOT case-sensitive.
    :RAM cost: 2.5 GB

    Places an order on the stock market. This function only works for `Limit and Stop Orders <http://bitburner.wikia.com/wiki/Stock_Market#Order_Types>`_.

    The ability to place limit and stop orders is **not** immediately available to the player and must be unlocked later on in the game.

    Returns true if the order is successfully placed, and false otherwise.

cancelOrder
-----------

.. js:function:: cancelOrder(sym, shares, price, type, pos)

    :param string sym: Symbol of stock to player order for
    :param number shares: Number of shares for order. Must be positive. Will be rounded to nearest integer
    :param number price: Execution price for the order
    :param string type: Type of order. It must specify "limit" or "stop", and must also specify "buy" or "sell". This is NOT
        case-sensitive. Here are four examples that will work:

        * limitbuy
        * limitsell
        * stopbuy
        * stopsell

    :param string pos:
        Specifies whether the order is a "Long" or "Short" position. The Values "L" or "S" can also be used. This is
        NOT case-sensitive.
    :RAM cost: 2.5 GB

    Cancels an oustanding Limit or Stop order on the stock market.

    The ability to use limit and stop orders is **not** immediately available to the player and must be unlocked later on in the game.

getOrders
---------

.. js:function:: getOrders()

    :RAM cost: 2.5 GB

    Returns your order book for the stock market. This is an object containing information
    for all the Limit and Stop Orders you have in the stock market.

    The object has the following structure::

        {
            StockSymbol1: [ // Array of orders for this stock
                {
                    shares: Order quantity
                    price: Order price
                    type: Order type
                    position: Either "L" or "S" for Long or Short position
                },
                {
                    ...
                },
                ...
            ],
            StockSymbol2: [ // Array of orders for this stock
                ...
            ],
            ...
        }

    The "Order type" property can have one of the following four values:

        * "Limit Buy Order"
        * "Limit Sell Order"
        * "Stop Buy Order"
        * "Stop Sell Order"

    **Note that the order book will only contain information for stocks that you actually
    have orders in**. For example, if you do not have orders in Nova Medical (NVMD), then the returned
    object will not have a "NVMD" property.

    Example::

        {
            ECP: [
                {
                    shares: 5,
                    price: 100,000
                    type: "Stop Buy Order",
                    position: "S",
                },
                {
                    shares: 25,
                    price: 125,000
                    type: "Limit Sell Order",
                    position: "L",
                },
            ],
            SYSC: [
                {
                    shares: 100,
                    price: 10,000
                    type: "Limit Buy Order",
                    position: "L",
                },
            ],
        }

getStockVolatility
------------------

.. js:function:: getStockVolatility(sym)

    :param string sym: Symbol of stock
    :RAM cost: 2.5 GB

    Returns the volatility of the specified stock.

    Volatility represents the maximum percentage by which a stock's price can
    change every tick. The volatility is returned as a decimal value, NOT
    a percentage (e.g. if a stock has a volatility of 3%, then this function will
    return 0.03, NOT 3).

    In order to use this function, you must first purchase access to the Four Sigma (4S)
    Market Data TIX API.

getStockForecast
----------------

.. js:function:: getStockForecast(sym)

    :param string sym: Symbol of stock
    :RAM cost: 2.5 GB

    Returns the probability that the specified stock's price will increase
    (as opposed to decrease) during the next tick.

    The probability is returned as a decimal value, NOT a percentage (e.g. if a
    stock has a 60% chance of increasing, then this function will return 0.6,
    NOT 60).

    In other words, if this function returned 0.30 for a stock, then this means
    that the stock's price has a 30% chance of increasing and a 70% chance of
    decreasing during the next tick.

purchase4SMarketData
--------------------

.. js:function:: purchase4SMarketData()

    :RAM cost: 2.5 GB

    Purchase 4S Market Data Access.

    Returns true if you successfully purchased it or if you already have access.
    Returns false otherwise.

purchase4SMarketDataTixApi
--------------------------

.. js:function:: purchase4SMarketDataTixApi()

    :RAM cost: 2.5 GB

    Purchase 4S Market Data TIX API Access.

    Returns true if you successfully purchased it or if you already have access.
    Returns false otherwise.