# List open positions

> Your open positions as a point-in-time snapshot, largest position first.

Source: https://docs.stxapp.io/api/rest/account/list-open-positions/

Your open positions as a point-in-time snapshot, largest `position` first. The body is identical to the `all_positions` frame the `positions:{user_id}` WebSocket channel sends on join, so a REST read can seed state that channel `updated_positions` deltas then keep current. This is a snapshot, not a feed: subscribe to the channel to hear about changes. Not paginated: the list is bounded by the markets you hold a live position in, and there is no `cursor`. A market you traded and closed out can appear with `position` `"0.00"` until it settles. Positions are not marked to market.

```http
GET /api/v1/positions
```

Send it with your own demo key: [Try it](/quick-start/?op=positions_get#try-it).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `market_ids` | `query` | string | no | Comma-separated market UUIDs. Returns only positions in these markets; an id you hold no position in matches nothing. Omit for every open position. |

## Responses

| Status | Description | Schema |
|---|---|---|
| `200` | Success | object |
| `400` | A parameter was missing or invalid. | Error |
| `401` | Missing, malformed or unrecognized signature, or a timestamp outside the 30-second window. Body: {"error":"Missing or invalid API key credentials"} | Error |
| `403` | The account behind this key is not active, for example it is pending approval or suspended. Body: {"error":"Your account is suspended. Contact support."}, the message naming the account's status. | Error |

## Example

Request:

```bash
curl --request GET \
  --url 'https://demo.stxapp.io/api/v1/positions' \
  --header 'X-STX-ACCESS-KEY: <key-id>' \
  --header 'X-STX-ACCESS-TIMESTAMP: <unix-ms>' \
  --header 'X-STX-ACCESS-SIGNATURE: <base64-ed25519>'
```

Response `200`:

```json
{
  "positions": [
    {
      "account_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "average_open_premium": "0.6700",
      "buy_order_liability": "0.6700",
      "contracts_settled": "2.00",
      "event_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "gross_pnl": "0.6700",
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "market_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "max_potential_fee": "0.6700",
      "max_potential_profit": "0.6700",
      "max_risk": "0.6700",
      "open_potential_fee": "0.6700",
      "open_potential_profit": "0.6700",
      "open_risk": "0.6700",
      "position": "2.00",
      "position_premium_liability": "0.6700",
      "premium": "0.6700",
      "sell_order_liability": "0.6700",
      "total_fee": "0.6700",
      "total_settlement_pnl": "0.6700"
    }
  ]
}
```

### Response fields

| Field | Type | Description |
|---|---|---|
| `account_id` | uuid | The account the position belongs to. |
| `average_open_premium` | decimal | Average premium per contract for the open portion. In dollars. |
| `buy_order_liability` | decimal | Liability from your open buy orders on this market. In dollars. |
| `contracts_settled` | decimal | Contracts settled in the position so far. |
| `event_id` | uuid | The event the market belongs to. |
| `gross_pnl` | decimal | `total_settlement_pnl` plus any pending-close profit or loss that has not settled yet. In dollars. |
| `id` | uuid | The unique id of the position record. |
| `market_id` | uuid | The market the position is on. |
| `max_potential_fee` | decimal | Total potential fee across the position's settlements. In dollars. |
| `max_potential_profit` | decimal | Total possible profit for the position if everything settles favorably. In dollars. |
| `max_risk` | decimal | Account-level risk on the position, netting in already settled profit and loss. In dollars. |
| `open_potential_fee` | decimal | Potential fee on the open contracts when they settle. In dollars. |
| `open_potential_profit` | decimal | Possible profit on the position's open contracts. In dollars. |
| `open_risk` | decimal | Risk on the position's open (unsettled) contracts. In dollars. |
| `position` | decimal | Net position in the market: positive if long (bought), negative if short (sold). Can be `"0.00"` for a market you have traded and closed out that has not settled yet. In contracts. |
| `position_premium_liability` | decimal | Liability from the position's premium that counts against available balance. Routinely negative. In dollars. |
| `premium` | decimal | Total premium paid or received for the open portion of the position. In dollars. |
| `sell_order_liability` | decimal | Liability from your open sell orders on this market. In dollars. |
| `total_fee` | decimal | Total fees paid across the position's settlements. In dollars. |
| `total_settlement_pnl` | decimal | Profit or loss realized from settlements so far. In dollars. |