ritmex-bot/docs/nado/developer-resources/api/definitions-formulas.md

Definitions / Formulas

Definitions

Unsettled USDT0

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 USDT0 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 USDT0 balance is an amount that results in amount * oracle_price + v_quote_balance == 0. Unsettled USDT0 is the total amount that would be transferred between v_quote_balance and your USDT0 balance summed across all perps.

Unsettled PNL

Note: Technically, there is no such concept as "Unsettled PNL" in our system. However, the UI displays "Unsettled PnL" in some places (e.g., in the USDT0 Balance section) for user clarity.

What the UI actually shows: When you see "Unsettled PnL" in the UI, it refers to Unsettled USDT0 (see above) - the total unsettled quote balance across all perp positions.

For developers: Always use Unsettled USDT0 when referring to this value programmatically. It represents the sum of amount × oracle_price + v_quote_balance across all perp positions, which is the amount that would be settled into your USDT0 balance.

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:

{% code lineNumbers="true" %}

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

{% endcode %}

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

{% hint style="info" %} 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. {% endhint %}