Positions & payouts

What a position is

When you buy Yes or No shares on a market, the matched fill creates (or grows) a position record on your account. Each position is scoped to one (market, outcome) pair — buying Yes and No on the same market gives you two separate positions.

• Shares — the count of outcome shares you hold. Always a non-negative integer.
• Cost basis — the total USDC you paid (net of fees) to accumulate the current share count.
• Average buy price — your weighted average entry price, useful for unrealised P&L computation against the live mid.

How positions are opened

Place a limit order (or a marketable limit) on the side you want exposure to. Each fill the matcher posts against your order grows the corresponding position in atomic ledger steps — you never end up with a partial-fill orphan. If you submit a buy on the Yes side and later a buy on the No side of the same market, the two positions are tracked independently.

Reading your position

GET /api/v1/me/positions returns one entry per (market, outcome) pair you currently hold. The fields you'll use most:

• shares — non-negative integer count of outcome shares.
• avg_buy_price — weighted average entry price in BPS (10000 = $1.00). Use for unrealised P&L vs. the current mid.
• cost_basis — total USDC paid to accumulate the current share count, expressed in dollars at the API boundary.

Payouts at resolution

Every share resolves to either 1.00 USDC (if the outcome wins) or 0.00 USDC (if it loses). The payout is mechanical — your profit per share is `outcome_value − price_paid` if you win, and `−price_paid` if you lose. Examples for a single share:

Payouts are credited atomically once the 2-hour dispute window closes with no upheld disputes. If a dispute is upheld, the market returns to active (trading) status — a fresh propose-and-confirm cycle is required before a new dispute window opens.

Closing a position before resolution

You don't have to hold to resolution. Place a sell order at any time; matched fills reduce your share count and post the proceeds to your USDC balance in the same atomic step. Partial sells leave the remaining position intact at the unchanged cost basis.

Where positions live

Positions are recorded in SatoriEx's double-entry ledger — every share movement has matching debit and credit entries. Today, this is the only representation of your holdings. The Conditional Token Framework (CTF) contracts that would represent each share as an on-chain ERC-1155 token exist and will enable optional self-custody in a future release; they are not active for settlement today.