Position Lifecycle

Overview

Norena models positions as a simple spot long: you hold some quantity of an asset, bought at a specific entry price, and you exit at a later price. There are no shorts, no leverage, and no margin. Each project + symbol pair can have at most one open position at a time.

Opening a Position

A position is opened when HP.buy(usd) is called and the broker accepts the order. The sequence is:

1. The strategy calls HP.buy(500) — buy $500 worth.
2. The runner captures the trigger snapshot (mark price, condition rows) synchronously.
3. The broker checks: is there an existing open position for this project + symbol? If yes, the BUY is rejected silently.
4. If no position exists:
   • Paper mode: fill price = current mark price. Quantity = USD ÷ fill price. Fee = $0.
   • Live mode: a Binance MARKET order is placed. Fill price = exchange fill. Quantity = exchange fill quantity. Fee = Binance fee (paid in BNB or base asset).
5. A project_positions row is inserted with status: 'open', entry_price, qty, and entry_time.
6. A project_trades row is inserted for the BUY side.
7. TRADE_TRIGGER and TRADE_EXECUTED logs are written and linked to the trade row.

Tracking an Open Position

While a position is open, the runner reads it from the database at the start of each tick via a fresh query to project_positions. The position data is stored in apositionRef reference that is kept current across the tick and refreshed after each trade action.

The following strategy functions read from the active position:

Unrealized PnL is not persisted between ticks — it is computed on demand in the UI by comparing the current mark price against the stored entry price and quantity.

Closing a Position

A position is fully or partially closed when HP.sell(pct) is called. The sequence mirrors the open flow:

1. Strategy calls HP.sell(100) — sell 100% of the position.
2. Trigger snapshot is captured (mark price, condition rows).
3. Broker checks: is there an open position? If not, the SELL is rejected silently.
4. If a position exists:
   • Paper mode: fills at current mark price with no fee.
   • Live mode: places a MARKET sell order for qty × (pct/100) units.
5. If pct = 100 (or the resulting remaining quantity rounds to zero), the position row is updated to status: 'closed' with close_price and closed_at.
6. A project_trades row is inserted for the SELL side.
7. TRADE_TRIGGER and TRADE_EXECUTED logs are written.

PnL Calculation

Realized PnL for a closed position is computed as:

pnl_usd = (close_price - entry_price) × qty_sold - fees
pnl_pct = (close_price - entry_price) / entry_price × 100

In paper mode, fees are always zero. In live mode, Binance fees are deducted from the fill result. The project_trades row stores both the gross fill value and the net amount after fees.

Partial Sells

Calling HP.sell(50) sells half the position. The position row remainsopen with qty reduced to the remaining amount. A SELL trade row is created for the portion sold.

The position is only marked closed when:

• A 100% SELL is executed, or
• A partial SELL results in a remaining quantity that rounds to zero.

The Positions Tab

The Positions tab inside each project shows all trades — both open and closed — sorted by most recent first. Each row displays:

Clicking any row opens the Trade Detail Modal, which shows the full TRADE_TRIGGER condition table and TRADE_EXECUTED fill details for that specific trade.

How Trades Are Stored

Each trade action creates or updates two database records:

The trade row links to both log entries via trigger_log_id andexecuted_log_id. The position row links to the most recent trade via its own foreign key. This structure makes it possible to reconstruct the full context of any trade — conditions, prices, fees, and slippage — from a single trade ID.