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/

STAGING

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

wss://api.wss.staging.power.trade/

https://powertrade-web-staging.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

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

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

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

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

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

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

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