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

# Positions

> Outcome-token holdings derived from trade history.

Positions are your exposure to specific market outcomes. They are
**derived** from your trade history — always consistent with your
executed trades.

## Reading positions

```http theme={null}
GET /api/me/positions
X-Api-Key: ps_live_<keyId>_<secret>  # integrators — needs `portfolio:read`
```

Response:

```json theme={null}
[
  {
    "marketId": "UAE-CUP-FINAL-20260425",
    "outcome": "0",
    "quantity": "250",
    "avgCost": "0.5140",
    "currentPrice": "0.5140",
    "realizedPnl": "0",
    "unrealizedPnl": "0"
  }
]
```

### Field semantics

* `quantity` — net long position in **outcome-share units** (decimal
  string at the same 6-decimal scale as USDC face value). E.g.
  `"250"` = 250 full outcome shares; `"250.500000"` = 250.5 shares.
  When a market resolves YES, every YES share redeems for 1 USDC, so
  this number is also your maximum payout if the outcome wins. Sum of
  `BUY quantity` minus `SELL quantity` over trades.
* `avgCost` — weighted average cost basis over retained quantity
  (decimal USDC).
* `currentPrice` — present MVP value: same as `avgCost`.
* `realizedPnl` / `unrealizedPnl` — `0` in the MVP.

## Split / Merge

<Info>
  **Availability:** split / merge endpoints are available via partner
  onboarding. The flow requires dual-signature calls to the user's
  vault.
</Info>

### Split — USDC → full outcome set

```http theme={null}
POST /api/vault/split-signature
{
  "marketId": "UAE-CUP-FINAL-20260425",
  "amount": "100",
  "signature": "0x...",
  "salt": "0x...",
  "deadline": 1713800000
}
```

Result: 100 USDC → 100 YES + 100 NO (binary).

### Merge — full outcome set → USDC

Symmetric. Burns 1 YES + 1 NO, returns 1 USDC.

Both operations are dual-sig, state-machine-driven, and audited.