> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orica.markets/llms.txt
> Use this file to discover all available pages before exploring further.

# Positions & Payouts

> How positions work and how winnings are calculated.

A position represents the shares you hold in a market's outcomes. Understanding positions is essential for tracking your exposure and calculating potential payouts.

***

## Position Structure

Each user has one position account per market (or none if they haven't traded):

```typescript theme={"dark"}
interface Position {
  market: PublicKey;      // Which market
  user: PublicKey;        // Your wallet
  outcomeAmounts: BN[];   // Shares per outcome
}
```

**Example** (Binary market):

```json theme={"dark"}
{
  "market": "ABC123...",
  "user": "MyWallet...",
  "outcomeAmounts": [1500, 0]  // 1500 "Yes" shares, 0 "No" shares
}
```

***

## How Shares Work

> [card] Buying Shares
>
> When you buy:
>
> * USDC leaves your wallet
> * New shares are minted
> * Your position increases
> * Price rises for that outcome

> [card] Selling Shares
>
> When you sell:
>
> * Shares are burned
> * USDC returns to your wallet
> * Your position decreases
> * Price falls for that outcome

***

## Calculating Position Value

Your position's current value depends on share prices:

$$
Value = \sum_{i=0}^{n} shares_i \times price_i
$$

```typescript theme={"dark"}
function calculatePositionValue(
  position: Position,
  prices: number[]
): number {
  return position.outcomeAmounts.reduce((total, shares, i) => {
    return total + (shares.toNumber() * prices[i]);
  }, 0);
}
```

***

## Payout Calculation

When a market resolves, only the winning outcome's shares have value:

> [tab] Standard Resolution
>
> **Winning shares** redeem for \$1 each (minus fees):
>
> $$
> Payout = shares_{winning} \times (1 - fee_{redemption})
> $$
>
> **Example**: 1000 winning shares with 0.30% fee
>
> * Gross: \$1000.00
> * Fee: \$3.00
> * Net payout: \$997.00

> [tab] Unresolvable (255)
>
> All participants receive proportional refunds based on their total investment.
>
> $$
> Refund = \frac{investment_{user}}{investment_{total}} \times pool_{total}
> $$

***

## Multi-Outcome Positions

In markets with more than 2 outcomes, you can hold shares in multiple outcomes simultaneously:

```json theme={"dark"}
{
  "outcomeAmounts": [500, 300, 200, 0]  // 4 outcomes
}
```

This allows for hedging strategies—you might believe outcomes A or B are likely but not C or D.

***

## Position Creation

Positions are created automatically on your first trade in a market:

1. User submits buy instruction
2. Program checks for existing position
3. If none exists, position PDA is created
4. Shares are added to position
5. Position persists until manually closed (if supported)

> [!NOTE]
>
> Position accounts require rent (\~0.002 SOL). This is paid on first trade and refunded if the account is closed.

***

## Fetching Positions

> [tab] Single Position
>
> ```typescript theme={"dark"}
> const position = await sdk.orica.fetchPosition(
>   marketAddress,
>   userPubkey
> );
>
> if (position) {
>   console.log("Shares:", position.outcomeAmounts);
> }
> ```

> [tab] All User Positions
>
> ```typescript theme={"dark"}
> const positions = await sdk.orica.fetchUserPositions(userPubkey);
>
> for (const { publicKey, account } of positions) {
>   console.log("Market:", account.market.toBase58());
>   console.log("Shares:", account.outcomeAmounts);
> }
> ```

***

## Best Practices

> [card] Check Before Selling
>
> Always verify your position balance before submitting a sell instruction to avoid transaction failures.

> [card] Track Multiple Markets
>
> If you're active in many markets, fetch all positions periodically to monitor exposure.

> [card] Redeem Promptly
>
> While there's no expiration, redeeming promptly frees up your capital for other opportunities.

> [card] Account for Fees
>
> Factor in trading and redemption fees when calculating expected returns.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.