Skip to main content

Positions and PnL

When you buy or sell tokens on Intotes, the platform tracks your holdings as positions. Each position represents your net exposure to a specific outcome in a market.

Position Structure​

A position record contains the following key fields:

FieldDescription
market_idThe market this position belongs to.
token_type"YES" or "NO" -- which token you hold.
amountNumber of shares held, in cents. Always a positive value.
avg_priceThe volume-weighted average price at which the position was acquired (0--10000).

Long and Short Positions​

  • Long position = holding YES tokens. You profit if the event resolves YES and the price increases.
  • Short position = holding NO tokens. You profit if the event resolves NO (equivalently, if the YES price decreases).

In the data model, a positive token amount indicates a long position in that token type. If you hold YES tokens, you are long on YES; if you hold NO tokens, you are long on NO (which is effectively short on the event outcome).

Average Price Tracking​

The avg_price is updated with each trade that adds to the position. It represents the weighted average cost basis of all shares in the position:

avg_price = total_cost / total_shares

When you partially close a position (sell some shares), the avg_price remains unchanged -- it always reflects your original cost basis for the remaining shares.

Unrealized PnL​

Unrealized PnL (profit and loss) represents the gain or loss you would realize if you closed the position at the current market price:

unrealized_pnl = (current_price - avg_price) * amount    // for YES (long)
unrealized_pnl = (avg_price - current_price) * amount    // for NO (short on YES)

This value fluctuates as market prices change and is displayed in real time on position views.

Position with Details​

The API returns enriched position objects (PositionWithDetails) that include contextual information beyond the raw numbers:

FieldDescription
event_nameName of the parent event.
pool_nameName of the pool containing the market.
market_nameName of the specific market.
current_priceLatest market price for the token type.
unrealized_pnlCalculated unrealized profit/loss.

This eliminates the need for additional API calls to resolve event and market names when displaying positions in a UI.

Closed Positions​

When a position is fully closed (either manually or via settlement), it becomes a closed position with additional settlement data:

FieldDescription
pnlRealized profit or loss in cents.
won_sideThe outcome that won when the event resolved ("YES" or "NO").
closed_atTimestamp when the position was closed.

Closed positions are available as ClosedPositionWithDetails objects, which include all the context fields from the open position view plus the settlement information.

Retrieving Positions​

Open Positions​

Open positions are returned as part of user portfolio endpoints. Each open position includes the current market price and unrealized PnL.

Closed Positions​

GET /api/v1/market/positions/completed
Authorization: Bearer <token>

Returns a list of all closed positions with full details including realized PnL, the winning side, and event/market context.

Settlement​

When an event resolves, all open positions in its markets are settled automatically:

  • Winning side (e.g., YES tokens when the event resolves YES): Each share pays out 10000 cents (100%).
  • Losing side (e.g., YES tokens when the event resolves NO): Each share pays out 0 cents.

Your realized PnL from settlement is:

pnl = (payout_per_share - avg_price) * amount

For winners: pnl = (10000 - avg_price) * amount For losers: pnl = (0 - avg_price) * amount

See Also​