# Overview

Welcome! The ShinyBroker package and this website are under frequent heavy development, with new features and examples posted almost daily as they are written and tested.

ShinyBroker is based on the realization that in trading, everything is a reactive variable. Your orders, the prices of assets you’re tracking, current positions, Greeks, p/l– everything is time-dynamic, and can trigger trade order events according to algorithms written by the user. In ShinyBroker, those dynamic variables are kept updated over a socket connection to your account – live or paper – at Interactive Brokers, and are made accessible within Posit’s Shiny framework – a brilliant piece of coding that provides a natural sandbox for reactive variables and their live visualization as webpages.

The ‘hello world’ example below will walk you through a trivial setup case. You do not need an account at Interactive Brokers in order to follow the example, but it is suggested that you set up a free paper trader account with them if you’re interested in keeping track of your trades.

## Hello World Example

Run the base ShinyBroker app, and inject a simple bit of UI & server code.

1. Download and install TWS Latest for your OS. TWS (TraderWorkstation) is what ShinyBroker connects to in order to communicate with IBKR and the market exchanges. Whenever you use ShinyBroker, you’ll need to have TWS open and running.

2. Open up TWS and sign in to the demo by clicking the link indicated by the yellow rectangle below. You’ll be asked for an email and whether or not you’d like IBKR to contact you. If you have a paper account already then you can certainly use it, so just sign in as usual.

3. Once you’re signed in, familiarize yourself with the system until you’re ready to move on. If you used a demo account, know that any trades you make will be erased when you log out.

4. Open the API Configuration menu using the File dropdown. You can find the menu at File > Global Configuration > API > Settings.

5. Check Enable ActiveX and Socket Clients

6. Un-check Read-only API

7. You can leave the rest of the settings alone. By default, your settings menu should look like the below:

8. Install ShinyBroker with `pip install shinybroker`

9. In Python, run the following: (make sure TWS is open and running)

    import shinybroker as sb

    # Create an instance of a ShinyBroker App object using the default ui and server
    app = sb.sb_app(
        host='127.0.0.1',  # localhost TWS is being served on your local machine
        port=7497,         # make this match the port in your API Settings config
        client_id=10742    # picked at random, choose another Client ID if preferred
    )

    # Run the app
    app.run()

This code performs three main operations:

- Defines where ShinyBroker can find a running instance of an IBKR client (TWS) (`host` and `port`) and what client ID to use when connecting (`client_id`)
- Creates a ShinyBroker `sb_app` object
- Runs the app

10. Click the link in the command line to open up a web browser at localhost and explore the app.

Note that there is nothing in the “home” tab. That space is reserved for you, the user, to inject your own graphics, controls, inputs & outputs, as well as your algorithm logic.

Let’s demonstrate that functionality by injecting some UI, and the server code to handle the backend, into this base ShinyBroker app.

11. Stop the running instance of the ShinyBroker app and modify your code as shown below:

    import shinybroker as sb
    from shiny import Inputs, Outputs, Session, ui, render

    # Some UI to add to the app
    a_piece_of_new_ui = ui.div(
        ui.input_text(
            id='sb_example_text_in',
            label='Example Input. Type something!'
        ),
        ui.output_code('sb_example_text_out')
    )

    # Server to support the new UI
    # Signature must always contain the following five parameters:
    #   input, output, session, ib_socket, and sb_rvs
    def a_server_function(
            input: Inputs, output: Outputs, session: Session, ib_socket, sb_rvs
    ):
        @render.code
        def sb_example_text_out():
            return f"You entered '{input.sb_example_text_in()}'."

    # Create a ShinyBroker app with the new ui and server
    app = sb.sb_app(
        a_piece_of_new_ui,
        a_server_function,
        host='127.0.0.1',
        port=7497,
        client_id=10742
    )

    app.run()

Here, we have added two additional elements: a `ui` and a `server()`, just like we normally would when building a Shiny app with the Core syntax.

- ui: We added a text input and a text output contained within a div
- server: A Shiny server function just like a normal server function except that its signature includes a fourth argument – `ib_socket` – in addition to the usual three (`input`, `output`, `session`). The simple function in this example reads whatever text has been input by the user into the text_input, appends “You entered” to the beginning of it, and renders the text as output.

12. Run the modified code above. Your app should now look something like the screenshot below:

If you can get that far, success! From this simple starting point you can build a trading algorithm that does just about anything. More usage examples that cover market data, orders, positions, and other topics will be treated in other tutorials and videos accessible on this site.