This work is licensed under a Creative Commons Attribution-NonCommercial-NoDerivs 3.0 Unported License.
When using the PProAPI, keep the following in mind:
Disclaimer: limited support
The assumption is that users of the API have a basic knowledge of programming and how to integrate URL calls with other tools, and as a result the support provided is limited, for the most part, to the documentation found below.
It is entirely up to the user how they want to interact with the API. It is possible to use the URL calls and process the CSV data using any programming language.
The PPro8 API is a web service which, when enabled, allows the user to pass commands using URL format:
<RequestType>? <parameter=value & parameter=value & parameter=value ... >
To enable access to PProAPI, go to Metro: General Processes: Trader Management: Trading Parameters: API Access. For more information, see the Trader Management Process Manual
Note: when UDP is set up, the commands do not receive responses in XML nor in .log files. Instead, the API server responds with HTTP headers. If a command fails, the server returns 400 bad requests. Without UDP set up, using regular URL instead, expected behaviour is 200 good requests.
To launch the PProAPI, a user launches the PPro8 client with the following command:
Note: any port may be used; 8080 is just used in all examples. If you choose to use a different port, we recommend you limit yourself to the range from 1000–65535, as ports below 1000 are often predefined by the operating system.
When logged in, the user can go to the PProAPI portal using this link: http://localhost:8080 . This portal will have a basic summary of the currently available commands.
To ensure proper UDP functionality, code your application to actively listen to the port.
If you want to verify UDP functionality, we recommend using NetCat and its accompanying cheat sheet for this purpose.
To use NetCat, launch it with the following command line, for example:
-u is UDP
-l means “listening to”
-p is port, the number of which varies depending on the registration being sent
…taken together, this command line means “UDP port 4135 is actively listening.”
You can then use the command line to register and send data to a port you set.
Register L1 data for ATML.NQ and send data to UDP port 4135.
Use the Register command to register for each of the available data types.
In each registration, writing an individual file is specified by the bykey syntax part in the following manner:
On the other hand, bytype sends all registered symbol data to a specified file.
If the specified file contains TOS, L1, L2, and OSTAT, you can choose which symbol goes to the specified file (bytype), or write to a separate file (bykey) for a symbol.
Register?symbol=<symbol.extension> & region=[1|2|3|4] & feedtype=[L1|TOS|L2|IMBALANCE|OSTAT|ORDEREVENT|PAPIORDER]
<RegistryQueueSize PProApi="<size>" NCSA="<size>" EMEA="<size>" APAC="<size>" />
New: the Register command is now supported for Manager accounts, for the OSTAT and ORDEREVENT feed types only. For OSTAT / ORDEREVENT, messages pass the region parameter.
The Register command is divided into three separate commands: GetSnapshot, Register, and SetOutput.
Using these commands, you can set the output and enable or disable it being written by setting the status on/off and writing only snapshot, live data, or both, depending on the command.
Use this command to get existing data (the last 100 records, but no new data) for the symbol.
Note: for the Level 1 (L1) feedtype, this command returns only two records.
GetSnapshot?symbol=<symbol.extension> & region=[1|2|3|4] & feedtype=[L1|TOS|L2]
Use this command to register live data and get new information for the symbol.
Use this command to set the output information for the symbol and define where the data should be written, either bykey or bytype.
New: the SetOutput command is now supported for Manager accounts, for the OSTAT and ORDEREVENT feed types only. For OSTAT / ORDEREVENT, messages pass the region parameter.
SetOutput?symbol=<symbol.extension> & region=[1|2|3|4] & feedtype=[L1|TOS|L2|IMBALANCE|OSTAT|ORDEREVENT|PAPIORDER] & output=[bykey|bytype|<port>] & status=[on|off]
Syntax for UDP registrations:
This command registers the API to receive all Level 1 price/size updates for symbol ZVZZT.NQ. These updates are written to a file in the PPro8 launch directory with the name L1_1_ZVZZT.NQ.log, where the number represents the region. The regions are as follows:
Note: please ensure that you register for the correct region with all relevant commands.
Messages for L1 must include the symbol parameter.
Each L1 update is a comma-separated line of data with the following fields:
This command registers the API to receive all Time of Sales prints for symbol ZVZZT.NQ. These updates are then written to a file in the PPro8 launch directory with the name TOS_1_ZVZZT.NQ.log.
Messages for TOS must include the symbol parameter.
TOS messages are stored in a separate file for each registered symbol.
Each TOS update is a comma-separated line of data with the following fields:
Information for the Type parameter:
Type 0 = live feed
Type 1 = start of snapshot
Type 2 = snapshot record
Type 3 = end of snapshot
Live feed data starts once the user registers for the feed.
Note: snapshot data is not duplicate data. Rather, it is historical data showing the last 100 TOS prints before the user registered for the feed. Snapshot records can be processed if the user wants to get an idea of symbol sales from directly prior to the TOS registry. The snapshots are used to populate the TOS window when a symbol is registered to it, and since the API makes the same calls as the software, the TOS is included here as well.
For more information, see the complete list of PPro8 TOS Values (Market Center, Submarket ID, and Sales Conditions).
Register?symbol=ZVZZT.NQ&feedtype=L2 & output=[bykey|bytype]
This command registers the API to receive all Level 2/Market Depth updates for symbol ZVZZT. These updates are then written to a file in the PPro8 launch directory with the name L2_1_ZVZZT.NQ.log.
Messages for L2 must include the symbol parameter.
L2 messages are stored in a separate file for each registered symbol.
Each L2 update is a comma-separated line of data with the following fields:
Each update either a) creates a new level, or b) replaces the existing values for that MMID, Price, and Side combination.
For example, if you already have an ANON Bid @ 8.60 for 400 shares, then the above example data would replace that so the new values would be ANON Bid @ 8.60 for 100 shares.
When the API registers for the L2 feed on a symbol, it first receives a snapshot. This snapshot represents the current quote state of the symbol, and should then be updated with the real-time messages coming in.
The snapshot begins with a line where Side=s, for example:
All messages making up the snapshot have SequenceNumber=0.
The snapshot ends with a line where Side=e, for example:
This command registers the API to receive all Imbalance data. This data is then written to a file in the PPro8 launch directory with the name: IMBLO_1_ALL.log.
Messages for IMBALANCE must pass the region parameter.
Note: NASDAQ and NYSE information is dynamic, while TSX/TSX-V information is static. AMEX information is not available at this time.
Each IMBALANCE update is a comma-separated line of data with the following fields:
Each imbalance update represents the current size of the imbalance. Previous messages for the same symbol can be discarded.
This command registers the API to receive all Order Status (OSTAT) messages for the user in region 1 (NCSA), region 2 (EMEA), region 3 (APAC), or region 4 (AUNZ). This data is then written to a file in the PPro8 launch directory with the name OSTAT_1.log. The numerical value in the log file name represents the region.
Messages for OSTAT must pass the region parameter.
One file is created for each region. In order to see all order updates—including internal rejects—a user will need to monitor both the OSTAT and ORDEREVENT logs.
Note: for Futures contracts, the API sends the contract size for the Price tag, not the contract price. Use GetLv1 to find tick size and tick value, and to calculate: Contract Price = (Contract Size * Tick Size) / Tick Value
Each OSTAT update is a comma-separated line of data with the following fields:
Order Flags are a sum of the below numbers:
SentViaScriptSrv=256 flag is sent whenever an order triggers Cancel Opposing or Cancel Less Aggressive logic.
You can use the OSTAT log, in combination with the ORDEREVENT log, to monitor the state of orders and track executions and associated fees. This data is also used by the PPro8 client software to update the Summary and History Log windows.
Register?region=1&feedtype=ORDEREVENT & output=[bykey|bytype]
This command registers the API to receive all Order Event (ORDEREVENT) messages for the user in region 1 (NCSA). This data is then written to a file in the PPro8 launch directory with the name ORDEREVENT_1.log.
Messages for ORDEREVENT must pass the region parameter.
One file is created for each region. This log can be combined with the OSTAT log to monitor for all order updates.
The primary use of the ORDEREVENT log is to recognize an order as rejected internally where it does not appear in the OSTAT log.
Each ORDEREVENT update is a comma-separated line of data with the following fields:
Order_Event (ORDEREVENT) Flavour Descriptions as follows:
Note: when price and sizes are pending OPC, an invalid value appears. This issue is usually corrected when we release a new OSM. If you believe this can affect trading, you may be able to filter them out as Size = -1. The description will also show the message 'New order, OPC Pending'.
This command registers the API to receive information for orders sent through the API about the order number associated with each order request ID. The data is then written to a file in the PPro8 launch directory with the name PAPIORDER_1.log.
Messages for PAPIORDER must pass the region parameter.
You can use this log file to limit the number of 'GetOrderNumber' requests you need to submit. You can set your program/script to monitor this log file for that information.
Each PAPIORDER update is a comma-separated line of data with the following fields:
This command is used to deregister for available data types. This stops the API from writing to log files or making L1 calls available.
Deregister?symbol=symbol.extension & region=[1|2|3|4] & feedtype=[L1|TOS|L2|IMBALANCE]
'Lv1' and 'Tos' are deprecated, but still available. Update your scripts to use 'L1' and 'TOS'.
This command gets information from Summary by layer. It returns the same total number of columns as the PPro8 GUI for all layers.
Get?type=tool & tool=[Summary_n] & key=<regionAsset>[^<layerKey>]*
Use this command to request a Refresh from Summary.
GetBlotterSnapshot?trader=[USERID] & region=[1|2|3|4] & assetid=<assetId>
This command recalls the environment the user is logged into (TMS or Live), and the user ID and directory where PPro8 is installed.
<Environment="Live" User="ABE001" DataDir="C:\Program Files\Ralota\ZenoriaStreet"/>
This command recalls Level 1 snapshot data. You must register for L1 data before trying to read it.
This will bring up the following response:
<Level1Data Message="L1DB" MarketTime="15:22:47.100" Symbol="TD.TO" BidPrice="55.4600" AskPrice="55.4700" BidSize="11000" AskSize="700" Volume="798304" MinPrice="55.1100" MaxPrice="55.5000" LowPrice="55.1100" HighPrice="55.5000" FirstPrice="55.4000" OpenPrice="55.4000" ClosePrice="55.3400" MaxPermittedPrice="0" MinPermittedPrice="0" LotSize="100" LastPrice="55.4600" InstrumentState="Open" AssetClass="Equity" TickValue="0" TickSize="0.00500000" Currency="CAD" Tick="D"/>
This GetLv1 response is a comma-separated line of data that includes the following fields:
This command returns information about a trader, including algorithm, LFT amount, NL amount, etc.
GetTraderInfo?trader=<trader> & region=<region> & assetid=<assetId>
traderId="DV113X91" regionId="1" assetclassId="1" traderState="1" algorithm="0" lftAmount="2000" netLossAmount="1500" timerIsActive="N" currentTimeRemaining="0"
This response includes the following fields:
This command recalls all executions for a user ID.
<Trader name="GODOT"> <Region id="1" name="NCSA"> <Transaction Message="OrderStatus" MarketDateTime="20141121-09:25:10.252" Currency="USD" Symbol="BRK/A.NY" Gateway="1" Side="B" %%OrderNumber="GODOT___00000001M172461100000" Price="0.01" Shares="1" Position="2" OrderState="Partially Filled" MarketID="18" CurrencyChargeGway="USD" ChargeGway="0.004" CurrencyChargeAct="UNK" ChargeAct="0" CurrencyChargeSec="UNK" ChargeSec="0" CurrencyChargeExec="UNK" ChargeExec="0" CurrencyChargeClr="UNK" ChargeClr="0" OrderFlags="8" CurrencyCharge="0" Account="1ORBX00001OR1GODOT___USD1"%% InfoCode="0" InfoText="Great stock. Great Price"/> </Region> </Trader>
Note: for Futures symbols, this command now returns Display Price instead of Contract Size.
You can use the API to interact with orders in several ways. For more detailed examples, see the PProAPI Portal (http://localhost:8080 ).
The ExecuteOrder command includes a number of values that can be entered depending on the chosen order type:
ExecuteOrder?symbol=<symbol.ext> & limitprice=<float> & ordername=<copied from KeyboardSetup> & shares=<int> & cancel=orderNumber & priceadjust=<float> & stopprice=<float> & pegdifference=<float> & displaysize=<int> & displayrange=<int> & minexecsize=<int>
ExecuteOrder?symbol=BB.TO&limitprice=6.90&ordername=TSX Buy SweepSOR Limit ANON DAY Reserve&shares=1000&displaysize=100
This example would send a Reserve order on the TSX with a limit price of 6.90, a size of 1000, and a display size of 100 shares.
Use this command to send a basket order by name.
Use this command to send orders from an order list (set using the Order List window in PPro8).
This command reproduces the cancel functionality.
This example command sends a cancel request for all open orders on the bid side of ZVZZT.NQ.
New: options added to CancelOrder command:
This command replaces the size of a selected order. With this function, the size can only be reduced, not increased.
OrderCancelReplace?ordernumber=<orderNumber> & shares=desired reduced number of shares
This command retrieves the order number associated with the request ID generated by the ExecuteOrder command.
Note: with the introduction of the PAPIORDER feed type, you can also monitor the file generated by region using that command to get this data in real time rather than polling the web server.
This command retrieves the order number for the order submitted on Request ID 3.
This command retrieves the current state for a specific order.
Note: with the introduction of the OSTAT and ORDEREVENT feed types, you can also monitor the files generated by region using those commands to get this data in real time rather than polling the web server.
This example command retrieves the current order state for order number GODOT03000008M1711F7000000.
The numerical value of the order state appears. This numerical value represents one of the following:
<Orders><Order id= state= /><Order id= state= />(....)</Orders>
This command retrieves the states of orders by user ID. States include the following:
This command also returns the following parameters:
Note: for Futures symbols, this command now returns Display Price instead of Contract Size.
This command sends a trailing stop order according to set parameters.
SendTrailingStop?symbol=<symbol.ext> & limitprice=<float> & ordername=<copied from KeyboardSetup> & shares=<int> & referenceprice=<bid|ask|lastPrice|midPoint> & offsettype=<numeric|percentage|tickSize> & trailoffset=<number> & incrementtype=<none|numeric|percentage|tickSize> & trailincrement=<number> & priceadjust=<float> & stopprice=<float> & pegdifference=<float> & displaysize=<int> & displayrange=<int> & minexecsize=<int>
SendTrailingStop?symbol=_STW60.E1&limitprice=10.10&ordername=AUTE Buy AUTE Limit ANON DAY&shares=100&referenceprice=bid&offsettype=percentage&trailoffset=0.8&incrementtype=numeric&trailincrement=1
This command sends a stop order script according to set parameters.
SendSwiftStop?symbol=<symbol.ext> & limitprice=<float> & ordername=<copied from KeyboardSetup> & shares=<int> & swiftstopprice=<float>
SendSwiftStop?symbol=_STW60.E1&limitprice=10.10&ordername=AUTE Buy AUTE Limit ANON DAY&shares=100&swiftstopprice=10.08
This command retrieves a list of the current open positions for a user ID.
<Positions> <Symbol <data> />(....)</Positions>
This command will cancel all open orders for a symbol. It will also cancel all scripts on the symbol, provided that the trader has a position or an open order on the symbol.
This command can also be used for multiple symbols:
This command retrieves Summary data by layers. For example, Get Summary by Trader.
Get?type=tool&tool=<summary instance>&key=<layer & row combination>
This command exports the information to a CSV file named <logged-on user>_<tool id>.log. This example retrieves information on GODOT's position in F.NY from Summary_1, which can be set up by Trader:Symbol in layer settings.