View source for Bookmap API

[[File:Bookmap_API.png|right|500px]]

Bookmap API allows to connect to Bookmap new data sources and trading systems, and to develop custom modules such as automated trading strategy, indicators, voice alerts, data export and recording, and more. The API was developed by Bookmap team which has experience with dozens of API's of trading platforms, data vendors, and exchanges. The resulting API combines unprecedented levels of both simplicity and transparency. This gives users an ability to develop within minutes or hours custom modules which receive truly unfiltered and unaggregated market data (including full market depth) and may use complete trading functionality.

==What is Bookmap==
{{See also|Main Page}}

Bookmap is a high-performance trading platform focused on intuitive visualization of traded volume, and full market depth data and its evolution from large scale (e.g. days) up to nanoseconds. Bookmap also visualizes complete evolution of user's own orders. More details including chart orientation can be found on the [[Main Page]]. Here are just two examples of large trader activity that can be observed with Bookmap. In the first example it's apparent that this trader attempts to sell large amounts but has to chase the price. The trader places the large orders gradually probably in order not to be easily detected by HFT's. The second example shows activity of a large trader on Crude Oil (CL) futures.

[[File:Large_trader.png|right]]


[[File:CL.png|right|927px]]

==Examples==
TBA

==API Documentation==
Bookmap is a Java program in its core with GPU accelerated rendering based on C++ OpenGL. Custom modules must be developed in Java and shipped as JAR files, but on their other end they may connect to an API with any programming language, hence the name adapters.
The complete API documentation is part of Bookmap installer. Its name is '''bm-l1api-javadoc.jar''' located in '''C:\Program Files\Bookmap\lib''' (given default installation paths). Note: it's not recommended to extract it in the installation folder. The API supports versioning, allowing back-compatibility. More details and source code examples can be found on Bookmap's GitHub page [https://github.com/BookmapAPI/]. Setup examples are demonstrated using Eclipse IDE, but there is no requirements for a specific development framework. 

===Bookmap forum===
Bookmap recently launched a [https://www.bookmap.com/forum/ forum], to get support on API, to communicate with developers of custom modules and/or to see what is being developed by others.

===Timestamps===
Main article: [[Market_Mechanics#Timestamps_in_Bookmap]]

The page above contains detailed information about timestamps in Bookmap, latency in general, and other related topics.

===Internal data format===
Bookmap accepts market data in either Market-by-Price (MBP) or Market-by-Order (MBO) format. Here is an illustration of both: [[Market_Mechanics#Order_Book]].

====Advanced order flow features====
By default, Bookmap performs advanced data processing such as detecting iceberg orders and reconstruction of trade size (summing up multiple trades caused by the same order) assuming raw exchange data with unchanged sequence of events as shown here by the ''native'' detection method: [[Iceberg Orders Tracker]]. However, Bookmap allows L0 adapters to override its default methods of advanced processing because the quality of such processing highly depends on the quality of market data. Some data vendors provide market depth data asynchronously from BBO data and/or trades data. This happens when the vendor throttles the data in order to reduce the network traffic on its own side or to adjust it to low internet speed on client's side. Or because the data vendor split the original data into channels and disseminates it via different servers. Also, exchanges may provide market data with different sequence of events. Such cases require fine-tuning the processing algorithm per specific data source.

==Layer 0 API==
The purpose of L0 API is connectivity to exchanges, data vendors, and trading systems which are not yet supported. Connecting via L0 opens full Bookmap functionality that is supported for built-in adapters. Typically, the development of a new adapter has two stages: data connectivity, and trading connectivity. The implementation of trading functionality is not mandatory and it can be implemented even partially, for instance, visualization of the evolution of trader's orders, but without the ability to send or modify them from Bookmap chart. There are two distinct solutions that are based on L0 API: Quant solution (paid), and Connect solution (free).

===Bookmap Quant solution===
[[File:Bookmap_Quant_use_cases.png|right|500px]]
Bookmap Quant solution is based on L0 API and may serve the needs of proprietary HFT firms, banks, trading rooms, etc. who have their own data and trading systems. Also, brokers, data vendors, and order management systems (OMS) may use Quant solution for monitoring and debriefing their systems in either real-time or replay. Bookmap uses nanoseconds timestamps.

====Use cases====
The diagram covers 3 most typical use cases of Bookmap Quant.
* Visualization of back-testing simulations
* Debrief of live trading sessions
* Monitor trading in real time

====Security====
To support a fully secure solution Bookmap Quant clients can use [[Bookmap_user_guide#Bookmap_Offline_Activation|Bookmap Offline Activation]]. Bookmap is capable to operate without internet access. Users can configure firewall to allow external access to their custom adapter only.

====Performance====
Bookmap is a high-performance software, focusing on high quality visualization using GPU. In order to allow seamless chart manipulation at any zoom level (vertical or horizontal), Bookmap stores the data in a proprietary data structure inside C:\Bookmap\Cache\ folder. The data structure is optimized for both HDD and SSD types of disk, but for faster processing it’s recommended to use SSD. Note that the size of the Cache folder can grow up to about 300 bytes per market data event (300 MB per a million data updates).

====Bookmap Recorder====
One of the most frequent use cases of Bookmap Quant is debriefing of simulations / backtesting results. Unlike debriefing a trading session, there may be thousands of simulations per day. Since simulations typically can run much faster than Bookmap’s throughput (30-50k data events per second) and in order to avoid Bookmap being a bottleneck in the process, users can use a utility called Bookmap Recorder, '''''BookmapRecorder.jar'''''. Bookmap Recorder is used to convert custom data into Bookmap readable format files, which can be opened by Bookmap in Replay mode. The throughput of Bookmap Recorder is roughly 150-200k of data events per second, producing files of size ~12 bytes per data event. User can integrate the recorder into their simulation software and then use Bookmap to replay only the relevant files. 
For the purpose of replaying data, BookmapRecorder does not have any disadvantages compared to the usage of L0 API directly.

====Features====
[[File:Quant_custom_icons.png|thumb|300px]]
Bookmap Quant package includes all built-in features and all paid add-ons. In addition, it allows to add and visualize custom indicators and custom order queue calculation (order queue is displayed as markers on the order book column). The display of custom indicators is fully configurable including usage of custom icons provided through the API as shown in this image:

====Price====
Bookmap Quant license is $499 per seat per month, paid annually. For the evaluation of Quant solution, Bookmap offers one month trial period of up to 5 seats for $500. For more information, custom development or special offers please contact Bookmap team at info@bookmap.com.

===Bookmap Connect solution===
Bookmap Connect solution is free. It enables users to connect Bookmap to unsupported yet target connections (e.g. trading platforms, data vendors, exchanges, trading systems, etc). 

====How to install a Bookmap Connect adapter====
Starting from [[Bookmap_versions#Bookmap_7.0_build_43|Bookmap 7.0 build 43]], users can import and install already developed adapters (including adapters in 'alpha' stage) via Settings->Manage plugins menu and then use them as any other connection, i.e. by adding them via Connections->Configure menu. Currently available adapters are for BitMEX, Bitfinex, and OKCoin exchanges.

==== Motivation ====
Prior to Bookmap Connect solution, Bookmap team was responsible to decide which adapters to develop. The evaluation of worthiness of candidate adapters and thus priority of their development isn't simple to determine, and individual users may have different priorities. Bookmap Connect solution solves these problems as following:
* It allows traders and developers to develop adapters according to their priorities, without Bookmap being a bottleneck in the process
* It helps Bookmap to grow by attracting traders who are interested in not supported yet connections to data and trading.

==== Requirements ====
Unlike Quant solution, Bookmap Connect solution is free. However it must meet the following criteria:
* The target connection must be available for anyone, not just the developer of the adapter.
* The adapter must be developed as an open source public project such as at GitHub.

==== How does it work ====
Bookmap Connect solution requires self-enabling the access to L0 API. Once the new adapter is ready, Bookmap team will certify it and then it can be used by other Bookmap users without the need to access L0 API. Users can import the adapter into Bookmap and select it as the desired connection.
There is a number of simple steps recommended prior to the development of an adapter. 
* Make sure the adapter you wish to develop meets Bookmap Connect requirements above.
* Evaluate the market data quality of the desired connection. To get maximum of Bookmap powers, it's highly desirable to feed it with '''MBO or MBP full market depth data''' (details: [[Market_Mechanics#Market_Data]]).
* Make sure the adapter will allow Bookmap to operate as '''standalone''' such as via WebSocket connection that doesn't require another trading platform to be running in parallel. While it's possible to develop an adapter to another trading platform that has an API, it would damage stability by adding dependencies, and may not be able to handle large amounts of data during high market activity. See [[Bookmap_Performance_FAQ | Performance FAQ]] for more details.
* Visit [https://www.bookmap.com/forum/viewtopic.php?f=3&t=2 Bookmap forum] and see if anyone else is already developing an adapter to the target connection you wish to have. They will appear under Bookmap Connect Incubator forum. You may want to contribute to current development (by requesting an access from the project owner) or by testing it or simply to wait for its readiness. Alternatively, you can start a new project, even for the same target connection.
* If you decided to start a new project, create a topic under the same forum, describe your project and target connection, provide some milestones (e.g. first data connectivity, then trading capability). This will be helpful for other traders who may also offer their help in development or in testing.
* Visit your profile on Bookmap website and self-enable an access to L0 API <span style="color:red"> (Meanwhile please send an email to support for manual enablment) </span>.

==== FAQ ====

{{quote|'''Does free Connect solution allows using Bookmap for free?'''}}

Bookmap Connect allows free access to L0 API but the access to Bookmap functionalities and add-ons are based on user's license. The free Bookmap Digital package allows use of all crypto adapters.

{{quote|'''I'm not a Java developer but I need an adapter to XXX. What can I do?'''}}

You can hire a freelance developer. In addition to Java programming skills, it's essential for the developer to understand the requirements and business logic. Hint: offer your candidates to read about [[Market Mechanics]] and then conduct a quiz on this topic. Then ask the candidate to review the API documentation, IDE setup, and existing open source adapters. Make sure the candidate feels confident about the task.

{{quote|'''Can I hire Bookmap team for development of an adapter?'''}}

It depends on our priorities at that period. Please send us an email to support@bookmap.com referencing this page, and describe your target connection (preferably with links to its API). If possible, Bookmap team will evaluate development cost and reply with an offer.

{{quote|'''Can I own the adapter I created or license it or sell it?'''}}

A marketplace will be considered later. As for May 2018 it's possible only under Bookmap Quant solution.

{{quote|'''What if I have an existing position and/or unfilled orders in the account I connect to?'''}}

It's the responsibility of the adapter to transfer information about the working orders and the positions upon Bookmap connection and then in real-time. Bookmap will display whatever it received from the adapter. A more detailed description is on the forum [https://www.bookmap.com/forum/viewtopic.php?f=6&t=3].

===Comparison between Quant and Connect solutions===
{| class="wikitable"
|+
|-
! scope="col" |
! scope="col"| Bookmap Connect solution || Bookmap Quant solution
|-
! style="text-align:left;" | Price
| Free (''excluding Bookmap'')
| $499 / month / seat (''including Bookmap'')
|-
! style="text-align:left;" | Real-time market data and trading
| Yes || Yes
|-
! style="text-align:left;" | Replay data & orders recorded by Bookmap
| Yes || Yes
|-
! style="text-align:left;" | Create Bookmap readable files from your own data & orders
| No || Yes
|-
! style="text-align:left;" | External custom indicators and signals
| No (but can be developed via L1/L2 API)|| Yes
|-
! style="text-align:left;" | Custom orders queue computation
| No || Yes
|-
! style="text-align:left;" | Target connection
| Disclosed and must be accessible to others || Confidential information of the client
|-
! style="text-align:left;" | Adapter source code
| Open source || Proprietary to the client
|-
! style="text-align:left;" | Adapter ownership
| Public || Client
|}

==Layer 1 API==
[[File:Bookmap_API_L1_%26_L2.png|thumb|500px]]
As shown on the diagram, it's up to the custom L1 API module whether to communicate with L2 API or not. L1 API allows to:
* Fast access to real-time and recent historical data (stored in Bookmap’s data-structure) in a uniform format regardless of specific connection
* Implement automated trading strategies
* Record and/or export market data and orders in any desired format, and more…

There are 3 built-in demo strategies Chase, Escape, and Execute which use L1 API. Users can activate them via strategies button: [[File:L1_demo_strategies.png]]. Their main purpose is demonstration of L1 API custom modules and offering their source code as a reference for development of other custom modules [https://github.com/BookmapAPI/DemoStrategies]. It's therefore recommended not to activate these demo strategies with a real trading account. 

L1 API will be opened for traders and developers during July-August 2018. Note: L1 API gives the access to so-called Non-Display data, i.e. ability to access it not only in the visual form. Some exchanges and/or data vendors may charge higher price for non-display data and/or require to register as a professional trader as shown on the 'API access' column [[Main_Page#All_data_and_trading_connections|here]].

L1 API modules can be either attached or injected. Both methods receive complete market data and updates on status of user's orders when they arrive from the outside (i.e. via L0 API) even if the orders were initiated from outside Bookmap.

===Inject method===
Within the inject method both market data and user's orders pass through the custom module. This gives the custom module full control over the data flow including the ability to modify it. But it also puts on it the responsibility to forward the data further both ways. Here are use case examples:
* Risk module that can override user actions on the chart
* Display on the chart thousands of units instead of units by dividing the size by 1000.

===Attach method===
Within the attach method the custom module cannot modify the data received by the chart and cannot modify user's trading actions on the chart. Instead, it ''listens'' to the market data updates and to user's actions on the chart. While it cannot block or modify trader's actions on the chart before they leave Bookmap, it will still receive status updates of user actions once they come back from the exchange or from OMS (e.g. from Rithmic) and can therefore generate its own automatic actions in response to market data or user's actions. Here are use case examples:
* Record market data in a custom format or export it in real-time, e.g. into Excel
* Automatic data driven trading strategy 
* Custom alerts for specific market data or trading conditions

==Layer 2 API==
L2 API allows custom visualization including full control of Bookmap chart rendering. It will be opened together with L1 API. At first it will support drawing of simple indicators, and gradually will be extended to offer greater control over chart rendering.

== Useful links ==
* [[Market Mechanics]]
* [[Main Page]]
* [[Iceberg Orders Tracker]]
* [https://bookmap.com/forum/ Bookmap forum]

[[Category:API]]
[[Category:Quant]]
[[Category:Connect]]