PowerTrade Position Summary WebSocket API Specification

VERSION 1.1 (see Revision History)

1. Hosts

Environment	REST	WS	WebApp
DEV	https://api.rest.dev.power.trade/	wss://api.wss.dev.power.trade/	https://powertrade-web-dev.web.app/
TEST	https://api.rest.test.power.trade/	wss://api.wss.test.power.trade/	https://powertrade-web-test.web.app/
PROD	https://api.rest.prod.power.trade/	wss://api.wss.prod.power.trade/	https://app.power.trade/

Environment

REST

WebApp

DEV

https://api.rest.dev.power.trade/

wss://api.wss.dev.power.trade/

https://powertrade-web-dev.web.app/

TEST

https://api.rest.test.power.trade/

wss://api.wss.test.power.trade/

https://powertrade-web-test.web.app/

PROD

https://api.rest.prod.power.trade/

wss://api.wss.prod.power.trade/

https://app.power.trade/

2. WS Position Summary

2.1. WS /v1/position_summary

Returns a snapshot of account’s balances of fundable currencies.

Immediately after account creation this snapshot is empty. New balances get added to snapshot after 1st balance change of the corresponding currency (deposit, trade, fee, etc).

2.1.1. Authorization

HTTP header

X-Power-Trade: {PT_ACCESS_TOKEN}

or URL-query

?power_trade=${PT_ACCESS_TOKEN}`

2.1.2. Sample Request

wscat wss://api.wss.dev.power.trade/v1/position_summary?power_trade=${PT_ACCESS_TOKEN}

2.1.3. Sample Response

On every update, the full position snapshot is being sent:

{
    "account_id": "369",
    "account_health": "73.3963",
    "account_risk_status": "normal",
    "balances": [
        {
            "timestamp": 1707465057059528000,
            "deliverable_id": "2",
            "symbol": "USD",
            "cash_balance": "22920.12583025",
            "assets": "22936.4866906359",
            "mark_price": "1",
            "in_orders": "-2000",
            "orders_estimated_cash": "-2000",
            "orders_estimated_liabilities": "2689.4805",
            "unrealised": "-4621.30075",
            "margin": "13873.602",
            "available_balance": "2441.5839406359",
            "withdrawable_balance": "2441.5839406359",
            "components": {
                "cash": "22920.12583025",
                "cash_open_buy_orders": "-2000",
                "cash_open_buy_orders_committed": "-2000",
                "margin": "13873.602",
                "margin_open_buy_orders": "0",
                "margin_open_sell_orders": "0",
                "payoff": "0",
                "payout": "16.3608603859",
                "realised": "0",
                "unrealised": "-4621.30075",
                "unrealised_open_buy_orders": "2689.4805",
                "unrealised_open_sell_orders": "0"
            }
        },
        {
            "timestamp": 1707465057059528000,
            "deliverable_id": "13",
            "symbol": "Reference USD",
            "cash_balance": "69044.44",
            "assets": "69060.8",
            "mark_price": "1",
            "in_orders": "-2000",
            "orders_estimated_cash": "-2000",
            "orders_estimated_liabilities": "2689.48",
            "unrealised": "-4499.1",
            "margin": "13873.6",
            "available_balance": "48688.1",
            "withdrawable_balance": "0",
            "components": {
                "cash": "69044.44",
                "cash_open_buy_orders": "-2000",
                "cash_open_buy_orders_committed": "-2000",
                "cash_open_sell_orders": "0",
                "margin": "13873.6",
                "margin_open_buy_orders": "0",
                "margin_open_sell_orders": "0",
                "payoff": "-6373.97",
                "payout": "16.36",
                "realised": "0",
                "unrealised": "-4499.1",
                "unrealised_open_buy_orders": "2689.48",
                "unrealised_open_sell_orders": "0"
            }
        },
        {
            "timestamp": 1707465057059528000,
            "deliverable_id": "3",
            "symbol": "BTC",
            "cash_balance": "1",
            "assets": "1",
            "mark_price": "46249.31",
            "in_orders": "0",
            "orders_estimated_cash": "0",
            "orders_estimated_liabilities": "0",
            "unrealised": "0",
            "margin": "0",
            "available_balance": "1",
            "withdrawable_balance": "0.9635574382",
            "span_scenario": "-P+V",
            "components": {
                "cash": "1",
                "margin": "0",
                "margin_open_buy_orders": "0"
            }
        }
    ],
    "positions": [
        {
            "timestamp": 1707465057059528000,
            "deliverable_id": "24",
            "symbol": "BTC-USD-PERPETUAL",
            "size": "2",
            "mark_price": "46238.41",
            "average_entry_price": "45062.5",
            "upnl": "2351.82",
            "margin_value": "13873.602",
            "components": {
                "margin": "13873.602",
                "payout": "16.3608603859",
                "unrealised": "2351.82"
            }
        },
        {
            "timestamp": 1707465057059528000,
            "deliverable_id": "28213",
            "symbol": "BTC-20240223-42000C",
            "size": "-1.5",
            "mark_price": "4689.4805",
            "average_entry_price": "3000",
            "upnl": "-2534.22075",
            "margin_value": "0",
            "greeks": {
                "delta": "-1.31799",
                "theta": "44.73615",
                "gamma": "-0.000075",
                "vega": "-27.505845"
            },
            "components": {
                "cash_open_buy_orders": "-2000",
                "cash_open_buy_orders_committed": "-2000",
                "margin": "0",
                "margin_open_buy_orders": "0",
                "payoff": "-6373.965",
                "unrealised": "-7034.22075",
                "unrealised_open_buy_orders": "2689.4805"
            }
        }
    ]
}

2.1.4. Fields

components: values by position kind
span_scenario: appears in non-USD balances if margining is enabled. String shows the SPAN scenario used for the asset: "+P", "=P", "-P" - increase, no change, decrease Price "+V", "=V", "-V" - increase, no change, decrease Volatility

2.1.5. Position Kinds

The Position Kinds s available can be grouped according to the table below:

Table 1. Position Kinds and Classification
Portfolio Type	Position Kind	Classification	Description
Held Positions	`cash`	Assets	Assets make up actual funds that you hold or are due. The system treats such assets as usable collateral.
	`realised`
	`expired`
	`payout`
	`funding_due`
	`unrealised`	Profit or Loss	An unrealised position represents the potential profit or loss associated with the position based on current market value.
	`margin`	Value at Risk	A margin position represents the value at risk to the unrealised value of the position.
	`payoff`	Informational	A payoff position is an informational only position message that indicates what the current payoff of an option is.
	`risk`	Position Risk	A position risk message that contains risk related information for an option position (such as the greeks).
	`trading_limit`	Trading Limits	Trading limit positions are messages that show the state of internal trading limits which are used to determine how much collateral is recognised for a given deliverable.

Open Orders	`cash_open_buy_orders`	Potential Assets	These positions represent potential `cash` positions, lost or gained, should any orders with the associated deliverable execute. They are Potential Assets because there is no guarantee that any, or all, of the associated orders will ever execute and result in that gain or loss. However the risk engine must consider that potentially all orders could execute all at once, or a subset of orders could execute.
	`cash_open_sell_orders`	Potential Assets

	`cash_open_buy_orders_committed`	Committed Assets	These positions represent committed `cash` positions (usually only to buy), meaning the value committed to (for example) buy an option can no longer be considered to place another order. This is similar to the idea of a Trading Limit in that if you place an order buy some asset, such as BTC using $100, you can no longer use that $100 to buy some ETH as it is committed to the BTC purchase.
	`cash_open_sell_orders_committed`	Committed Assets

	`unrealised_open_buy_orders`	Potential Profit or Loss	These positions represent potential profit or loss (`unrealised`) positions, profit or loss that would result should any orders with the associated deliverable execute. They represent Potential Profit or Loss because there is no guarantee that any, or all, of the associated orders will ever execute and result in that gain or loss. However the risk engine must consider that potentially all orders could execute all at once, or a subset of orders could execute.
	`unrealised_open_sell_orders`	Potential Profit or Loss

	`margin_open_buy_orders`	Potential Value at Risk	These positions represent potential value at risk (`margin`) positions, that is the value at risk that would result should any orders with the associated deliverable execute, *given the current worst case scenario in force for the Positions Held* portfolio*. They represent Potential Value at Risk* because there is no guarantee that any, or all, of the associated orders will ever execute and result in that gain or loss. However the risk engine must consider that potentially all orders could execute all at once, or a subset of orders could execute.
	`margin_open_sell_orders`	Potential Value at Risk
Pending Orders	`cash_pending_buy_orders`	Potential Assets	These positions represent potential `cash` positions, lost or gained, should any pending order for the associated deliverable be accepted and immediately execute. They are Potential Assets because there is no guarantee that any, or all, of the associated orders will ever execute and result in that gain or loss. However the risk engine must consider that potentially all orders could execute all at once, or a subset of orders could execute. Since this is for a Pending Order there is no concept of committed cash positions. The order has not yet been accepted and so therefore no committment has been made.
	`cash_pending_sell_orders`	Potential Assets

	`unrealised_pending_buy_orders`	Potential Profit or Loss	These positions represent potential profit or loss (`unrealised`) positions, profit or loss that would result should any pending order for the associated deliverable be accepted and immediately execute. They represent Potential Profit or Loss because there is no guarantee that any, or all, of the associated orders will ever execute and result in that gain or loss. However the risk engine must consider that potentially all orders could execute all at once, or a subset of orders could execute.
	`unrealised_pending_sell_orders`	Potential Profit or Loss

	`margin_pending_buy_orders`	Potential Value at Risk	These positions represent potential value at risk (`margin`) positions, that is the value at risk that would result should any pending order for the associated deliverable be accepted and immediately execute and the *worst case scenario for the Positions Held* portfolio is updated to reflect the impact of such an order executing fully*. They represent Potential Value at Risk* because there is no guarantee that any, or all, of the associated orders will ever execute and result in that gain or loss. However the risk engine must consider that potentially all orders could execute all at once, or a subset of orders could execute.
	`margin_open_sell_orders`	Potential Value at Risk

For Open Order and Pending positions that have both a buy and sell position calculations about the impact of those positions on a portfolio can be carried out by netting the associated value fields of those positions.

2.1.6. Calculating Positions Health for Held Positions

Account Health is calculated as the ratio of Collateral account value to Total account value, where the "value" of an account is represented in the Reference Deliverable which is typically the USD value (if the Reference Deliverable is USD) of all account assets and obligations.

The Health of an account is calculated using the values for the Reference Deliverable positions as shown:

Calculating Positions Health

assets     = cash + realised + payout + funding_due + expired
liabilites = unrealised - margin

def health_score( assets, liabilites ):

    collateral = assets + liabilites
    norm_collateral = max(0, assets) + max(0, liabilites)

    health = 0
    if norm_collateral == 0:
        if collateral >= 0:
            health = 100
        else:
            health = 0
    else:
        health = 100 * collateral / norm_collateral
        health = max( 0, health )
        health = min( 100, health )

    return health

For example if the Reference Deliverable was deliverable_id == 1 ("USD" for example) and the position deliverable that is used to represent values in the Reference Deliverable is deliverable_id == 2 ("USD Reference Value" for example) then following positions would be used:

3. Revision History

Table 2. revision history:
Date	Version	Notes
2024-02-13	1.1	Add the Hosts section
2024-02-09	1.0	Initial Position Summary API documentation