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

[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.]{
style="color:#cece7d;background-color:#b2a9248f;"
}

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=Limitations-,TWS%20Software,-Click%20a%20version
) 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.
![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 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:

```{python}
#| eval: false
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:
![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.
