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

# GET /v1/positions — Query Subaccount Open Positions

> Retrieve open positions for a subaccount. Returns instrument holdings with size, cost basis, and unrealized PnL. Endpoint: GET /v1/positions.

Call `client.portfolio.positions()` or its top-level shortcut `client.positions()` to retrieve all open positions held by a subaccount. The response contains one record per instrument with details about the current holding size, average entry cost, and unrealized profit and loss. Use this endpoint to monitor exposure across the prediction markets your subaccount is active in.

## Method

```
client.portfolio.positions(subaccount_id)
client.positions(subaccount_id)   # shortcut
```

**Endpoint:** `GET /v1/positions`

## Example

```python theme={"dark"}
from molecule import Molecule

client = Molecule(
    base_url="https://api.molecule.trade",
    key_id="key_abc123",
    private_key="<base64-encoded-ed25519-seed>",
)

subaccount_id = "sa_abc123"

positions = client.positions(subaccount_id=subaccount_id)

for pos in positions:
    print(pos)
```

## Parameters

<ParamField query="subaccount_id" type="string" required>
  The subaccount whose open positions to retrieve.
</ParamField>

## Response

The endpoint returns a list of position objects, one per instrument with a non-zero holding. Common fields:

<ResponseField name="instrument_id" type="integer">
  The venue-specific instrument identifier.
</ResponseField>

<ResponseField name="side" type="&#x22;BUY&#x22; | &#x22;SELL&#x22;">
  Direction of the position.
</ResponseField>

<ResponseField name="qty" type="string">
  Current open quantity as a decimal string.
</ResponseField>

<ResponseField name="avg_price" type="string">
  Average entry price (cost basis) as a decimal string.
</ResponseField>

<ResponseField name="unrealized_pnl" type="string">
  Mark-to-market unrealized profit and loss as a decimal string.
</ResponseField>

## Notes

<Tip>
  To monitor position changes in real time, subscribe to the `/v1/ws/positions` WebSocket stream. See the [WebSocket overview](/api/websockets/overview) for connection details.
</Tip>

<Note>
  Positions reflect holdings at the subaccount level. If you operate multiple subaccounts, call this endpoint once per subaccount to get a full portfolio view.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.