Positions

A Position represents a user's holding in a specific market. When you buy shares in a market, you receive a position. Positions track what you hold, at what average price you bought, and whether you are betting for (YES) or against (NO) an outcome.

---

Position fields

Field	Type	Description
id	integer	Unique identifier.
user_id	integer	The user who holds this position.
market_id	integer	The market this position belongs to.
token_type	string	"YES" or "NO" — the type of shares held.
amount	integer	Number of shares held, in cents. Always positive.
avg_price	integer	Volume-weighted average purchase price, in the 0-10,000 scale (see Prices and Probability).
use_bonus	boolean	Whether this position was purchased using bonus balance.
created_at	timestamp	When the position was first opened.

---

Long and short

Intotes positions are directional:

• Long (YES) — You hold YES tokens. You profit if the outcome resolves YES. Your token_type is "YES" and amount is positive.
• Short (NO) — You hold NO tokens. You profit if the outcome resolves NO. Your token_type is "NO" and amount is positive.

In both cases, amount is always a positive number representing the number of shares you hold (in cents). The direction of your bet is determined by token_type, not by the sign of amount.

---

Settlement and PnL

When a market resolves, positions are settled automatically:

• Winners (holding the correct token type) receive 10,000 per share (in cents). Since prices are always below 10,000 when buying, this guarantees a profit.
• Losers (holding the wrong token type) receive 0. They lose their entire investment.

PnL calculation

Profit and Loss is calculated as:

For winners:   PnL = (10000 - avg_price) * amount / 10000
For losers:    PnL = -avg_price * amount / 10000

For example, if you bought 50,000 cents of YES shares at an average price of 2,600 (26%):

• If YES wins: PnL = (10,000 - 2,600) * 50,000 / 10,000 = +37,000 cents
• If NO wins: PnL = -2,600 * 50,000 / 10,000 = -13,000 cents

---

Closed positions

When a position is settled (either through market resolution or manual close), it becomes a ClosedPosition. This adds the following fields on top of the base position:

Field	Type	Description
pnl	integer	Realized profit or loss in cents. Positive means profit, negative means loss.
won_side	integer | null	0 = YES won, 1 = NO won, null = manually closed before resolution.
closed_at	timestamp	When the position was closed.

Manual close vs. resolution

There are two ways a position can close:

1. Market resolution — The event outcome is determined. All positions in the market are settled automatically. won_side is set to 0 (YES won) or 1 (NO won).

2. Manual close — The user sells their shares back to the market before resolution (at the current market price). won_side is null, and pnl reflects the difference between the sell price and the average purchase price.

---

Bonus balance

The use_bonus flag indicates that a position was opened using the user's bonus balance instead of their main balance. Bonus balance comes from referral rewards and promotional credits. When a bonus position is settled, the payout goes to the main balance, but the original bonus funds are not returned if the position loses.

---

Position enrichment in the API

When positions are returned as part of a user profile (GET /api/v1/users/me or GET /api/v1/users/{id}), they include additional context fields for display:

Field	Description
event_id	ID of the parent event.
event_name / event_name_ru	Event name for display.
event_image	Event cover image URL.
pool_name / pool_name_ru	Pool (question) name.
market_name / market_name_ru	Market name within the pool.
side / side_ru	Human-readable side label (e.g., "YES" / "DA").
unrealized_pnl	Estimated PnL based on the current market price (best bid/ask), before the position is closed.

For closed positions, the enriched response additionally includes the pnl, won_side, and closed_at fields described above.

---

Example lifecycle

1. Open — User places a BUY order for YES shares at price 3,500. Order fills and creates a Position with token_type: "YES", amount: 28571 (shares received), avg_price: 3500.

2. Hold — The market moves. The user's unrealized_pnl fluctuates based on the current market price.

3. Close — Either:

   • The market resolves YES: user receives 10,000 per share, position is closed with positive PnL.
   • The market resolves NO: user receives 0, position is closed with negative PnL.
   • The user manually sells at price 5,200: position is closed with PnL based on the difference (5,200 - 3,500) per share.