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

# Positions

> Retrieve a wallet’s open positions, PnL metrics, and market metadata.

`client.data.core.getPositions` surfaces the holdings for a single wallet. Results include token
sizes, average price, cash/percent PnL, redeem/merge flags, and market metadata.

## Request

```ts theme={null}
const positions = await client.data.core.getPositions(params);
```

### Parameters

| Name            | Type                   | Required | Default    | Notes                                                                                               |
| --------------- | ---------------------- | -------- | ---------- | --------------------------------------------------------------------------------------------------- |
| `user`          | `string` (0x + 40 hex) | ✅        | –          | Wallet or proxy address.                                                                            |
| `market`        | `string[]`             |          | –          | Condition IDs (0x + 64 hex). Mutually exclusive with `eventId`.                                     |
| `eventId`       | `number[]`             |          | –          | Event IDs. Mutually exclusive with `market`.                                                        |
| `sizeThreshold` | `number`               |          | `1`        | Minimum token size to display.                                                                      |
| `redeemable`    | `boolean`              |          | `false`    | Restrict results to redeemable positions.                                                           |
| `mergeable`     | `boolean`              |          | `false`    | Restrict results to mergeable positions.                                                            |
| `limit`         | `number` (0–500)       |          | `100`      | Page size.                                                                                          |
| `offset`        | `number` (0–10000)     |          | `0`        | Page offset.                                                                                        |
| `sortBy`        | enum                   |          | `"TOKENS"` | `CURRENT`, `INITIAL`, `TOKENS`, `CASHPNL`, `PERCENTPNL`, `TITLE`, `RESOLVING`, `PRICE`, `AVGPRICE`. |
| `sortDirection` | enum                   |          | `"DESC"`   | `ASC` or `DESC`.                                                                                    |
| `title`         | `string` (≤ 100 chars) |          | –          | Case-insensitive title filter.                                                                      |

> ⚠️ **Mutually exclusive filters** — Provide either `market` or `eventId`, not both. The SDK throws
> a validation error highlighting both fields if used together.

## Response

```ts theme={null}
type Position = {
  proxyWallet: string;
  asset: string;
  conditionId: string;
  size: number;
  avgPrice: number;
  initialValue: number;
  currentValue: number;
  cashPnl: number;
  percentPnl: number;
  totalBought: number;
  realizedPnl: number;
  percentRealizedPnl: number;
  curPrice: number;
  redeemable: boolean;
  mergeable: boolean;
  title: string;
  slug: string;
  icon: string;
  eventSlug: string;
  outcome: string;
  outcomeIndex: number;
  oppositeOutcome: string;
  oppositeAsset: string;
  endDate: string;
  negativeRisk: boolean;
};
```

Unexpected fields are preserved via `passthrough()` so you can adopt new attributes without waiting
for a release.

## Usage example

```ts theme={null}
const positions = await client.data.core.getPositions({
  user: "0x56687bf447db6ffa42ffe2204a05edaa20f55839",
  limit: 25,
  sortBy: "CASHPNL",
});

positions.forEach((position) => {
  console.log(`${position.title}: ${position.cashPnl.toFixed(2)} USDC`);
});
```

## Failure modes

* Missing `user` → validation error.
* Conflicting filters → validation error naming both `market` and `eventId`.
* HTTP failure → `HttpError` with `status`, `statusText`, and `body`.
* Network failure → `Error("Network error: …")` with the original `cause`.