====== PPro8 PProAPI ======

=====Important information=====

When using the PProAPI, keep the following in mind:

  * The API user is responsible for all profits/losses associated with order activity generated by the API
  * API-generated order activity is subjected to all the same checks and surveillance as manual order activity
  * It is the API user’s responsibility to monitor his or her trade activity in real time
  * If an API user generates problematic order activity using the API, access may be restricted until such time as the user can demonstrate that corrective action has been taken

**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.

=====Overview======

The PPro8 API is a web service which, when enabled, allows the user to pass commands using URL format: <code><RequestType>? <parameter=value & parameter=value & parameter=value ... ></code>

To enable access to PProAPI, go to **Metro: General Processes: Trader Management: Trading Parameters: API Access**. For more information, see the **__[[http://10.68.200.107/metro/node/15542519|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:

<code>PPro8.exe -pproapi_port=8080</code>

**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.

**Note:** throughout this instruction manual, example URLs are presented omitting //http://localhost:8080 //. For all examples below, first type //http://localhost:8080/ // followed by the command.

{{ :pproapiv2.0.png?nolink |}}

=====UDP functionality=====

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 __[[http://www.sans.org/security-resources/sec560/netcat_cheat_sheet_v1.pdf|cheat sheet]]__ for this purpose.

To use NetCat, launch it with the following command line, for example:

<code>-ul -p4135</code>

...where:

  * -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.

For example:

Register L1 data for ATML.NQ and send data to UDP port 4135.

<code>http://localhost:8080/SetOutput?symbol=ATML.NQ&region=1&feedtype=L1&output=4135&status=on</code>

Example response:

<code>LocalTime=08:53:20.845,Message=L1,MarketTime=08:53:20.551,Symbol=ATML.NQ,BidPrice=8.05000,BidSize=4700,AskPrice=8.07000,AskSize=2500,Tick=D</code>

**Notes:**

  * For OSTAT / ORDEREVENT / PAPIORDER, messages pass the region parameter
  * For IMBALANCE / SCRIPTS, messages pass the market parameter
  * For L1, L2, or TOS data, messages must pass the symbol parameter
  * Lv1 and Tos are deprecated but still available, please update your scripts to use L1 and TOS, respectively


=====Register commands=====

Use the Register command to register for each of the available data types.

Syntax:

<code>Register?symbol=<symbol.extension> & region=[1|2|3|4] & feedtype=[L1|TOS|L2|IMBALANCE|OSTAT|ORDEREVENT|PAPIORDER|NEWS]</code>

Return:

<code><RegistryQueueSize PProApi="<size>" NCSA="<size>" EMEA="<size>" APAC="<size>" /></code>

Example:

<code>Register?symbol=ZVZZT.NQ&feedtype=TOS</code>

**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.

====GetSnapshot====

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.

Syntax:
<code>GetSnapshot?symbol=<symbol.extension> & region=[1|2|3|4] & feedtype=[L1|TOS|L2]</code>

Example: 

<code>GetSnapshot?symbol=ZVZZT.NQ&feedtype=TOS</code>

===Notes===

  * For L1, L2, or TOS data, must pass the symbol parameter
  * 'Lv1' and 'Tos' are deprecated but still available, please update your scripts to use 'L1' and 'TOS'

====Register====

Use this command to register live data and get new information for the symbol.

Syntax: 

<code>Register?symbol=<symbol.extension> & region=[1|2|3|4] & feedtype=[OSTAT|ORDEREVENT|NEWS]</code>

Example:

<code>http://localhost:8080/Register?region=1&feedtype=OSTAT</code>

Return:

<code><RegistryQueueSize PProApi="<size>" NCSA="<size>" EMEA="<size>" APAC="<size>" /></code>

==Notes==

For OSTAT / ORDEREVENT messages, pass the region parameter.

===News (NEWS)===

Use this command to register the API to receive all News entries:

Example:

<code>Register?feedtype=NEWS</code>

Use this command to send the continuous News feed to a file named NEWSTEXTUPDATEANALYTICS_1.log, which is then saved to the PPro8 launch directory:

Example:

<code>SetOutput?feedtype=NEWS&output=bykey&status=on</code>

===Scripts (SCRIPTS)===

This command registers the API to register scripts. This will require you to set an output, and after doing so will create a file where all the scripts will be written.

Example:

<code>Register?feedtype=SCRIPTS</code>

====SetOutput====

Use this command to set the output information for the symbol and define where the data should be written, either **bykey** or **bytype**.

Please note that the data will be written to a log file, which will be generated in PPro8 folder.

**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.

Syntax: 

<code>SetOutput?symbol=<symbol.extension> & region=[1|2|3|4] & feedtype=[L1|TOS|L2|IMBALANCE|OSTAT|ORDEREVENT|PAPIORDER|NEWS|SCRIPTS] & output=[bykey|bytype|<port>] & status=[on|off]</code>

Example:

<code>SetOutput?symbol=ZVZZT.NQ&feedtype=NEWS&output=4134&status=on</code>

===Notes===

  * For OSTAT / ORDEREVENT / PAPIORDER / SCRIPTS, messages pass the region parameter.
  * For IMBALANCE, messages pass the market parameter.
  * For L1, L2, or TOS data, must pass the symbol parameter.
  * 'Lv1' and 'Tos' are deprecated but still available. Update your scripts to use 'L1' and 'TOS'.
  * output=1234 means output is broadcast to localhost UDP port 1234
  * L1 will also generate output files for: 
    * InstrumentUpdate (IU_*) - Message that has the State of a Symbol (Halted, Normal, etc.); sent by the market when state changes
    * SummaryUpdate (SU_*) - Message that has the Open and Close Price of a symbol; sent by the market
    * AlertMessages (AM_*) - Alert Messages registered by the client; sent by the Alert Server whenever an alert condition triggers
    * AuctionInfo (AI_*) - Message that has TAP, TAV, and TAT values; sent by the market

===GetOstats===

Syntax:

<code>SetOutput?region=1&feedtype=OSTAT&output=bytype&status=on</code>

Syntax for UDP registrations:

<code><SetOutput?region=1&feedtype=OSTAT&output=4321&status=on</code>

====Level 1 (L1)====

Example: <code>Register?symbol=ZVZZT.NQ&feedtype=L1</code>

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:

  * 1 – NCSA
  * 2 – EMEA
  * 3 – APAC
  * 4 – AUNZ

**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:

  * LocalTime=09:07:29.349 <- the time the update arrived on the user's machine and uses the user's computer's time
  * MarketTime=09:07:30.379 <- the market time of the update
  * Symbol=XIU.TO <- the symbol the update applies to, in the format <symbol>.<market extension>
  * BidPrice=19.19 <- the bid price of the L1 update
  * BidSize=8000 <- the bid size of the L1 update
  * AskPrice=19.24 <- the ask price of the L1 update
  * AskSize=16000 <- the ask size of the L1 update
  * Tick=? <- whether the latest update is related to an uptick/downtick on markets, where applicable

====Time of Sales (TOS)====

Example: <code>Register?symbol=ZVZZT.NQ&feedtype=TOS</code>

This command registers the API to receive all Time of Sales prints for symbol ZVZZT.NQ.

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:

  * LocalTime=09:30:15.375 <- the time the update arrived on the user's machine and uses the user's computer's time
  * MarketTime=09:30:14.887 <- the market time of the update
  * Type=1 <- the type of snapshot data coming in
  * Price=8.63 <- the price at which the trade occurred
  * Size=100 <- the number of shares involved in the trade
  * Source=17 <- an internal value for mapping to the quote source
  * Condition=? <- the Sales Condition value, where applicable
  * Tick=? <- identifies the trade as an uptick/downtick on markets, if applicable
  * MmId=C <- the market center on which the trade occurred
  * SubMarketId= <- the submarket center on which the trade occurred, if applicable
  * Buyer <- the buyer
  * Seller <- the seller

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. 

Examples:

<code>LocalTime=21:32:59.193,MarketTime=00:00:00.000,Symbol=WBC.AX,Type=1,Price=0,Size=0,Source=0</code>

<code>LocalTime=21:34:52.322,MarketTime=11:33:15.929,Symbol=WBC.AX,Type=2,Price=34.445,Size=59,Source=0,Condition=?,Tick=?,Mmid=C,SubMarketId=</code>

<code>LocalTime=21:32:59.209,MarketTime=00:00:00.000,Symbol=WBC.AX,Type=3,Price=0,Size=0,Source=0</code>

<code>LocalTime=21:34:42.916,MarketTime=11:34:41.913,Symbol=WBC.AX,Type=0,Price=34.44,Size=64,Source=42,Condition=?,Tick=?,Mmid=A,SubMarketId=</code>

For more information, see the complete list of PPro8 __[[https://metro.dttw.com/metro/sites/default/files/Manager%20Wiki/TOS%20Values%2020190823.pdf|TOS Values]]__ and __[[https://metro.dttw.com/metro/sites/default/files/Manager%20Wiki/PPro8%20Buyer%20Seller%20Codes.pdf|Buyer/Seller Codes]]__.

====Market Depth (L2)====

Example: <code>Register?symbol=ZVZZT.NQ&feedtype=L2</code>

This command registers the API to receive all Level 2/Market Depth updates for symbol ZVZZT.

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:

  * LocalTime=08:39:43.114 <- the time the update arrives on the user's machine and uses the user's computer's time
  * MarketTime=08:39:42.601 <- the market time of the update
  * Mmid=ANON <- the MMID (Market Maker ID) associated with the update
  * Side=B <- the side of the update
  * Price=8.6 <- the price of the update
  * Volume=100 <- the size in shares of the updated quote
  * Depth=1 <- the number of orders that make up the quote, where applicable
  * SequenceNumber=27003 <- the sequence number is unique by MMID, Price, and Side, and can be used to correct for out-of-sequence data

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.

=== Market Depth snapshot ===

If you would like to get a Market Depth snapshot, you can use the GetSnapshot command.

Example: <code>GetSnapshot?symbol=ZVZZT.NQ&feedtype=L2</code>

The snapshot begins with a line where Side=s, for example:

<code>LocalTime=08:37:31.908,MarketTime=00:00:00.000,Mmid=,Side=s,Price=0,Volume=0,Depth=0,SequenceNumber=0</code>

All messages making up the snapshot have SequenceNumber=0.

The snapshot ends with a line where Side=e, for example:

<code>LocalTime=08:37:31.908,MarketTime=00:00:00.000,Mmid=,Side=e,Price=0,Volume=0,Depth=0,SequenceNumber=0</code>
====Imbalance (IMBALANCE)====

Example: <code>Register?symbol=*.NQ,*.E1,*.TO&feedtype=IMBALANCE</code>

This command registers the API to receive all Imbalance data.

Messages for IMBALANCE must pass the market 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:

  * LocalTime=15:57:15.113 <- the time the update arrived on the user's machine and uses the user's computer's time
  * MarketTime=15:57:15.072 <- the market time of the update
  * Side=S <- the side of the imbalance
  * Type=O <- the type of imbalance, where applicable
  * Status=  <- the status of the imbalance, if applicable
  * Symbol=LKQ.NQ <- the symbol on which the imbalance exists
  * Price=32.875 <- the price of the stock
  * Volume=3578 <- the size of the imbalance in shares
  * Mmid=Q <- the market of the imbalance (Q=NASDAQ, N=NYSE, T=Toronto, V=Venture)
  * AuctionPrice=32.84 <- the theoretical auction price, where applicable
  * ContinuousPrice=32.86 <- the continuous price on the primary market, where applicable
  * PairedVolume=67428 <- the size, in shares, already paired off

Each imbalance update represents the current size of the imbalance. Previous messages for the same symbol can be discarded.

====Order Status (OSTAT)====

Example: <code>Register?region=1&feedtype=OSTAT</code>

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).

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 | 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:

  * LocalTime=09:35:34.237 <- the time the update arrived on the user's machine and uses the user's computer's time
  * MarketDateTime=20131011-09:35:34.048 <- the market date and time of the update
  * Currency=CAD <- the currency of the order
  * Symbol=TD <- the symbol on which the order was submitted
  * Gateway=2028 <- the Gateway ID on which the order was submitted
  * Side=B <- the side on which the order was submitted
  * OrderNumber=TESTTEST00000024M1713F3100000 <- the unique order number of the order
  * Price=92.72000000 <- the price of the order status update; for a new order it is the order price, for Fill / PartialFill it represents the price of the shares executed
  * Shares=100 <- the number of shares associated with the order status update; for a new order is it the order size, for a Fill / PartialFill it represents the number of shares executed
  * Position=2 <- a sequence number for messages related to the unique order number, for example, 1 is first, 2 is second, and so on
  * OrderState=Filled <- the status of the order represented by the update
  * MarketID=2 <- the market on which the order was submitted
  * CurrencyChargeGway=CAD <- the currency of the gateway charge
  * ChargeGway=-0.31 <- the gateway charge associated with this status update
  * CurrencyChargeAct=CAD <- the currency of the activity charge
  * ChargeAct=0.011 <- the activity charge associated with this status update
  * CurrencyChargeSec=CAD <- the currency of the SEC/Regulatory fee
  * ChargeSec=0 <- the SEC/Regulatory fee associated with this status update
  * CurrencyChargeExec=CAD <- the currency of the execution charge
  * ChargeExec=0.16 <- the execution charge associated with this status update
  * CurrencyChargeClr=CAD <- the currency of the clearing charge
  * ChargeClr=0.008 <- the clearing charge associated with this status update
  * OrderFlags=128 <- the order flags associated with the orders, used for internal processing only and to identify if the order was sent through PPro8 or the API
  * CurrencyCharge=10 <- internal value, not relevant for external analysis
  * Account=1TESTOF001TNVTESTTESTCAD1 <- the account associated with this order
  * InfoCode=255 <- internal value for tracking OSTAT codes, not relevant for external analysis
  * InfoText=LiqFlags=^Tag6888=20^Tag31=92.720^Tag9730=A <- additional information text, if any, associated with this status update

Order Flags are a sum of the below numbers:

  * ConvertToShortSell = 1
  * CancelOpposing = 2 
  * SetPriceToComply = 8 - this flag is sent when an order is sent from the Stock Window
  * AutoCancelOrder = 32 
  * AutoCancelOnPartialFill = 64 
  * SentViaPProApi = 128
  * SentViaScriptSrv = 256
  * 512 - this flag is sent when an order is rejected by OPC

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.

====Order Event (ORDEREVENT)====

**Example:** <code>Register?region=1&feedtype=ORDEREVENT</code>

This command registers the API to receive all Order Event (ORDEREVENT) messages for the user in region 1 (NCSA).

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:

  * LocalTime=08:39:45.442 <- the time the update arrived on the user's machine and uses the user's computer's time
  * MarketDateTime=20131025-08:39:45.208 <- the market date and time of the update
  * EventMessageType=1 <- the nature of the order event:
      * New Order Request = 1
      * Cancel Request = 3
      * Cancel Replace Request = 6
      * Manual Order Conf = 21
      * Change Order Flag Request = 23
  * EventFlavour=2 <- the internal state of the order event: see flavour descriptions list below
  * EventOriginatorId=1 <- the originator of the order event: 1 = Client, 2 = OPC, 3 = GS, 4 = SS
  * OriginatorSeqId=0 <- the sequence number of the event sent by the originator
  * Size=100 <- the size of the order, in shares
  * Price=8610000000 <- the price at which the order was submitted; uses PPro8 native price format, which needs to be divided by 10^8 (100000000) to show human-readable price
  * OrderNumber=TESTTEST00000003M171401100000 <- the unique number of the order
  * InfoText= <- additional information text associated with this order event, for example, the reject reason

Order_Event (ORDEREVENT) Flavour Descriptions as follows:

  *0 NoOrderEventFlavour <- the order has no event flavour
  *1 RequestPending - reports about a request that was made have no effect on the order state (initially Holding)
  *2 Accepted - the order is on the market
  *3 PartFill - the order is not open (State to Filled)
  *4 Filled - order not open (State to Filled)
  *5 Cancel - the order is not open (State to PartCancelled or Cancelled)
  *6 RejectedOrderClosed - the request was rejected, and the order number requested is not/no longer open
  *7 RejectedOrderOpen - the request was rejected, but the order is still live on the market
  *8 RejectedNoConnection - the request was rejected due to a network issue
  *9 CancelReplace - (State remains unchanged, either Accepted or PartFilled)
  *10 Holding - from the PPro8 Client, the order is being held, awaiting an event before being sent (State→Holding)
  *11 LastOrderEventFlavour - the last order event flavour

**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'.

====PProAPI Index to Order Number (PAPIORDER)====

Example: <code>Register?region=1&feedtype=PAPIORDER</code>

This command registers the API to receive information for orders sent through the API about the order number associated with each order request ID.

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:

  * LocalTime=10:10:07.006 <- the time the update arrived on the user's machine and uses the user's computer's time
  * PProApiIndex=3 <- the RequestID associated with an ExecuteOrder event as returned in XML
  * OrderNumber=DV10600503000002M171407100000 <- the order number associated with the RequestID

=====Deregister=====

This command is used to deregister for available data types. This stops the API from writing to log files or making L1 calls available.

Syntax: 

<code>Deregister?symbol=symbol.extension & region=[1|2|3|4] & feedtype=[L1|TOS|L2|IMBALANCE|NEWS]</code>

Examples:

<code>Deregister?symbol=ZVZZT.NQ&feedtype=NEWS</code>
<code>Deregister?symbol=\*.NQ,\*.E1,\*.TO&feedtype=IMBALANCE</code>

===Notes===

  * For IMBALANCE messages, define market, not region or symbol
  * Regional data centers: 1 = NewJersey, 2 = London, 3 = Hong Kong, 4 = Sydney
  * For L1, L2, or TOS data, define symbol
  * 'Lv1' and 'Tos' are deprecated but still available; update your scripts to use 'L1' and 'TOS'

=====Lv1 & Tos=====

'Lv1' and 'Tos' are deprecated, but still available. Update your scripts to use 'L1' and 'TOS'.

=====Get=====

This command gets information from Summary by layer. It returns the same total number of columns as the PPro8 GUI for all layers.

**New:** wildcard (*) is now allowed in this command, which means **All Symbols** or **All Traders** depending on the selected key.

Syntax: <code>Get?type=tool & tool=[Summary_n] & key=<regionAsset>[^<layerKey>]*</code>

Example: <code>Get?type=tool&tool=Summary_2&key=NCSA Equity^GODOT^F.NY</code>

===Notes===

  * To determine the key, open **Summary**, right-click a layer, and then click **Copy Key to Clipboard**.
  * The output will be written as CSV in the format <logged-on user>_<tool id>.log

====GetBlotter====

Use this command to return blotter information on a user ID.

Syntax: <code>GetBlotter?user=<userId></code>

Example: <code>http://localhost:8080/GetBlotter?user=GODOT</code>

Return: <code><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></code>

====GetBlotterSnapshot====

Use this command to request a Refresh from Summary.

Syntax: <code>GetBlotterSnapshot?trader=[USERID] & region=[1|2|3|4] & assetid=<assetId></code>

Example: <code>GetBlotterSnapshot?trader=DV113X91&region=1&assetid=1</code>

====GetBracketId====

Use this command to get the bracket ID of a symbol to send a bracket order for it.

Syntax: <code>GetBracketId?symbol=<symbol.extension></code>

Example: <code>GetBracketId?symbol=FB.NQ</code>

To send a bracket order, use two ExecuteOrder commands. For example:

<code>ExecuteOrder?symbol=FB.NQ&limitprice=10.10&ordername=&shares=100&bracketid=FB.NQ_1518813150_API</code>

<code>ExecuteOrder?symbol=FB.NQ&limitprice=20.10&ordername=&shares=100&bracketid=1518813150_API</code>

Executing both commands will send a bracket script with two manual orders as limits. Stop and trailing stop orders can be used as well.

====GetEnvironment====

This command recalls the environment the user is logged into (TMS or Live), and the user ID and directory where PPro8 is installed.

Syntax: <code>GetEnvironment?</code>

Return:

<code><Environment="Live" User="ABE001" DataDir="C:\Program Files\Ralota\Inka"/></code>

====GetL1Registrations====

This command returns all symbols registered for L1 per region.

Syntax: <code>GetL1Registrations?</code>

**Example:** <code>http://localhost:8080/GetL1Registrations?</code>

This will bring up current L1 registrations.

====GetLv1====

This command recalls Level 1 snapshot data. You must register for L1 data before trying to read it.

Syntax: <code>GetLv1?symbol=<symbol.extension></code>

**Example:** <code>GetLv1?symbol=TD.TO</code>

This will bring up the following response:

<code><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"/></code>

This GetLv1 response is a comma-separated line of data that includes the following fields:

  * Volume=798304 ← the volume of the symbol
  * LowPrice=55.1100 ← the low price
  * HighPrice=55.5000 ← the high price
  * OpenPrice=55.4000 ← the open price
  * ClosePrice=55.3400 ← the close price
  * MaxPermittedPrice=0 ← the maximum permitted price
  * MinPermittedPrice=0 ← the minimum permitted price
  * LotSize=100 ← the lot size
  * LastPrice=55.1100 ← the last price
  * InstrumentState=Open ← the instrument state
  * AssetClass=Equity ← the asset class
  * TickValue=0 ← the tick value
  * TickSize=0.00500000 ← the tick size
  * Currency=CAD ← the currency

====GetNewsDetails====

This command retrieves detailed information for a specific News ID.

Syntax: <code>GetNewsDetails?alertid=<alertId></code>

**Example:** <code>GetNewsDetails?alertid=201908026270</code>
====GetScriptState====

This command returns the state of a given Script ID (except Flatten scripts, which are not applicable).

**Note:** the GetOrderNumber command can also be used to retrieve a Script ID, as any script sent via API also returns a Request ID, much like the ExecuteOrder command does.

Syntax: <code>GetScriptState?scriptid=<scriptId></code>

Return: <code>script state</code>

Example: <code>http://localhost:8080/GetScriptState?scriptid=DV113X9100000004S1761A4100000</code>

The possible script states are as follows:

  * Done
  * Preparing
  * Paused
  * Paused by Error
  * Pending
  * Ready
  * Rejected
  * Running
  * Script Failed
  * Script Timed Out
  * Stopped by User
  * Waiting for Fill
  * Waiting for LV1
  * Waiting for Timer
  * Waiting for TOS

====GetTraderInfo====

This command returns information about a trader, including algorithm, LFT amount, NL amount, etc. Buying Power information is included as a part of the GetTraderInfo response.

Syntax: <code>GetTraderInfo?trader=<trader> & region=<region> & assetid=<assetId></code>

**Example:** <code>GetTraderInfo?trader=DV113X91&region=1&assetid=1</code>

Response: <code>traderId="DV113X91" regionId="1" assetclassId="1" traderState="1" algorithm="0" lftAmount="2000" netLossAmount="1500" timerIsActive="N" currentTimeRemaining="0"</code>

This response includes the following fields:

  * traderId=DV113X91 ← the ID of the trader
  * regionId=1 ← the ID of the region
  * assetclassId=1 ← the ID of the asset class
  * traderState=1 ← the state of the trader
  * algorithm=0 ← the ID of the algorithm
  * lftAmount=2000 ← the daily Loss From Top amount
  * netLossAmount=1500 ← the daily Net Loss amount
  * timerIsActive=N ← is the risk timer active (Yes or No)
  * currentTimeRemaining=0 ← the current time remaining in the risk timer

  * Trader State
    * 1 = Active
    * 2 = Disabled not flat
    * 3 = Disabled by User
    * 6 = Closed by User
    * 7 = Closed by Risk

  * Algorithm ID
    * 2 = Loss from Top
    * 3 = Net Loss

====GetTransactions====

This command recalls all executions for a user ID.

Syntax: <code>GetTransactions?user=<userID></code>

**Example:** <code>GetTransactions?user=GODOT</code>

Return:

<code><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></code>

**Note:** for Futures symbols, this command now returns Display Price instead of Contract Size.

====ValidateSymbol====

Use this command to check if Symbol is available in Ppro8, and the time parameter is just how long the client can wait for a response from the server before it fails.

Syntax : <code>ValidateSymbol?symbol=<symbol.extension> & time=<milliseconds></code>
Return : <validation status>

Examples:

  * http://localhost:8080/ValidateSymbol?symbol=BMO.TO
  * http://localhost:8080/ValidateSymbol?symbol=BMO.TO&time=1000

=====Order-related commands=====

You can use the API to interact with orders in several ways. For more detailed examples, see the PProAPI Portal (//http://localhost:8080 //).

====ExecuteOrder====

The ExecuteOrder command includes a number of values that can be entered depending on the chosen order type:

  * symbol=<symbol.ext> (can only be 1–16 characters in length maximum)
  * limitprice=<float> (must be a positive number)
  * ordername=<copied from Keyboard Setup> (use exact spelling, case, and spacing of order name)
  * shares=<int> (must be a positive number)
  * priceadjust=<float> (can be a positive or negative number)
  * stopprice=<float> (must be a positive number)
  * pegdifference=<float>
  * displaysize=<int> (must be a positive number)
  * displayrange=<int>
  * minexecsize=<int> (must be a positive number)

Syntax: <code>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></code>

Return: <code>requestId</code>

**Example:** <code>ExecuteOrder?symbol=BB.TO&limitprice=6.90&ordername=TSX Buy SweepSOR Limit ANON DAY Reserve&shares=1000&displaysize=100</code>

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.

===Notes===

  * The user must ensure that the required parameters are for the order type
  * By passing a cancel order, the new order will be in a Holding state until the cancel order is verified Cancelled
====ExecuteBasketOrder====

Use this command to send a basket order by name.

Syntax: <code>ExecuteBasketOrder?basketname=<basketName></code>

**Example:** <code>ExecuteBasketOrder?basketname=basket1</code>

====ExecuteListOrder====

Use this command to send orders from an order list (set using the __[[order list tool|Order List]]__ window in PPro8).

Syntax: <code>ExecuteListOrder?symbol=<symbol.ext>&orderlistname=<orderListName>&shares=<int></code>

**Example:** <code>ExecuteListOrder?symbol=ZVZZT.NQ&orderlistname=myList&shares=100</code>

====CancelAllScripts====

This command cancels all active/running scripts for the specified region/asset class.

Syntax: <code>CancelAllScripts?user=<userId> & region=<regionId> & assetid=<assetId></code>

**Example:** <code>http://localhost:8080/CancelAllScripts?user=DV113X91&region=1&assetid=1</code>

====CancelOrder====

This command reproduces the cancel functionality. It's possible to cancel multiple orders with this command.

**New:** this command is now available for use by manager accounts.

Syntax: <code>CancelOrder?type=ordernumber|all|oldest|newest|closest|furthest&ordernumber=<orderNumber>&symbol=<symbol.ext>|<*.*>|<*.ext>&side=order|bid|offer|sell|shortsell</code>

**Example:** <code>CancelOrder?type=all&symbol=ZVZZT.NQ&side=bid</code>

This example command sends a cancel request for all open orders on the bid side of ZVZZT.NQ.

CancelOrder command options:
  * <Symbol=*.*> to cancel orders on ALL symbols.
  * <Symbol=*.ext> to cancel orders on ALL symbols from a specific market.
  * <Side=Sell> to cancel only Sell orders.
  * <Side=ShortSell> to cancel only Short Sell orders.
  * <Side=Offer> to cancel both Sell orders and Short Sell orders.

===Notes===

  * For type=ordernumber, only the ordernumber parameter is required
  * For all other types, side and symbol must be defined

====CancelScript====

This command cancels a specific script.

Syntax: <code>CancelScript?scriptid=<scriptId></code>

**Example:** <code>http://localhost:8080/CancelScript?scriptid=DV113X9101000001S1772C7100000</code>
====OrderCancelReplace====

This command replaces the size of a selected order. With this function, the size can only be reduced, not increased.

Syntax: <code>OrderCancelReplace?ordernumber=<orderNumber> & shares=desired reduced number of shares</code>

Example: <code>OrderCancelReplace?ordernumber=GODOT___03000008M1711F7000000&shares=1000</code>

====GetOrderNumber====

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.

Syntax: <code>GetOrderNumber?requestid=<requestID></code>

Return: <code>orderNumber</code>
 
**Example:** <code>GetOrderNumber?requestid=3</code>

This command retrieves the order number for the order submitted on Request ID 3.

====GetOrderState====

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.

Syntax: <code>GetOrderState?ordernumber=<orderNumber></code>

Return: <code><OrderState></code>

**Example:** <code>GetOrderState?ordernumber=GODOT03000008M1711F7000000</code>

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:
  * 0 = eUninitialised
  * 1 = eHolding,  %%//!<%% Holding (unofficial premarket—not sent to market)
  * 2 = ePending,  %%//!<%% Pre Accepted/rejected (unofficial premarket—sent to market, no response yet)
  * 3 = eAccepted, %%//!<%% Accepted (open)
  * 4 = eAP,       %%//!<%% Part Filled (open)
  * 5 = eAPC,      %%//!<%% Part Cancelled (terminal eAP)
  * 6 = eAPF,      %%//!<%% Multi Filled (terminal eAP)
  * 7 = eAF,       %%//!<%% Filled (terminal eA)
  * 8 = eAC,       %%//!<%% Cancelled (terminal eA)
  * 9 = eRejected, %%//!<%% Rejected
  * 10 = eJunked,  %%//!<%% Junked

====GetOpenOrders====

Syntax: <code>GetOpenOrders?user=<userID></code>

Return: <code><Orders><Order id= state= /><Order id= state= />(....)</Orders></code>

Example: <code>GetOpenOrders?user=GODOT</code>

This command retrieves the states of orders by user ID. States include the following:

  * Accepted
  * Canceled
  * Holding
  * Rejected

This command also returns the following parameters:

  * Symbol
  * Price
  * Side
  * Gateway
  * Destination
  * MarketTime

**Note:** for Futures symbols, this command now returns Display Price instead of Contract Size.

====SendTrailingStop====

This command sends a trailing stop order according to set parameters.

Syntax: <code>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></code>

Example: <code>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</code>

====SendSwiftStop====

This command sends a stop order script according to set parameters.

Syntax: <code>SendSwiftStop?symbol=<symbol.ext> & limitprice=<float> & ordername=<copied from KeyboardSetup> & shares=<int> & swiftstopprice=<float></code>

Example: <code>SendSwiftStop?symbol=_STW60.E1&limitprice=10.10&ordername=AUTE Buy AUTE Limit ANON DAY&shares=100&swiftstopprice=10.08</code>

=====Position-related commands=====

====GetOpenPositions====

This command retrieves a list of the current open positions for a user ID, including Average Price.

Syntax: <code>GetOpenPositions?user=<userID></code>

Return: <code><Positions> <Symbol <data> />(....)</Positions></code>

Example: <code>GetOpenPositions?user=GODOT</code>

====Flatten====

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.

Syntax: <code>Flatten?symbol=<symbol.extension></code>

Example: <code>Flatten?symbol=ZVZZT.NQ</code>

This command can also be used for multiple symbols:

<code>Flatten?symbol=ZVZZT.NQ,ZWZZT.NQ,ZXZZT.NQ</code>

This command can also be used for a single or multiple market extensions:

<code>http://localhost:8080/Flatten?symbol=*.NQ</code>
<code>http://localhost:8080/Flatten?symbol=*.NQ,*.E1,*.TO</code>

This command can also be used by managers for a single or multiple traders:

<code>Flatten?symbol=<symbol.ext> & trader=<trader></code>

Examples:

<code>http://localhost:8080/Flatten?symbol=ZVZZT.NQ&trader=DV101</code>
<code>http://localhost:8080/Flatten?symbol=ZVZZT.NQ,ZWZZT.NQ,ZXZZT.NQ&trader=DV101,DV102</code>
<code>http://localhost:8080/Flatten?symbol=*.NQ&trader=DV101</code>
<code>http://localhost:8080/Flatten?symbol=*.NQ,*.E1,*.TO&trader=DV101,DV102</code>

===Notes===

  * If a single symbol is given, that symbol will be flattened for the logged-in trader
  * If symbol contains a list of symbols separated by commas, all those symbols will be flattened for each of the specified traders
  * If an asterisk is given with the market extension, all symbols belonging to that market will be flattened for each of the specified traders

====Get (Summary)====

This command retrieves Summary data by layers. For example, Get Summary by Trader.

Syntax: <code>Get?type=tool&tool=<summary instance>&key=<layer & row combination></code>

Example: <code>Get?type=tool&tool=Summary_1&key=NCSA Equity^GODOT^F.NY</code>

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.

=====Data Output Format=====

Data through the API can be exported into two formats: JSON, and XML. 

====JSON====

To output data as JSON, please take the following steps:

Copy and call the following syntax into your script:

<code>SetJSonON</code>

====XML====

To output data as XML, please take the following steps:

Copy and call the following syntax into your script:

<code>SetXMLON</code>

  * Note: You cannot call both of these functions at the same time.


=====Additional Notes=====

  * For more information about markets currently available for trading with the PProAPI, see the __{{pproapi_markets_list.xlsx|PProAPI Markets List}}__.