README.md

Finance Charts Android SDK

Finance Charts SDK adds professional-grade financial charting capabilities for native iOS & Android apps.

It is built on top of the SciChart – an award-winning, high-performance chart SDK for iOS, Android, Windows, and JavaScript apps.

Our SDK library may be licensed for inclusion in your trading apps, exchange apps, or investment/brokerage apps, with pricing on the application.

NOTE: To see what could be done with Finance and SciChart, please try our SciTrader Android and iOS app.

What is the Android Finance SDK?

• Native Android (Kotlin) Financial Chart Library
• Build Trading Apps, Exchange Apps, or Investment/Brokerage Apps
• A single View or Control to display a multi-pane stock or financial chart
• Built for CryptoCurrency markets but also suitable for Equities, FX
• Support for 20 built-in Technical Indicators (MACD, RSI, Moving Average, etc)
• Automatic Management of Panels
• Interactive Cursors and Legends
• Auto-fit zoom or manual fit data
• Data management and reactive updates from exchange
• Resizing of panels
• Rich, Touch Zoom, Pan interaction
• Ultra High performance: using gaming technology, achieve fast & smooth charts even on low-end mobile and desktop devices
• Theming, styling
• Whitelabel the Android Finance SDK into your app

Table of Contents

1. Integration
   1. Manual
   2. Maven
2. QuickStart
3. Studies
4. FinanceSeries
5. Panes
6. DataProvider and DataManager

Integrating Finance SDK Manually

Please follow these steps to integrate Android Finance SDK:

1. Clone the Finance.Android repo
2. In your project File/New/Import module and select finance folder from in the Finance.Android cloned repo.
3. Add SciChart maven URL.

NOTE: Finance SDK is built on top of the SciChart library. It means you also need to get SciChart lib dependency.

Add maven URL to your repositories in the **settings:

maven { url 'https://www.myget.org/F/abtsoftware/maven' }

NOTE: To integrate SciChart manually, please follow the corresponding article in the SciChart documentation.

Also, make sure, the line include ':finance' is added in the same file.

4. Add implementation project(path: ":finance") to the dependencies in your module build.gradle file.
5. Sync project.

Integrating Finance SDK Using Maven

1. Add maven { url 'https://www.myget.org/F/abtsoftware/maven' } to your repositories in the settings.gradle file
2. Add Finance and SciChart implementations in your module build.gradle file.

// Declare Finance as module dependencies
implementation project(path: ":finance")

// Declare SciChart libraries as module dependencies
def sciChartVersion = '4.3.0.4686'
api(group: 'com.scichart.library', name: 'core', version: "$sciChartVersion", ext: 'aar')
api(group: 'com.scichart.library', name: 'data', version: "$sciChartVersion", ext: 'aar')
api(group: 'com.scichart.library', name: 'drawing', version: "$sciChartVersion", ext: 'aar')
api(group: 'com.scichart.library', name: 'charting', version: "$sciChartVersion", ext: 'aar')

NOTE: Finance SDK is built on top of the SciChart library. It means you also need to get SciChart lib dependency.

3. Sync project.

Quickstart

NOTE: Finance SDK is built on top of the SciChart library. To use it, you must have an active SciChart license. For more details, please, follow the SciChart Android Licensing page.

Finance SDK allows you to create a full-blown finance chart app with a few lines of code.

The central place of the Finance SDK is the SciFinanceChart. It holds studies, panes, data provider, chart modifiers, such as cursor, legend etc.

Let's see how you can create a chart just in a few steps:

1. Add a SciFinanceChart view to your .xml file:

<com.scitrader.finance.SciFinanceChart
    android:id="@+id/financeChart"
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>

2. Create DataProvider.

val candleDataProvider = DefaultCandleDataProvider()
chart.candleDataProvider = candleDataProvider

// fill the dataProvider with your candlestick data
fillDataProvider(candleDataProvider, StubDataManager.getCandles())

NOTE: Please follow the DataProvider and DataManager section for more details.

3. Create Studies. Study is the object that is responsible for charting business logic. Here you decide what your chart should display and how it should be visualized - as a candlestick, line, column, mountain, etc.

As an example, let's add two studies - PriceSeriesStudy to show candlesticks and RSIStudy to show RSI(Relative Strength Index) indicator:

val priceSeriesStudy = PriceSeriesStudy(PaneId.DEFAULT_PANE)
val rsiStudy = RSIStudy(PaneId.uniqueId("RSI"))
        
chart.studies.add(priceSeriesStudy)
chart.studies.add(rsiStudy)

NOTE: Creating our priceSeriesStudy with a PaneId.DEFAULT_PANE pane id means that we want to place our study on the main pane. If you want it to be a separate pane, create your study with some unique id, as we did with the rsiStudy. Please follow the Pane article for more details.

NOTE: Of course, you can change colors, indicator inputs, and everything else. Please follow the Modify Study Properties section for more details.

4. Also, let's enable a cursor:

chart.isCursorEnabled = true

NOTE: By default, the chart has already a few gesture modifiers, like Zoom, Pan, Y-Axis drag, etc. Please follow the Chart Modifiers section for more details.

5. Enter the license key.

NOTE: As mentioned above, Finance SDK is built on top of the SciChart library. To see a chart, you must have an active SciChart license. For more details, please, follow the SciChart Android Licensing page.

After you obtain your license key, use it in your project, like this:

SciChartSurface.setRuntimeLicenseKey("YOUR_LICENSE_KEY")

NOTE: Please, follow the Applying the Runtime License in Your App article for more details.

That's it. You've just created a finance chart with candles, indicators, legend, modifiers, resizing, and saved tons of development time.

Studies

Study is the object that is responsible for charting business logic. Here you decide what your chart should display and how it should be visualized - as a candlestick, line, column, mountain, etc.

Modify Study Properties

Each of our built-in studies has editable properties, depending on the Finance Series type and indicators included in that study. These editable properties are annotated with the @EditableProperty annotation to allow you to collect all of them in one place, for example, for a study settings view.

NOTE: To see it in action, please try our SciTrader Android app.

As an example, let's take our RSIStudy and try to modify its properties. It has two of them - RSIIndicator and LineFinanceSeries:

1. RSIIndicator has also two properties: period and input. By default, period == 14 and input == "close" which means that we want to calulate our RSI based on close prices from our candlesticks. Let's change our period to 50 and input to "open". It will produce the following result:

period == 14, input == "close"	period == 50, input == "open"

2. LineFinanceSeries has its own editable properties: opacity and strokeStyle with color, antiAliasing, thickness and strokeDashArray.

NOTE: You can find more about PenStyle, BrushStyle and FontStyle in the SciChart Android Documentation

NOTE: All of these properties have some default values to have a nice chart out-of-the-box. Feel free to edit them to match your design requirements.

After some changes, your RSIStudy might look, like this:

color == Constants.DefaultBlue thickness == 5.5f strokeDashArray == null	color == Constants.DefaultRed thickness == 5.5f strokeDashArray == floatArrayOf(3f.toDip(), 3f.toDip())

Built-in Studies

Finance SDK contains 14 built-in studies, available out of the box. There is on special PriceSeriesStudy that displays candlesticks and volume bars. Others represent technical indicators from the world's most famous TA-Lib (Technical Analysis) Library. Here are all of them with some images:

PriceSeriesStudy	ADXStudy

ATRStudy	BBandsStudy

CCIStudy	EMAStudy

HT_TrendlineStudy	MacdStudy

OBVStudy	RSIStudy

SARStudy	SMAStudy

STDDevStudy	StochStudy

Finance Series

There are a few built-in Finance Series types that are responsible for a visual representation of your data on the chart.

NOTE: Finance Series corresponds to the SciChart RenderableSeries. For more details, please read the RenderableSeries API article in the SciChart Android documentation

Each of them has its editable properties, like stroke, fill, opacity, etc. Also, it has its tooltip and Info provider, which is responsible for providing data for your tooltips, legend, etc.

NOTE: For more info, please refer to the Tooltips Customization documentation.

Each of our Studies uses one or few Finance Series to visualize prices or TA-lib indicators outputs. Here you can see their usage:

CandlestickFinanceSeries and ColumnFinanceSeries	BandFinanceSeries

LineFinanceSeries	HistogramFinanceSeries

NOTE: Please refer to Modify Study Properties section for more details.

Panes

Pane is an object that holds a chart, legend, and all other subviews that you might want to place on top of the chart. Also, it is responsible for chart resizing.

Pane Factory and Chart Modifiers

SciFinanceChart has an IPaneFactory object, responsible for creating panes. There is one concrete implementation, called DefaultPaneFactory which creates two types of panes - DefaultPane and MainPane. This factory is responsible for creating Chart modifiers - objects, that can be added to a chart to give it a certain behavior, like zooming, panning operations, tooltips, legends, selection of points or lines, etc. There are many different ChartModifiers provided by SciChart, so you might wanna take a look at the Chart Modifier APIs article in the SciChart Android Documentation for more details.

Here you can take a quick look at how they work:

ZoomPanModifier	PinchZoomModifier

SeriesValueModifier	DoubleTapGestureModifier

YAxisDragModifier	XRangeModifier

CrosshairModifier	StudyLegend

Panes Resizing

Our built-in panes know how to resize. Assuming, you have more than one pane, you can tap between panes and drag to resize:

Data Provider and Data Manager

DefaultCandleDataProvider and DataManager are objects that simplify data manipulation in your app.

DataManager is responsible for storing data and accessing it by the DataSourceId. First, you register your ID, then put some values under it. Later, you can access those values where needed.

DefaultCandleDataProvider is responsible for adding candlesticks. It has xValues, openValues, highValues, lowValues, closeValues and volumeValues along with corresponding id's that you can use to get access to those values later.

Let's take a look, at how the data flow works on the RSIStudy example.

1. At the beginning, create a DefaultCandleDataProvider instance and set it to SciFinanceChart.candleDataProvider property. DefaultCandleDataProvider registers all candlesticks IDs in the DataManager and stores corresponding values under the hood.

val chart = findViewById<SciFinanceChart>(R.id.financeChart)
val candleDataProvider = DefaultCandleDataProvider()
chart.candleDataProvider = candleDataProvider

2. Then, use dataProvider to fill the data manager with some candles:

// Assume you get some candles from a server
for (candlestick in candles) {
    dataProvider.xValues.addTime(candlestick.openTime)
    dataProvider.openValues.add(candlestick.open)
    dataProvider.highValues.add(candlestick.high)
    dataProvider.lowValues.add(candlestick.low)
    dataProvider.closeValues.add(candlestick.close)
    dataProvider.volumeValues.add(candlestick.volume)
}

3. When we create our Studies, we specify Values ID's, that we will need to get access to. Since RSIStudy need xValues and close values we pass as a constructor parameters corresponding IDs, that have been registered previously in our DefaultCandleDataProvider - DataSourceId("xValues") and DataSourceId("close"):

class RSIStudy(
    pane: PaneId,
    id: StudyId = StudyId.uniqueId("RSI"),
    xValuesId: DataSourceId = DataSourceId("xValues"),
    yValuesId: DataSourceId = DataSourceId("close"),
) : CandleStudyBase(pane, id) {
    ...
}

4. Next we send yValuesId to the RSIIndicator. It gets yValues from the DataManager and uses it to perform RSI calculations. When the job is done it saves the outputValues to the data manager under specific rsiOutputId. Here is how it looks in code in short form:

// create rsiIndicator with yValuesId and rsiOutputId
val rsiIndicator = TALibIndicatorProvider.RSIIndicator(defaultPeriod, yValuesId, rsiOutputId)

// register outputValues under yValuesId in DataManager
dataManager.registerYValuesSource(rsiOutputId, outputValues)

// calculate RSI and write computed values to the outputValues
core.rsi(startIndex, endIndex, inputValues, period.value, outStart, outLength, outputValues)

5. In order to send RSI values to the chart we create a LineFinanceSeries with our xValuesId and rsiOutputId alongside with other parameters. FinanceSeries gets corresponding values from the DataManager and adds it to the renderableSeries.dataSeries:

// create rsiSeries with xValuesId and rsiIndicator.outputId
val rsiSeries = LineFinanceSeries(R.string.rsiIndicatorName, xValuesId, rsiIndicator.outputId, yAxisId)

// get values from the DataManager
val xValues = dataManager.getXValues(xValues.value)
val yValues = dataManager.getYValues(yValues.value)

// Add values to the dataSeries
dataSeries.append(xValues, yValues)

That's it. The rest is handled by the SciChart library and finally, our nice blue RSI line appears on the screen:

NOTE: Most likely, you'd want to display some real-time data, coming from the WebSocket. To see it in action, please try our SciTrader Android and iOS app.

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this software except in compliance with the License. You may obtain a copy of the License at LICENSE file or

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

This license requires specifying SciChart as the product creator. You shall add the "attribution notice" from the NOTICE file and a link to https://www.scichart.com/ to the page of your website or mobile application that is available to your users. As thanks for creating this product, we'd be grateful if you add it in a prominent place.