6. Position and Accounting - adharapayments/REST-API GitHub Wiki

• Streaming accounting service provides a constant flow of events when there is a change in the accounting status of selected accounts, as well all changes in global strategy accounting.
• Polling (non-streaming) accounting service provides current opened positions and global strategy accounting.
• Trading strategies should open a single stream to receive all accounting changes/events from different accounts.
• Minimum latency is provided by this service to increase execution probability of a cancel or modification request on an order.
• While streaming, JSON heartbeat objects are sent if there is no accounting change during a second.
• Typically a trading strategy will send new orders when a price change is detected, an order is executed, or an accounting event indicates that there is more margin available for trading.
• Typically a trading strategy will cancel a 'pending order' if accounting events indicate that a margin call could be generated.
• Margin call events are signaled through this service when there is no margin for trading on any of the accounts, or if a trading strategy has a specific limit (margin) for trading.
• Any opened position by a trading strategy can be a 'cash' position or a 'swap' position. Please refer to Adhara's ACT trading documentation.

$ curl -i --data '{"getPosition":{"user":"demo","token":"E79133C6902B63D2E5F5D9E9F1E658019F143675"}}' http://actfx.adhara.io:81/cgi-bin/IHFTRestStreamer/getPosition --header 'Content-Type: application/json'

HTTP/1.1 200 OK
Date: Thu, 02 Jul 2015 15:16:05 GMT
Server: Apache/2.4.7 (Ubuntu)
Transfer-Encoding: chunked
Content-Type: application/json;charset=iso-8859-1

{ "getPositionResponse": {

   "accounting": {

      "m2mcurrency": "EUR",
      "strategyPL": 9.049119,
      "totalequity": 9.049119,
      "usedmargin": 2499.773772,
      "freemargin": -2490.724653 },

   "assetposition": [

      { "account": "AC1",
        "asset": "EUR",
        "exposure": 0.000000,
        "totalrisk": 100000.000000,
        "pl": 100000.000000 },

      { "account": "<AGGREGATED>",
        "asset": "EUR",
        "exposure": 0.000000,
        "totalrisk": 100000.000000,
        "pl": 100000.000000 },

      { "account": "AC1",
        "asset": "USD",
        "exposure": 21.000000,
        "totalrisk": -110498.000000,
        "pl": -103285.242458 },

      { "account": "<AGGREGATED>",
        "asset": "USD",
        "exposure": 21.000000,
        "totalrisk": -110498.000000,
        "pl": -103285.242458 } ],

   "securityposition": [

      { "account": "AC1",
        "security": "EUR/USD",
        "exposure": 100000.000000,
        "side": "buy",
        "price": 1.105190,
        "pips": 5,
        "pl": -12.348273 },

      { "account": "<AGGREGATED>",
        "security": "EUR/USD",
        "exposure": 100000.000000,
        "side": "buy",
        "price": 1.105190,
        "pips": 5,
        "pl": -12.348273 } ],

   "timestamp": "1445962494.648742" }
}

{ "getPositionResponse": {
   "heartbeat": {
      "asset": [ "AED", ..., "ZAR" ],
      "security": [ "AUD/CAD", ..., "ZAR/JPY" ],
      "account": [ "AC1", "AC2" ] },
   "timestamp": "1445962495.648981" }
}

• user: Required. Strategy login assigned by the backend administrator.
• token: Required. Token obtained during the authentication procedure.
• asset: Optional. List of assets where detected accounting changes/events will be streamed. When non defined all assets will be used.
• security: Optional. List of securities where detected accounting changes/events will be streamed. When non defined all securities will be used.
• account: Optional. List of accounts where detected accounting changes/events will be streamed. When non defined all accounts will be used.
• interval: Optional. Inter-message time interval (in milliseconds). When defined streamed positions are sent at a given rate to prevent high throughputs and overkilling a mobile data plan. Default value: Positions are streamed in real-time (no interval is defined) when any change on a position is detected.

getPositionResponse can include a list of accounting changes/event or heartbeats. It also includes a timestamp.

• accounting: Object that includes global accounting information. The currency of these fields depends on the denomination currency (usually USD):

  • m2mcurrency: Denomination currency of the system (usually 'EUR' or 'USD'). Following amounts are expressed in this asset.
  • strategyPL: Equity of the strategy (that can be considered the 'strategy P&L').
  • totalequity: Total equity from all user strategies (that can be considered the final 'user P&L').
  • usedmargin: Equity used in open positions (considering all asset and security positions).
  • freemargin: Equity available for trading (this equals to 'totalequity' minus 'usedmargin'). All strategies of the same user share the equity (and therefore the 'freemargin').

• assetposition: Object that includes a list of open 'cash' positions with following fields:

  • account: Account name of the prime broker account where position is opened.
  • asset: Name of the asset with the opened 'cash' position.
  • exposure: Total amount of the opened position (in 'asset' units).
  • totalrisk: Total position amount considering the asset exposure and all security positions based on this asset (see 'securityposition' object).
  • pl: Mark2market of this position calculated in the 'denomiation currency'.

• securityposition: Object that includes a list 'swap' positions with following fields:

  • account: Account name of the prime broker account where position is opened. A special '' account will be provided with the sum of all account positions.
  • security: Name of the security with the opened 'swap' position.
  • exposure: Total amount of the opened position.
  • side: Side of the position ("buy" or "sell").
  • price: Closed price of the position.
  • pips: Number of decimals that defines the "pips" of the price.
  • pl: Mark2market of profit/loss that will be obtained if the position would be closed (calculated in the 'denomiation currency').

• heartbeat: Keep alive object which is sent when there is no change in orders during 1000ms. It includes a list of all accounts associated to the streaming with following fields:

• timestamp: Epoch time of the orders or heartbeat. Decimals define the number of micro-seconds. Integer part represents the seconds from "epoch" time.