---
title: Overview
jupyter:
  kernelspec:
    display_name: Python 3 (ipykernel)
    language: python
    name: python3
---

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](https://www.interactivebrokers
.com/en/trading/ib-api.php), and are made accessible within [Posit's Shiny
framework](https://shiny.posit.co/) -- 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**](https://www.interactivebrokers
.com/en/trading/tws.php#:~:text=TWS%20SOFTWARE) for your OS. TWS (Trader
Workstation) 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.
![TWS Demo Login](data/tws_demo_login)

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:
![Settings Menu](data/api_config)

8) Install ShinyBroker with `pip install shinybroker`

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

```{python}
#| eval: false
import os
import shinybroker as sb
from shiny import Inputs, Outputs, Session, App


# Project Settings
os.environ['IB_HOST'] = '127.0.0.1'
os.environ['IB_PORT'] = '7497'
os.environ['IB_CLIENT_ID'] = '10645'

app = App(sb.sb_ui(), sb.sb_server)

app.run()
```

This code performs three main operations:

- Defines where ShinyBroker can find a running instance of an IBKR client (TWS)
- Creates a Shiny `app` object using only the base ShinyBroker ui and server
- 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:

```{python}
#| eval: false
import os
import shinybroker as sb
from shiny import Inputs, Outputs, Session, App, ui, render


# Project Settings
os.environ['IB_HOST'] = '127.0.0.1'
os.environ['IB_PORT'] = '7497'
os.environ['IB_CLIENT_ID'] = '10645'


app_ui = sb.sb_ui(
    ui.div(
        ui.input_text(
            id='sb_example_text_in',
            label='Example Input. Type something!'
        ),
        ui.output_code('sb_example_text_out')
    )
)


def user_defined_server(input:Inputs, outputs:Outputs, session:Session):
    @render.code
    def sb_example_text_out():
        return f"You entered '{input.sb_example_text_in()}'."


def server(input:Inputs, outputs:Outputs, session:Session):
    sb.sb_server(input, outputs, session)
    user_defined_server(input, outputs, session)


app = App(app_ui, server)


app.run()
```

Here, we have done two things:

- added a **ui**: We added a text input and a text output contained within a div
- added a **server** function: it reads whatever text has been input by the user
 into the text_input, appends "You entered " to the beginning of it, and returns
  the text to the text output.

12) Run the modified code above. Your app should now look something like the
screenshot below:
![Hello World Screenshot](data/hello_world)

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.
