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

# Portfolio API Overview

> View positions and trading activity

# Portfolio API

The Portfolio API provides access to user positions and trading activity history.

## Endpoints

### Positions

| Method | Endpoint                  | Description                  |
| ------ | ------------------------- | ---------------------------- |
| `GET`  | `/v1/portfolio/positions` | Get user's trading positions |

### Activities

| Method | Endpoint                   | Description                  |
| ------ | -------------------------- | ---------------------------- |
| `GET`  | `/v1/portfolio/activities` | Get trading activity history |

## Positions Response

The positions response returns a **map of market slug to position**, not an array:

```json theme={null}
{
  "positions": {
    "will-x-happen": {
      "netPosition": "100",
      "qtyBought": "100",
      "qtySold": "0",
      ...
    },
    "another-market": {
      "netPosition": "-50",
      ...
    }
  },
  "nextCursor": "abc123",
  "eof": false
}
```

### Position Fields

| Field            | Type               | Description                                               |
| ---------------- | ------------------ | --------------------------------------------------------- |
| `netPosition`    | string (int64)     | Net position quantity (positive = long, negative = short) |
| `qtyBought`      | string (int64)     | Total quantity bought                                     |
| `qtySold`        | string (int64)     | Total quantity sold                                       |
| `cost`           | Amount             | Total cost basis                                          |
| `realized`       | Amount             | Realized profit/loss                                      |
| `cashValue`      | Amount             | Current unrealized value                                  |
| `qtyAvailable`   | string (int64)     | Quantity available to trade                               |
| `bodPosition`    | string (int64)     | Beginning of day position                                 |
| `expired`        | boolean            | Whether the position has expired                          |
| `updateTime`     | string (date-time) | Last update timestamp                                     |
| `marketMetadata` | object             | Market information (slug, title, outcome)                 |

## Activities Response

Activities are returned as an array with pagination:

```json theme={null}
{
  "activities": [
    {
      "type": "ACTIVITY_TYPE_TRADE",
      "trade": { ... }
    }
  ],
  "nextCursor": "xyz789",
  "eof": false
}
```

### Activity Structure

Each activity has a `type` field and a corresponding nested object:

| Type                                | Nested Field           | Description               |
| ----------------------------------- | ---------------------- | ------------------------- |
| `ACTIVITY_TYPE_TRADE`               | `trade`                | Trade execution details   |
| `ACTIVITY_TYPE_POSITION_RESOLUTION` | `positionResolution`   | Market settlement details |
| `ACTIVITY_TYPE_ACCOUNT_DEPOSIT`     | `accountBalanceChange` | Deposit details           |
| `ACTIVITY_TYPE_ACCOUNT_WITHDRAWAL`  | `accountBalanceChange` | Withdrawal details        |
| `ACTIVITY_TYPE_TRANSFER`            | `accountBalanceChange` | Transfer details          |

### Trade Object

| Field         | Type               | Description                         |
| ------------- | ------------------ | ----------------------------------- |
| `id`          | string             | Exchange-assigned trade ID          |
| `marketSlug`  | string             | Market slug                         |
| `state`       | string             | Trade state (CLEARED, BUSTED, etc.) |
| `price`       | Amount             | Trade price                         |
| `qty`         | string             | Trade quantity                      |
| `isAggressor` | boolean            | True if user's order was the taker  |
| `costBasis`   | Amount             | Cost basis for the trade            |
| `realizedPnl` | Amount             | Realized profit/loss                |
| `createTime`  | string (date-time) | Creation timestamp                  |
| `updateTime`  | string (date-time) | Last update timestamp               |

### Position Resolution Object

| Field            | Type               | Description                            |
| ---------------- | ------------------ | -------------------------------------- |
| `marketSlug`     | string             | Market slug                            |
| `beforePosition` | UserPosition       | Position before resolution             |
| `afterPosition`  | UserPosition       | Position after resolution              |
| `side`           | string             | Resolution side (LONG, SHORT, NEUTRAL) |
| `tradeId`        | string             | Associated trade ID                    |
| `updateTime`     | string (date-time) | Resolution timestamp                   |

### Account Balance Change Object

| Field           | Type               | Description                           |
| --------------- | ------------------ | ------------------------------------- |
| `transactionId` | string             | Transaction ID                        |
| `status`        | string             | Status (PENDING, COMPLETED, REJECTED) |
| `amount`        | Amount             | Amount of the balance change          |
| `createTime`    | string (date-time) | Creation timestamp                    |
| `updateTime`    | string (date-time) | Last update timestamp                 |

## Pagination

Both endpoints support cursor-based pagination. Use `cursor` parameter with the `nextCursor` value to fetch the next page. When `eof` is `true`, there are no more results.

<Tip>
  **Real-Time Position Updates**

  For real-time position changes, use the [WebSocket Private Stream](/api-reference/websocket/private) with the `SUBSCRIPTION_TYPE_POSITION` subscription instead of polling.
</Tip>

## Filtering Activities

Filter activities by type and market:

```bash theme={null}
GET /v1/portfolio/activities?types=ACTIVITY_TYPE_TRADE&marketSlug=will-x-happen
```

## Sort Order

Activities can be sorted ascending or descending by time:

| Sort Order              | Description            |
| ----------------------- | ---------------------- |
| `SORT_ORDER_DESCENDING` | Newest first (default) |
| `SORT_ORDER_ASCENDING`  | Oldest first           |