Definitions / Formulas

Useful definitions and formulas to better understand Vertex API.

Definitions

Unsettled USDC

Perp balances have two main components:

• amount

• v_quote_balance

When you buy a perp, amount increments and v_quote_balance decrements, and vice versa for selling.

Settlement is the process of converting from v_quote_balance into actual USDC balance. This happens mostly on position close, but may happen on extremely negative PNL positions when we need to pay out positive PNL positions.

The amount that is transferred between v_quote_balance in the perp and your USDC balance is an amount that results in amount * oracle_price + v_quote_balance == 0. Unsettled USDC is the total amount that would be transferred between v_quote_balance and your USDC balance summed across all perps.

Unsettled PNL

There is no such concept in our system.

Unrealized PNL

Refers to the estimated gains or losses of a current position based on the difference between the average entry price and the current oracle price.

Formulas

Unrealized PNL

Using the indexer's events query, your unrealized PNL at the end of some event is given by:

unrealized_pnl = (
    event.post_balance.amount * event.product.oracle_price_x18 
    - event.net_entry_unrealized
)

Total PNL

Your total PNL between event1 and event2, assuming event1 is after event2 - is given by:

total_pnl = (
    (event1.post_balance.amount * event1.product.oracle_price_x18 - event1.net_entry_cumulative)
    - (event2.post_balance.amount * event2.product.oracle_price_x18 - event2.net_entry_cumulative)
)

Notes:

• You can use 0 for the second term for the PNL to compute since the beginning of time.

• For spots, we will count deposits and withdraws towards your PNL. i.e. if you deposit BTC, for PNL tracking purposes it is counted as a BTC long at the oracle price.