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

# Wallet Positions

> Get all positions for a wallet with market context, current prices, unrealized P&L, and settlement status.

Returns every position a wallet has ever held, enriched with market metadata, live token prices, computed unrealized P\&L, settlement status, and redemption data. All amounts are in USD.

## Request

```
GET /v3/wallets/{address}/positions
```

### Path parameters

| Parameter | Type   | Description                                    |
| --------- | ------ | ---------------------------------------------- |
| `address` | string | Wallet address (0x-prefixed, case-insensitive) |

### Query parameters

| Parameter        | Type    | Default        | Description                                                                                                                      |
| ---------------- | ------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `status`         | string  | all            | Filter: `open`, `closed`, `redeemable`, `redeemed`                                                                               |
| `sort`           | string  | `realized_pnl` | Sort by: `realized_pnl` (default), `amount` (current shares), `volume` / `total_bought`, `avg_price`, `recent` (last trade time) |
| `order`          | string  | `desc`         | Sort direction: `asc` or `desc`                                                                                                  |
| `condition_id`   | string  | --             | Filter by market condition ID                                                                                                    |
| `market_slug`    | string  | --             | Filter by market slug                                                                                                            |
| `min_size`       | number  | --             | Minimum position size in USD (e.g. `min_size=10.0`)                                                                              |
| `include_combos` | boolean | `false`        | Append combo positions to the response. Combo rows have `position_type: "combo"` and include `legs` metadata.                    |
| `limit`          | integer | 100            | Results per page (max 300)                                                                                                       |
| `offset`         | integer | 0              | Pagination offset                                                                                                                |

### Position statuses

Wallet and global position endpoints use lifecycle statuses:

| Status       | Meaning                                                         |
| ------------ | --------------------------------------------------------------- |
| `open`       | Wallet holds shares in an active (unresolved) market            |
| `closed`     | Position fully sold before market resolved                      |
| `redeemable` | Market resolved, wallet still holds shares that can be redeemed |
| `redeemed`   | Market resolved and shares have been redeemed                   |

Market-scoped holder endpoints may use `open`/`closed` differently when explicitly documented as holder-state filters: `open` means the current balance is nonzero, and `closed` means the current balance is zero.

## Examples

### All positions

```bash theme={null}
curl https://api.polynode.dev/v3/wallets/0xa9857c7bcb9bcfafd2c132ab053f34f678610058/positions?limit=1
```

```json theme={null}
{
  "address": "0xa9857c7bcb9bcfafd2c132ab053f34f678610058",
  "positions": [
    {
      "token_id": "56311531524793560667677947517355066819344622894461317832902534277368408457717",
      "size": 0.003332,
      "avg_price": 0.479999,
      "realized_pnl": 0.083202,
      "unrealized_pnl": 0.0,
      "total_pnl": 0.083202,
      "current_price": 0.0,
      "total_bought": 2.083332,
      "initial_value": 0.001599,
      "redeemable_payout": 0.0,
      "resolved": true,
      "price_source": "settlement",
      "status": "redeemable",
      "market": "Bitcoin Up or Down - May 13, 6:55AM-7:00AM ET",
      "slug": "btc-updown-5m-1778669700",
      "outcome": "Down",
      "outcome_index": 1,
      "opposite_asset": "75458928898922591833639657019011228747535375591777673334858165385124723756977",
      "image": "https://polymarket-upload.s3.us-east-2.amazonaws.com/BTC+fullsize.png",
      "condition_id": "0xa1118bf183058190b9b47529d94eed53d0210c65531990019c09b893cb64b73b",
      "event_slug": "btc-updown-5m-1778669700",
      "neg_risk": false,
      "market_status": "live",
      "tag_slugs": ["Hide From New", "Recurring", "Up or Down", "Crypto Prices", "Crypto", "Bitcoin", "5M"],
      "last_trade_at": "1778670064",
      "resolved_at": "0",
      "winning_outcome_index": null,
      "won": null
    }
  ],
  "rows_returned": 1,
  "has_more": true,
  "offset": 0,
  "limit": 1,
  "elapsed_ms": 45
}
```

### Only open positions

```bash theme={null}
curl https://api.polynode.dev/v3/wallets/0x.../positions?status=open
```

### Only redeemable (resolved but not yet claimed)

```bash theme={null}
curl https://api.polynode.dev/v3/wallets/0x.../positions?status=redeemable
```

The `redeemable_payout` field shows the exact USD amount the wallet can claim.

### Sort by most recent trade

```bash theme={null}
curl "https://api.polynode.dev/v3/wallets/0x.../positions?sort=recent"
```

### Sort by current position size

```bash theme={null}
curl "https://api.polynode.dev/v3/wallets/0x.../positions?sort=amount"
```

### Include combo positions

```bash theme={null}
curl "https://api.polynode.dev/v3/wallets/0x63613e3b96f418332d43cd2af8dc321014d15907/positions?include_combos=true&limit=2"
```

When combo rows are present, they are appended with `position_type: "combo"` and a combo-specific field set:

```json theme={null}
{
  "position_type": "combo",
  "combo_condition_id": "0x030002fa8781d9f445d838e60524d70bf30000000000000000000000000000",
  "combo_position_id": "1356959103499736670017337806334234879289930581423500836189165811753797287936",
  "shares_balance": "0.000100",
  "entry_avg_price_usdc": "0.2285",
  "entry_cost_usdc": "0.00",
  "realized_pnl_usdc": "0.000000",
  "total_pnl_usdc": "0.000000",
  "status": "open",
  "legs": [
    {
      "leg_index": 0,
      "leg_position_id": "943244391856361009754982642766252708422485833075867696330382296106234020352",
      "leg_outcome_label": "Yes",
      "leg_status": "OPEN"
    }
  ]
}
```

## Response fields

### Top-level combo fields

| Field                     | Type    | Description                                                      |
| ------------------------- | ------- | ---------------------------------------------------------------- |
| `include_combos`          | boolean | Present when `include_combos=true` was requested                 |
| `included_position_types` | array   | Includes `market` and `combo` when combo inclusion was requested |
| `combo_position_count`    | integer | Number of combo position rows returned in this page              |

### Position data

| Field               | Type    | Description                                                         |
| ------------------- | ------- | ------------------------------------------------------------------- |
| `token_id`          | string  | Outcome token ID                                                    |
| `size`              | number  | Current shares held in USD (0 if closed/redeemed)                   |
| `avg_price`         | number  | Weighted-average entry price in USD                                 |
| `realized_pnl`      | number  | Realized P\&L from closed trades (USD)                              |
| `unrealized_pnl`    | number  | Paper P\&L: `(current_price - avg_price) * size`                    |
| `total_pnl`         | number  | `realized_pnl + unrealized_pnl`                                     |
| `current_price`     | number  | Latest token price (USD, from settlement, CLOB mid, or last fill)   |
| `total_bought`      | number  | Total USD spent buying this position                                |
| `initial_value`     | number  | `avg_price * size` at current holdings                              |
| `redeemable_payout` | number  | USD claimable if redeemed now (0 for losing outcomes)               |
| `resolved`          | boolean | Whether the market has settled                                      |
| `price_source`      | string  | Price source: `settlement`, `clob_mid`, `v1_condition`, `last_fill` |
| `status`            | string  | `open`, `closed`, `redeemable`, or `redeemed`                       |

### Market context

| Field            | Type    | Description                                          |
| ---------------- | ------- | ---------------------------------------------------- |
| `market`         | string  | Market question text                                 |
| `slug`           | string  | Market URL slug                                      |
| `outcome`        | string  | Outcome label (e.g. "Yes", "No", "Trump")            |
| `outcome_index`  | integer | Outcome position (0 or 1)                            |
| `opposite_asset` | string  | Token ID of the other outcome in this market         |
| `image`          | string  | Market image URL                                     |
| `condition_id`   | string  | Market condition ID                                  |
| `event_slug`     | string  | Parent event slug                                    |
| `neg_risk`       | boolean | Whether this is a neg-risk (multi-outcome) market    |
| `market_status`  | string  | `live`, `closed`, `resolved-win`, or `resolved-loss` |
| `tag_slugs`      | array   | Category tags for this market                        |

### Timestamps and resolution

| Field                   | Type    | Description                                             |
| ----------------------- | ------- | ------------------------------------------------------- |
| `last_trade_at`         | string  | Unix timestamp of the most recent fill for this token   |
| `resolved_at`           | string  | Unix timestamp when the market was resolved             |
| `winning_outcome_index` | integer | Which outcome won (0 or 1), null if unresolved          |
| `won`                   | boolean | Whether this position's outcome won, null if unresolved |

## Use cases

* **Portfolio dashboard** — show a trader's open positions with live P\&L and market context
* **Redemption alerts** — find wallets with unclaimed payouts using `?status=redeemable`
* **Performance analysis** — sort by P\&L to see best and worst positions
* **Copy trading** — see what a wallet is currently holding with `?status=open&sort=amount`