### Run a Tutorial Project

Source: https://github.com/tradovate/example-api-js/blob/main/README.md

Start a tutorial project after installing dependencies. Access the running project by navigating to localhost:8080 in your browser.

```bash
> yarn start
```

--------------------------------

### Install WebSocket Dependencies

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-05-WebSockets-Start/README.md

Navigate to the WebSocket tutorial directory and install project dependencies using yarn.

```bash
> cd c:/path/to/repo/tutorial/WebSockets/EX-5-WebSockets-Start
> yarn install
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/tradovate/example-api-js/blob/main/README.md

Install project dependencies using yarn. Navigate to the tutorial project's root directory before running this command.

```bash
> yarn install
```

--------------------------------

### Project Structure Overview

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/Access/EX-0-Access-Start/README.md

This illustrates the typical file and directory structure for the Tradovate API example projects.

```text
|-EX-0-Access-Start
|---src
|-----app.js
|-----connect.js
|-----services.js
|---babel.config.json
|---index.html
|---package.json
|---webpack.config.js
...
|-
```

--------------------------------

### Setup UI for Placing Orders

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-12-Calculating-Open-PL/README.md

This function sets up event listeners for buy and sell buttons to place market orders. It retrieves the primary account, validates symbol and quantity inputs, and then places the order via the API. It also synchronizes user data using the provided WebSocket socket.

```javascript
const setupUI = () => {

    const setupUI = (socket) => {

    const onClick = (buyOrSell = 'Buy') => async () => {
        //first available account
        const { name, id } = getAvailableAccounts()[0]

        if(!$symbol.value || !$qty.value) return

        let { orderId } = await tvPost('/order/placeOrder', {
            action: buyOrSell,
            symbol: $symbol.value,
            orderQty: parseInt($qty.value, 10),
            orderType: 'Market',
            accountName: name,
            accountId: id
        })
        console.log(orderId)
       
    }

    $buyBtn.addEventListener('click', onClick('Buy'))
    $sellBtn.addEventListener('click', onClick('Sell'))
}

```

--------------------------------

### Initiate Fetch Request

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/Access/EX-0-Access-Start/README.md

This snippet shows the basic structure of initiating a fetch request to a specific endpoint. It's the starting point for making API calls from a web browser.

```javascript
const connect = () => {
    fetch(DEMO_URL + '/auth/accesstokenrequest')
}
```

--------------------------------

### Subscribe to Chart Data

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-10-Chart-Data/README.md

Example of subscribing to real-time chart data using the socket.subscribe method with specific chart parameters.

```javascript
$getChart.addEventListener('click', async () => {
    unsubscribe = await socket.subscribe({
        url: 'md/getchart',
        body: {
            symbol: 'MNQZ1',
            chartDescription: {
                underlyingType: 'MinuteBar',
                elementSize: 30,
                elementSizeUnit: 'UnderlyingUnits',
                withHistogram: false,
            },
            timeRange: {
                asMuchAsElements: 20
            }
        },
        subscription: (chart) => {
            console.log(chart)
        }
    })
})
```

--------------------------------

### GET Request with tvGet

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/Access/EX-1-Simple-Request/README.md

Use tvGet for GET endpoints. It handles query string manipulation and JSON response decoding. The first parameter is the endpoint, and the optional second parameter is an object for the query string.

```javascript
//no parameters
const jsonResponseA = await tvGet('/account/list')
```

```javascript
//parameter object, URL will become '/contract/item?id=2287764'
const jsonResponseB = await tvGet('/contract/item', { id: 2287764 })
```

--------------------------------

### Connect Function with Time Penalty Handling

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/Access/EX-3-Time-Penalty/README.md

This function handles the time penalty response by checking for a 'p-ticket' and calling a retry function if present. It first checks for a valid existing access token before attempting to get a new one.

```javascript
export const connect = async (data) => {
    const { token, expiration } = getAccessToken()
    if(token && tokenIsValid(expiration)) {
        console.log('Already have an access token. Using existing token.')
        return
    }

    const authResponse = await tvPost('/auth/accesstokenrequest', data, false)

    //added branch
    if(authResponse['p-ticket']) {
        await handleRetry(data, authResponse)
    }

    const {accessToken, expirationTime, } = await tvPost('/auth/accesstokenrequest', data, false)

    setAccessToken(accessToken, expirationTime)
}
```

--------------------------------

### Get HTML Element References

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-10-Chart-Data/README.md

Obtain references to the HTML controls defined in the body for later use in event listeners and data retrieval.

```javascript
const main = async () => {
  //...
    const $getChart     = document.getElementById('get-chart-btn')
    const $symbol       = document.getElementById('symbol')
    const $type         = document.getElementById('type')
    const $nElements    = document.getElementById('n-elements')
    const $elemSize     = document.getElementById('elem-size')
  //...}
```

--------------------------------

### Authentication Request with tvPost

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/Access/EX-1-Simple-Request/README.md

This function uses tvPost to make an access token request. The third parameter 'false' is used to prevent the default Authentication header setup, which is necessary for the initial token request.

```javascript
//connect.js

export const connect = async (data) => {

    const json = await tvPost('/auth/accesstokenrequest', data, false)

    console.log(json)
}
```

--------------------------------

### Subscribe to Chart Data and Render

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-10-Chart-Data/README.md

Attaches an event listener to the 'Get Chart' button. On click, it subscribes to chart data via the 'md/getchart' WebSocket endpoint, processes incoming bar data, and renders a candlestick chart using CanvasJS.

```javascript
$getChart.addEventListener('click', async () => { 
    all_bars = []

    if(unsubscribe) unsubscribe()

    unsubscribe = await socket.subscribe({
        url: 'md/getchart',
        body: { 
            symbol: $symbol.value,
            chartDescription: {
                underlyingType: $type.value,
                elementSize: parseInt($elemSize.value),
                elementSizeUnit: 'UnderlyingUnits',
                withHistogram: false,
            },
            timeRange: {
                asMuchAsElements: parseInt($nElements.value)
            }
        },
        subscription: chart => { 

            if(chart.eoh) {
                console.log('end of history')
                return
            }
            
            let stockChart = new CanvasJS.StockChart("outlet", {
                title: {
                    text: `${$symbol.value} Chart`
                },
                charts: [
                    {						
						data: [
						{						
							type: "candlestick", //Change it to "spline", "area", "column"
							dataPoints : all_bars
						}
					]
						
						}],
                navigator: {
                    slider: {
                        minimum: new Date('2020 01 01'),
                        maximum: new Date()
                    }
                }
            }); 
            chart.bars.forEach(bar => {
                const { high, low, open, close, timestamp } = bar
                all_bars.push({x: new Date(timestamp), y: [open, high, low, close]})
            })

            stockChart.render()
        }
    })
})
```

--------------------------------

### Import URLs and Initialize WebSocket

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-05-WebSockets-Start/README.md

Import the URLs configuration and establish a WebSocket connection to the demo URL.

```javascript
import { URLs } from '../../../tutorialsURLs.js'
const { WS_DEMO_URL } = URLs

//...

const ws = new WebSocket(WS_DEMO_URL)
```

--------------------------------

### Connect and Fetch Account List

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/Access/EX-4-Test-Request/README.md

This snippet shows how to connect to the API and set up an event listener to fetch and handle account data when a button is clicked. Ensure the 'connect' function is properly configured.

```javascript
const main = async () => {
    connect({...})

    const $accountListBtn = document.querySelector('#get-acct-btn')

    $accountListBtn.addEventListener('click', async () => {
        let accounts = await tvGet('/account/list')
        handleAccountList(accounts)
    })
}
```

--------------------------------

### Initial WebSocket Request

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-07-Making-Requests/README.md

This snippet demonstrates a basic click event listener that sends a 'product/find' request with 'ETH' as the query parameter to the WebSocket.

```javascript
$reqBtn.addEventListener('click', () => {
    socket.send({
        url: 'product/find',
        query: 'name=ETH'
    })
})
```

--------------------------------

### Initializing TradovateSocket in App

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-06-Heartbeats/README.md

Demonstrates how to import and instantiate the `TradovateSocket` class in the main application file (`app.js`) to manage WebSocket connections.

```javascript
import { TradovateSocket } from './TradovateSocket.js'

//...

const { accessToken } = await connect(credentials)

const ws = new TradovateSocket()
ws.connect(WS_DEMO_URL, accessToken)
```

--------------------------------

### Initialize Connect Function

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/Access/EX-0-Access-Start/README.md

This JavaScript code snippet shows the basic structure of the `connect.js` file, including importing URLs and exporting an empty `connect` function.

```javascript
import { URLs } from '../../../tutorialsURLs'

const { DEMO_URL } = URLs

export const connect = () => { /*...*/ }

```

--------------------------------

### Order Placement Parameters

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/Access/EX-4a-Place-An-Order/README.md

Defines the structure for placing an order, including required and optional parameters.

```json
{
    accountSpec: "string",
    accountId: 0,
    clOrdId: "string",
    action: "Buy",          //required
    symbol: "string",       //required
    orderQty: 0,            //required
    orderType: "Limit",     //required
    price: 0,
    stopPrice: 0,
    maxShow: 0,
    pegDifference: 0,
    timeInForce: "Day",
    expireTime: "2019-08-24T14:15:22Z",
    text: "string",
    activationTime: "2019-08-24T14:15:22Z",
    customTag50: "string",
    isAutomated: true
}
```

--------------------------------

### Execute Connect Function

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/Access/EX-0-Access-Start/README.md

This snippet shows how to import and call the connect function to initiate the API request. Ensure the connect function is uncommented in app.js to run this.

```javascript
import { connect } from './connect'

connect()
```

--------------------------------

### WebSocket Connection and Subscription Logic

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-08-Realtime-Market-Data/README.md

This JavaScript code sets up a WebSocket connection, handles connection status updates, and manages subscriptions to real-time market data. It includes event listeners for user interactions like connecting, disconnecting, and requesting data.

```javascript
const main = async () => {

    const { accessToken } = await connect(credentials)

    //HTML elements
    const $outlet       = document.getElementById('outlet')
    const $reqBtn       = document.getElementById('request-btn')
    const $unsubBtn     = document.getElementById('unsubscribe-btn')
    const $connBtn      = document.getElementById('connect-btn')
    const $discBtn      = document.getElementById('disconnect-btn')
    const $statusInd    = document.getElementById('status')
    const $symbol       = document.getElementById('symbol')

    //The websocket helper tool
    const socket = new TradovateSocket()
    let lastSymb
    let unsubscribe

    //give user some feedback about the state of their connection
    //by adding an event listener to 'message' that will change the color
    const onStateChange = _ => {
        $statusInd.style.backgroundColor = 
            socket.ws.readyState == 0 ? 'gold'      //pending
        :   socket.ws.readyState == 1 ? 'green'     //OK
        :   socket.ws.readyState == 2 ? 'orange'    //closing
        :   socket.ws.readyState == 3 ? 'red'       //closed
        :   /*else*/                    'silver'    //unknown/default           
    }

    $connBtn.addEventListener('click', async () => {
        if(socket.ws && socket.ws.readyState === 1) return

        await socket.connect(URLs.MD_URL, accessToken)  
        //add your feedback function to the socket's
        socket.ws.addEventListener('message', onStateChange)
    })

    //disconnect socket on disconnect button click
    $discBtn.addEventListener('click', () => {
        if(socket.ws.readyState !== 1) return

        socket.ws.close()
        $statusInd.style.backgroundColor = 'red'
        $outlet.innerText = ''
        
    })

    $unsubBtn.addEventListener('click', () => {
        unsubscribe()
        lastSymb = ''
    })

    //clicking the request button will fire our request and initialize
    //a listener to await the response. This will trigger our renders.
    $reqBtn.addEventListener('click', async () => {

        lastSymb = $symbol.value
        unsubscribe = socket.subscribe({
            url: 'md/subscribequote',
            body: { symbol: $symbol.value },
            subscription:  data => {
                const newElement = document.createElement('div')
                newElement.innerHTML = renderQuote($symbol.value, data.entries)
                $outlet.firstElementChild
                    ? $outlet.firstElementChild.replaceWith(newElement)
                    : $outlet.append(newElement)
            }
        })
        
    })
}

main()

```

--------------------------------

### Import URLs Configuration

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/Access/EX-0-Access-Start/README.md

Demonstrates how the `URLs` object is imported from a shared configuration file, typically used for API endpoints.

```javascript
import { URLs } from '../../../tutorialsURLs'

```

--------------------------------

### Subscribe to User Data and Calculate Open P&L

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-12-Calculating-Open-PL/README.md

Connects to the Tradovate API, subscribes to user data, and then subscribes to market data for each open position to calculate and display real-time P&L. Requires credentials and DOM elements like $openPL and $posList.

```javascript
const main = async () => {

    const pls = []
    
    //combines all your open p&ls into one 
    const runPL = () => {
        const totalPL = pls.map(({pl}) => pl).reduce((a, b) => a + b, 0)
        $openPL.innerHTML = ` $${totalPL.toFixed(2)}`
    }

    //Connect to the tradovate API by retrieving an access token
    const { accessToken, userId } = await connect(credentials)

    const socket = new TradovateSocket({debugLabel: 'Realtime API'})
    await socket.connect(URLs.WS_DEMO_URL, accessToken)

    const mdsocket = new TradovateSocket({debugLabel: 'Market Data API'})
    await mdsocket.connect(URLs.MD_URL, accessToken)
    
    socket.subscribe({
        url: 'user/syncrequest',
        body: { users: [userId] },
        subscription: (item) => {
            if(item.users) { //this is the initial response
                const { positions, contracts, products } = item

                positions.forEach(async pos => {
                    if(pos.netPos === 0 && pos.prevPos === 0) return
            
                    //we need the name variable from the contract this position is related to
                    const { name } = contracts.find(contract => contract.id === pos.contractId)
            
                    //get the value per point from products
                    let item = products.find(product => product.name.startsWith(name))
                    
                    let vpp = item.valuePerPoint

                    //our subscription has an inner subscription
                    let unsubscribe = await mdsocket.subscribe({
                        url: 'md/subscribequote',
                        body: { symbol: name },
                        //entries is a field on the quote data object
                        subscription: ({entries}) => {
                            
                            let buy = pos.netPrice ? pos.netPrice : pos.prevPrice
                            const { Trade } = entries //current Trade quote
                            const { price } = Trade   //price of the Trade quote
                
                            let pl = (price - buy) * vpp * pos.netPos //our p&l formula
                            
                            //render the HTML
                            const element = document.createElement('div')
                            element.innerHTML = renderPos(name, pl, pos.netPos)
                            const $maybeItem = document.querySelector(`#position-list li[data-name="${name}"`) // Corrected escaping for inner quotes
                            $maybeItem ? $maybeItem.innerHTML = renderPos(name, pl, pos.netPos) : $posList.appendChild(element)
                
                            //update existing p&l or push a new one
                            const maybePL = pls.find(p => p.name === name)
                            if(maybePL) {
                                maybePL.pl = pl
                            } else {
                                pls.push({ name, pl })
                            }

                            //run the p&l reducer to get total p&l
                            runPL()
                            
                        }
                    })
                            
                })
            }
        }
    })
    //...
}
```

--------------------------------

### TradovateSocket Connect Method and Message Preparation

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-06-Heartbeats/README.md

Implements the `connect` method for establishing a WebSocket connection and handling the initial authorization message. The `prepareMessage` function is a utility for parsing incoming WebSocket data.

```javascript
TradovateSocket.prototype.connect = async function(url, token) {
    console.log('connecting...')
    const self = this

    return new Promise((res, rej) => {
        this.listeningURL = url
        this.ws = new WebSocket(url)
        //auth only
        this.ws.addEventListener('message', function onConnect(msg) {
            //we need 'self' to preserve outer 'this' value in event callbacks
            const [T, _] = prepareMessage(msg.data)
            if(T === 'o') {
                self.send({
                    url: 'authorize',
                    body: token,
                })
            }
        })
    })
}

function prepareMessage(raw) {
    const T = raw.slice(0, 1)
    const data = raw.length > 1 ? JSON.parse(raw.slice(1)) : []

    return [T, data]
}
```

--------------------------------

### Fetch and Render Product Data

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-07-Making-Requests/README.md

This snippet updates the click event listener to asynchronously fetch product data using the enhanced `socket.send` method and then renders the received data into a designated HTML element.

```javascript
$reqBtn.addEventListener('click', async () => {
    let data = await socket.send({
        url: 'product/find',
        query: `name=ETH`
    })

    const div = document.createElement('div')
    div.innerHTML = renderETH(data)
    $outlet.firstElementChild 
        ? $outlet.firstElementChild.replaceWith(div)
        : $outlet.appendChild(div)
    
})
```

--------------------------------

### Subscribe to Real-Time Chart Data

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-11-Tick-Charts/README.md

This snippet demonstrates how to subscribe to real-time chart data, handling both tick and regular chart types. It includes logic for unsubscribing from previous subscriptions, setting chart parameters, and processing incoming data in the subscription callback. Use this when you need to display live chart updates.

```javascript
//... 
    $getChart.addEventListener('click', async () => {  
        all_bars = []

        if(unsubscribe) unsubscribe() //unsubscribe existing subsciptions
        
        if($type.value === 'Tick') {
            _chart = getTickChart()
        } else {
            _chart = getRegularChart()
        }

        unsubscribe = await socket.subscribe({
            url: 'md/getchart',
            body: { 
                symbol: $symbol.value,
                chartDescription: {
                    underlyingType: $type.value,
                    elementSize: $type.value === 'Tick' || $type.value === 'DailyBar' ? 1 : parseInt($elemSize.value),
                    elementSizeUnit: 'UnderlyingUnits',
                    // withHistogram: true,
                },
                timeRange: {
                    ...{ asMuchAsElements: parseInt($nElements.value) },
                    // closestTimestamp: "2020-10-30T19:45:00.000Z",
                    asFarAsTimeStamp: "2020-05-01T19:45:00.000Z"
                }
            },    
            subscription: chart => {
                console.log(chart)
                // console.log($type.value)
                if($type.value === 'Tick') {
                    handleTickChart(chart)
                } else {
                    handleRegularChart(chart)
                } 
                _chart.render()
            }
        })
    })
//...
```

--------------------------------

### Initialize Data Array

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-10-Chart-Data/README.md

Declare an array to store the chart data points that will be fetched and processed.

```javascript
const main = async () => {
  let all_bars = []
  //...}
```

--------------------------------

### Subscribe to User Data Synchronization

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-07-Making-Requests/README.md

Connect to the WebSocket and subscribe to user data synchronization. This is essential for receiving real-time updates on account information. The callback function handles both the initial full data response and subsequent incremental updates.

```javascript
const main = async () => {
    const { accessToken, userId } = await connect(credentials)

    const socket = new TradovateSocket()
    await socket.connect(WS_DEMO_URL, accessToken)

    socket.subscribe({
        url: 'user/syncrequest',
        body: { users: [userId] },
        subscription: item => {
            if(item.users) {
                //initial response has the `users` field and contains all of your current user data
                const { 
                    accountRiskStatuses,
                    accounts,
                    cashBalances,
                    commandReports,
                    commands,
                    contractGroups,
                    contractMaturities,
                    contracts,
                    currencies,
                    exchanges,
                    executionReports,
                    fillPairs,
                    fills,
                    marginSnapshots,
                    orderStrategies, 
                    orderStrategyLinks,
                    orderStrategyTypes,
                    orderVersions,
                    orders,
                    positions,
                    products,
                    properties,
                    spreadDefinitions,
                    userAccountAutoLiqs,
                    userPlugins,
                    userProperties,
                    userReadStatuses,
                    users        
                } = item
                //do setup stuff with data
            } else {
                //after initial response, subscription events look like this
                const { entity, entityType, eventType } = item
            }
        }
    })
}
```

--------------------------------

### Handle Fetch Response with .then()

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/Access/EX-0-Access-Start/README.md

This snippet demonstrates how to handle the data returned from a fetch request using the .then() method of a Promise. It logs the received data to the console.

```javascript
const connect = () => {
    fetch(DEMO_URL + '/auth/accesstokenrequest')
        .then(data => console.log(data))
}
```

--------------------------------

### Render ETH Product Data

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-07-Making-Requests/README.md

A JavaScript function to generate HTML for displaying product details. It takes a product object and returns an HTML string.

```javascript
export const renderETH = ({
    allowProviderContractInfo,
    contractGroupId,
    currencyId,
    description,
    exchangeChannelId,
    exchangeId,
    id,
    isMicro,
    marketDataSource,
    name,
    priceFormat,
    priceFormatType,
    productType,
    status,
    tickSize,
    valuePerPoint,
}) => {
    return `
        <section>
            <h1>${name}</h1>
            <p>currency ID: ${currencyId == 1 ? '$' : currencyId}</p>
            <h3>info:</h3>
            <span>
                <div>allowProviderContractInfo: ${allowProviderContractInfo}</div>
                <div>contractGroupId: ${contractGroupId}</div>
                <div>exchangeChannelId: ${exchangeChannelId}</div>
                <div>exchangeId: ${exchangeId}</div>
                <div>id: ${id}</div>
                <div>isMicro: ${isMicro}</div>
                <div>marketDataSource: ${marketDataSource}</div>
                <div>priceFormat: ${priceFormat}</div>
                <div>priceFormatType: ${priceFormatType}</div>
                <div>productType: ${productType}</div>
                <div>status: ${status}</div>
                <div>tickSize: ${tickSize}</div>
                <div>valuePerPoint: ${valuePerPoint}</div>
            </span>
            <h3>Description</h3>
            <p>${description}</p>
        </section>
    `
}
```

--------------------------------

### HTML Structure for WebSocket Interaction

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-07-Making-Requests/README.md

Sets up the basic HTML elements for a WebSocket interaction, including buttons for requesting data and connecting, and a status indicator.

```html
<!DOCTYPE html>
<html>
  <head>
    <meta charset='utf-8'>
    <meta name='title' content='Project meta title'>
    <meta name='description' content='Project description'>
    <title>Tradovate API JS Example</title>
    <base href="./" />
    <style>
      #status {
        height: 1em;
        width: 1em;
        border-radius: 50%;
        background-color: silver;
      }

      span {
        display: flex;
        flex-direction: row;
        margin: auto;
        align-items: center;
        flex-wrap: wrap;
      }

      div { 
        margin: 1em;
        border-left: .1em solid black;
      }

      button {
        margin: 1em;
      }
    </style>
  </head>
  <body>
    <span>
      <button id="request-btn">ETH Details</button>
      <button id="connect-btn">Connect</button>
      <div id="status"></div>
    </span>
    <section id="outlet">
      <!-- stuff will get rendered here -->
    </section>
  </body>
</html>

```

--------------------------------

### HTML Structure for Market Data UI

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-08-Realtime-Market-Data/README.md

Provides the basic HTML structure for a web page designed to display real-time market data. It includes buttons for controlling the data feed (Watch, Unwatch, Connect, Disconnect), an input for specifying a symbol, and a status indicator.

```html
<!DOCTYPE html>
<html>
  <head>
    <meta charset='utf-8'>
    <meta name='title' content='Project meta title'>
    <meta name='description' content='Project description'>
    <title>Tradovate API JS Example</title>
    <base href="./" />
    <style>
      #status {
        transition: background-color .33s ease-in;
        height: 1em;
        width: 1em;
        border-radius: 50%;
        background-color: silver;
      }

      span {
        display: flex;
        flex-direction: row;
        margin: auto;
        align-items: center;
        flex-wrap: wrap;
      }

      div { margin: 1em; }

      section span div {
        height: 10em;
        width: 14.5em;        
        padding: 0 1em;
        box-shadow: 0 .2em .5em -.33em black;        
        border-radius: 4px;
      }

      button {
        margin: 1em;
      }
    </style>
  </head>
  <body>
    <span>
      <button id="request-btn">Watch</button>
      <button id="unsubscribe-btn">Unwatch</button>
      <input id="symbol" type="text" placeholder="BTCM1" />
      <button id="connect-btn">Connect</button>
      <button id="disconnect-btn">Disconnect</button>
      <div id="status"></div>
    </span>
    <section id="outlet">
      <!-- stuff will get rendered here -->
    </section>
  </body>
</html>

```

--------------------------------

### Place Order Function

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/Access/EX-4a-Place-An-Order/README.md

Asynchronously places an order using the Tradovate API, requiring account and access token information.

```javascript
export const placeOrder = async ({
    action, 
    symbol,
    orderQty,
    orderType, 
    accountSpec, 
    accountId, 
    clOrdId, 
    price, 
    stopPrice, 
    maxShow, 
    pegDifference,
    timeInForce, 
    expireTime, 
    text, 
    activationTime, 
    customTag50, 
    isAutomated
}) => {

    const { id, name } = getAvailableAccounts()[0]
    const { token } = getAccessToken()

    const normalized_body = {
        action, symbol, orderQty, orderType,
        isAutomated: isAutomated || false,
        accountId: id,
        accountSpec: name
    }    

    if(!token) {
        console.error('No access token found. Please acquire a token and try again.')
        return
    }

    const res = await tvPost('/order/placeOrder', normalized_body)

    return res
}
```

--------------------------------

### Connect and Store Access Token

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/Access/EX-2-Storing-A-Token/README.md

This function checks for an existing valid access token. If none is found, it requests a new one and stores it using `setAccessToken`.

```javascript
//connect.js

import { tvPost } from './services'
import { getAccessToken, setAccessToken, tokenIsValid } from './storage'

export const connect = async (data) => {
    const { token, expiration } = getAccessToken()
    if(token && tokenIsValid(expiration)) {
        console.log('Already have an access token. Using existing token.')
        return
    }
    const {accessToken, expirationTime} = await tvPost('/auth/accesstokenrequest', data, false)

    setAccessToken(accessToken, expirationTime)
}
```

--------------------------------

### TradovateSocket Constructor and Send Method

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-06-Heartbeats/README.md

Defines the `TradovateSocket` constructor and its `send` method for formatting WebSocket messages. It includes a counter for unique request IDs and abstracts away the manual string formatting of requests.

```javascript
//TradovateSocket.js
import { WSS_URL } from "./env";
import { getAccessToken } from './storage'

export function TradovateSocket() {
    let counter = 0
    
    this.ws = null
    this.increment = function() { return counter++ }
}

TradovateSocket.prototype.send = function({url, query, body}) {
    this.ws.send(`${url}\n${this.increment()}\n${query || ''}\n${body ? JSON.stringify(body) : ''}`)
}
```

--------------------------------

### Format and Send Authorization Request

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-05-WebSockets-Start/README.md

Construct and send an authorization request to the WebSocket server using the specified plain text format with newline delimiters.

```javascript
const { token } = getAccessToken()
const authRequest = `authorize\n1\n\n${token}`

ws.send(authRequest)
```

--------------------------------

### Registering a Message Event Listener

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-05-WebSockets-Start/README.md

Use the addEventListener method to dynamically register a callback function for 'message' events. This approach is an alternative to assigning to ws.onmessage and is preferred for managing multiple listeners.

```javascript
ws.addEventListener('message', myCallback)
```

--------------------------------

### Place Buy Market Order

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/Access/EX-4a-Place-An-Order/README.md

This code snippet connects to the Tradovate API and sets up an event listener to place a buy market order when a symbol is entered and the buy button is clicked. It uses default values for order quantity and type, requiring only the symbol.

```javascript
import { credentials } from '../../../tutorialsCredentials.js'
import { connect } from './connect'
import { ORDER_ACTION, ORDER_TYPE, placeOrder } from './placeOrder'


const main = async () => {
    //Connect to the tradovate API by retrieving an access token
    await connect(credentials)

    const $symbol = document.getElementById('symbol')
    const $input = document.getElementById('buy')

    $input.addEventListener('click', async () => {
        if(!$symbol.value) return 
        const response = await placeOrder({
            action: ORDER_ACTION.Buy,
            symbol: $symbol.value,
            orderQty: 1,
            orderType: ORDER_TYPE.Market,
        })
        console.log(response)
    })
}

//app entry point
main()
```

--------------------------------

### Credentials Configuration

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/Access/EX-0-Access-Start/README.md

This JavaScript object defines the structure for storing API credentials, including username, password, app ID, and secret key. Ensure these are filled with your actual data.

```javascript
export const credentials = {
    name:       "Your credentials here",
    password:   "Your credentials here",
    appId:      "Sample App",
    appVersion: "1.0",
    cid:        0,
    sec:        "Your API secret here"
}

```

--------------------------------

### HTML Structure for DOM Watcher

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-09-Realtime-Market-Data-Pt2/README.md

Adds buttons for subscribing and unsubscribing to DOM data, and a section for rendering the DOM information. Ensure corresponding styles are applied for readability.

```html
<!DOCTYPE html>
<html>
  <head>
    <meta charset='utf-8'>
    <meta name='title' content='Project meta title'>
    <meta name='description' content='Project description'>
    <title>Tradovate API JS Example</title>
    <base href="./" />
    <style>
      <!-- ... -->
    </style>
  </head>
  <body>
    <span>
      <button id="request-btn">Watch</button>
      <button id="unsubscribe-btn">Unwatch</button>
      <button id="connect-btn">Connect</button>
      <button id="disconnect-btn">Disconnect</button>
      <div id="status"></div>
    </span>
    <section id="outlet">
      <!-- stuff will get rendered here -->
    </section>

    <!-- new stuff here -->
    <span>
      <button id="subscribe-dom">Watch DOM</button>
      <button id="unsubscribe-dom">Unwatch DOM</button>
    </span>
    <section id="outlet-2">

    </section>
  </body>
</script>
```

--------------------------------

### HTML Structure for Tick Chart

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-11a-Tick-Charts-Solution/index.html

Sets up the basic HTML elements for displaying chart data, including status indicators, input fields, and buttons. This is the foundational structure for the charting application.

```html
<!DOCTYPE html>
<html>
<head>
<title>Tradovate API JS Example</title>
<style>
#status {
  transition: background-color .33s ease-in;
  height: 1em;
  width: 1em;
  border-radius: 50%;
  background-color: silver;
  margin: 0 1em;
}
span {
  display: flex;
  flex-direction: row;
  align-items: center;
  margin: 1em;
}
button {
  margin: 1em;
}
input {
  margin: 1em;
}
</style>
</head>
<body>

<span>
  <div id="status"></div>
  Connected
</span>

<button id="connect">Connect</button>
<button id="disconnect">Disconnect</button>

<br/>

<label for="symbol">Symbol:</label>
<input type="text" id="symbol" value="ES"/>

<br/>

<label for="chartType">Chart Type:</label>
<select id="chartType">
  <option value="MinuteBar">MinuteBar</option>
  <option value="Tick" selected>Tick</option>
  <option value="DailyBar">DailyBar</option>
</select>

<br/>

<div id="chartContainer"></div>

<script src="./index.js"></script>

</body>
</html>
```

--------------------------------

### Handle Account List Data

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/Access/EX-4-Test-Request/README.md

This function processes the account data received from the API and renders it as HTML. It dynamically creates and appends/replaces HTML elements in the '#outlet' element.

```javascript
export const handleAccountList = (data) => {
    const $outlet = document.querySelector('#outlet')
    
    data.forEach(item => {
        const { 
            accountType,
            active,
            archived,
            autoLiqProfileId,
            clearingHouseId,
            id,
            legalStatus,
            marginAccountType,
            name,
            riskCategoryId,
            userId,
        } = item

        const templateHtml = `
            <h1>Name: ${name}</h1>
            <h2>Account Type: ${accountType}</h2>
            <section>
                <div>Active: ${active ? 'Yes' : 'Inactive'}</div>
                <div>ID: ${id}</div>
                <div>UserID: ${userId}</div>
                <div>legalStatus: ${legalStatus}</div>
                <div>marginAccountType: ${marginAccountType}</div>
                <div>riskCategory: ${riskCategoryId}</div>
                <div>autoLiqProfileId: ${autoLiqProfileId}</div>
                <div>clearingHouseId: ${clearingHouseId}</div>
                <div>archived: ${archived}</div>
            </section>
        `

        const container = document.createElement('div')
        container.innerHTML = templateHtml

        if($outlet.firstElementChild) {            
            $outlet.firstElementChild.replaceWith(container)
        } else {
            $outlet.appendChild(container)
        }
    })
}
```

--------------------------------

### JavaScript WebSocket Connection and Status Indicator

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-07-Making-Requests/README.md

Establishes a WebSocket connection and updates a status indicator based on the WebSocket's ready state. It also adds a message event listener to the WebSocket.

```javascript
$connBtn.addEventListener('click', () => {
    socket.connect()
    socket.ws.addEventListener('message', msg => {
        $statusInd.style.backgroundColor = 
            socket.ws.readyState == 0 ? 'gold'      //pending
        :   socket.ws.readyState == 1 ? 'green'     //OK
        :   socket.ws.readyState == 2 ? 'orange'    //closing
        :   socket.ws.readyState == 3 ? 'red'       //closed
        :   /*else*/                    'silver'    //unknown|default           
    })
})

```

--------------------------------

### POST Request with tvPost

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/Access/EX-1-Simple-Request/README.md

Use tvPost for POST endpoints. It shares the same interface as tvGet, simplifying usage. The first parameter is the endpoint, and the second is an object for the JSON body.

```javascript
//placing an order with tvPost

const myAcct = getAvailableAccounts()[0] //<-- you can import this function from storage.js, but you need to have acquired an access token to use it.

const jsonResponseC = await tvPost('/order/placeorder', {
    accountSpec: myAcct.name,
    accountId: myAcct.id,
    action: 'Buy',
    symbol: 'MNQM1',
    orderQty: 2,
    orderType: 'Market',
    isAutomated: true //was this order placed by you pressing a button or by your robot?
})
```

--------------------------------

### HTML Controls for Chart Configuration

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-10-Chart-Data/README.md

These HTML elements provide user controls for selecting chart type, number of elements, and element size, along with a button to fetch the chart data.

```html
<body>

    <span>
      <button id="get-chart-btn">Get Chart</button>

      <label for="type">TYPE
        <select name="type" id="type">  
          <option value="MinuteBar">MinuteBar</option> 
          <option value="Tick">Tick</option>      
          <option value="DailyBar">DailyBar</option>      
        </select>
      </label>

      <label for="n-elements">#ELEMS
        <input name="n-elements" id="n-elements" type="number" min="1" value="100" max="500"  />
      </label>

      <label for="elem-size">ELEM SIZE
        <input name="elem-size" id="elem-size" type="number" min="1" value="30" max="720"  />
      </label>

      <div id="status"></div>
    </span>


    <span>
      <input id="symbol" type="text" placeholder="BTCJ1"/>
      <h1>Chart</h1>
    </span>

    <main id='outlet'>
      
    </main>
</body>
```

--------------------------------

### Subscribe to Depth of Market Data

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-09-Realtime-Market-Data-Pt2/README.md

Connects to the Market Data API and subscribes to Depth of Market data for a specified symbol. Requires authentication and a WebSocket connection.

```javascript
import { URLs } from '../../../tutorialsURLs'

const { MD_URL } = URLs

const main = async () => {
    const {accessToken} = await connect(credentials)
    
    const mySocket = new TradovateSocket({debugLabel: 'Market Data API'})
    await mySocket.connect(MD_URL, accessToken)

    const unsubscribe = await mySocket.subscribe({
        url: 'md/subscribedom',
        body: { symbol: 'MNQZ1' },
        subscription: (item) => {
            //...
        }
    })
}

main()
```

--------------------------------

### Basic WebSocket Event Handlers

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-05-WebSockets-Start/README.md

Assign custom functions to WebSocket events to log connection status, received messages, errors, and closure. This provides a fundamental way to monitor and react to WebSocket lifecycle events.

```javascript
ws.onopen = msg => console.log(msg)

//anytime you receive a message. All messages will be caught here
ws.onmessage = msg => console.log(msg)

//handle errors here
ws.onerror = err => console.error(err)

//when the connection closes. cleanup logic goes here
ws.onclose = msg => console.log(msg)
```

--------------------------------

### DOM Element References in App.js

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-09-Realtime-Market-Data-Pt2/README.md

References DOM elements for controlling Depth of Market subscriptions and rendering. These are used to attach event listeners and display data.

```javascript
//...
    const $watchDom     = document.getElementById('subscribe-dom')
    const $unwatchDom   = document.getElementById('unsubscribe-dom')
    const $outlet2      = document.getElementById('outlet-2')
    const $sym1         = document.getElementById('sym1')
    const $sym2         = document.getElementById('sym2')
//...
```

--------------------------------

### Generate and Set Device ID for 2FA

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/Access/EX-1-Simple-Request/README.md

This snippet demonstrates how to generate a device ID for multi-factor authentication. It handles different logic for browser and mobile environments and utilizes a utility function to cache the ID in browsers.

```javascript
import "device-uuid"
import { isMobile } from './utils/isMobile'
import { setDeviceId } from './storage.js'
import { credentials } from '../../../tutorialsCredentials.js'

//set device ID, behaves differently for browser and mobile device.
let DEVICE_ID
if(!isMobile()) {
    const device = getDeviceId()
    DEVICE_ID = device || new DeviceUUID().get()
    setDeviceId(DEVICE_ID)
} else {
    DEVICE_ID = new DeviceUUID().get()
}

const main = async () => {
    
    await connect(credentials)
    
}

main()

```

--------------------------------

### Chart Data Request Parameters

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-10-Chart-Data/README.md

Defines the structure for requesting chart data, including symbol, chart description (type, size, unit, histogram), and time range.

```json
{
  "symbol":"ESM7" | 123456,
  "chartDescription": {
    "underlyingType":"MinuteBar", // Available values: Tick, DailyBar, MinuteBar, Custom, DOM
    "elementSize":15,
    "elementSizeUnit":"UnderlyingUnits", // Available values: Volume, Range, UnderlyingUnits, Renko, MomentumRange, PointAndFigure, OFARange
    "withHistogram": true | false
  },
  "timeRange": {
    // All fields in "timeRange" are optional, but at least any one is required
    "closestTimestamp":"2017-04-13T11:33Z",
    "closestTickId":123,
    "asFarAsTimestamp":"2017-04-13T11:33Z",
    "asMuchAsElements":66
  },
}
```

--------------------------------

### Subscribe to DOM Data

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-09-Realtime-Market-Data-Pt2/README.md

Subscribes to real-time Depth of Market (DOM) data for a given symbol. The subscription callback updates a DOM element with the received data. Ensure the 'socket' object is initialized and the DOM elements ($watchDom, $sym2, $outlet2, $unwatchDom) are available.

```javascript
//...in main()

    $watchDom.addEventListener('click', async () => {

        unsubscribeDom = await socket.subscribe({
            url: 'md/subscribedom',
            body: { symbol: $sym2.value },
            subscription: data => {
                const newElement = document.createElement('div')
                newElement.innerHTML = renderDOM($sym2.value, data)
                $outlet2.firstElementChild
                    ? $outlet2.firstElementChild.replaceWith(newElement)
                    : $outlet2.append(newElement)
            }
        })
    })

    $unwatchDom.addEventListener('click', () => {
        unsubscribeDom()
    })
//...
```

--------------------------------

### Advanced WebSocket Message Handling with Switch

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-05-WebSockets-Start/README.md

Implement a detailed message handler that discriminates message types based on the first character of the data. This snippet includes logic for handling 'open' (authorization), 'heartbeat', 'data' (JSON parsing), and 'close' messages, along with error handling for unexpected types.

```javascript
ws.onmessage = msg => {

    const { data } = msg
    const type = data.slice(0,1) // what kind of message is this? the first character lets us know

    //message discriminator
    switch(type) {
        case 'o':
            console.log('Opening Socket Connection...')
            const { token } = getAccessToken()
            ws.send(`authorize\n0\n\n${token}`) //we need to send our auth message on the 'open' frame 
            break
        case 'h':
            console.log('received server heartbeat...')
            break
        case 'a':
            const data = JSON.parse(msg.data.slice(1))
            console.log(data)
            break
        case 'c':
            console.log('closing websocket')
            break
        default:
            console.error('Unexpected response token received:')
            console.error(msg)
            break;
    }

}
```

--------------------------------

### Generic WebSocket Send Implementation

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-07-Making-Requests/README.md

This enhanced `send` method for TradovateSocket returns a Promise that resolves or rejects based on the WebSocket response. It handles message listening, response matching by ID, and error reporting.

```javascript
TradovateSocket.prototype.send = async function({url, query, body, onResponse, onReject}) {
    const self = this

    return new Promise((res, rej) => {
        const id = this.increment()
        this.ws.addEventListener('message', function onEvent(msg) {
            const [_, data] = prepareMessage(msg.data)        
            data.forEach(item => {
                if(item.s === 200 && item.i === id) {  
                    if(onResponse) {
                        onResponse(item)
                    }
                    self.ws.removeEventListener('message', onEvent)
                    res(item)
                } else if(item.s && item.s !== 200 && item.i && item.i === id) {
                    console.log(item)
                    self.ws.removeEventListener('message', onEvent)
                    if(onReject) onReject()
                    rej(`
FAILED:
	operation '${url}'
	query ${query ? JSON.stringify(query, null, 2) : ''}
	body ${body ? JSON.stringify(body, null, 2) : ''}
	reason '${JSON.stringify(item?.d, null, 2) || 'unknown'}'`)
                } 
            })
        })
        this.ws.send(`${url}\n${id}\n${query || ''}\n${body ? JSON.stringify(body) : ''}`)
    })
}
```

--------------------------------

### Initialize Chart Variable in Main Function

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-11-Tick-Charts/README.md

This JavaScript snippet shows how to declare a chart variable at the top of the main function scope. This variable will be used to hold the chart instance, whether it's a regular or tick chart.

```javascript
const main = async () => {
    let all_bars = []
    let subscription
    let _chart

    //...
}
```

--------------------------------

### WebSocket Request with Query Parameter

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-07-Making-Requests/README.md

A WebSocket request format that includes an endpoint, an ID, and a query parameter.

```plaintext
tradingPermission/ldeps
8
masterids=1

```

--------------------------------

### Subscribe to Realtime Quote Data

Source: https://github.com/tradovate/example-api-js/blob/main/tutorial/WebSockets/EX-08-Realtime-Market-Data/README.md

Connects to the market data WebSocket URL and subscribes to quote updates for a specified symbol. The subscription function processes incoming quote items. It returns an unsubscribe function to stop receiving updates.

```javascript
import { URLs } from '../../../tutorialsURLs'

const { MD_URL } = URLs

const main = async () => {
    const { accessToken } = await connect(credentials)
    
    const mySocket = new TradovateSocket({debugLabel: 'Market Data API'})
    await mySocket.connect(MD_URL, accessToken)

    const unsubscribe = await mySocket.subscribe({
        url: 'md/subscribequote',
        body: { symbol: 'MNQZ1' },
        subscription: (item) => {
            //...
        }
    })
}

main()


```