> ## 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.

# Manage Positions, Balances, and Risk with Molecule

> Query open positions, account balances, fill history, realized and unrealized PnL, fees, and configure risk limits using the Molecule portfolio API.

The portfolio API gives you a unified view of your account state across all connected venues. Use it to monitor open positions and available balances, inspect fill history, track realized and unrealized PnL, supply fair-value overrides for mark-to-market calculations, look up fee schedules, and configure or trigger risk controls. All methods are available on the `client.portfolio` and `client.risk` sub-clients.

## Positions

Retrieve all open positions for a subaccount. Each entry includes the instrument, size, side, and average entry price.

Use `client.positions(subaccount_id)` (top-level shortcut) or `client.portfolio.positions(subaccount_id)` — both call `GET /v1/positions`.

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

client = Molecule(
    base_url="https://api.molecule.fi",
    key_id="your-key-id",
    private_key="your-base64-private-key",
)

positions = client.positions(subaccount_id="sub_123")

for pos in positions:
    print(
        pos["instrument_id"],
        pos["side"],
        pos["qty"],
        pos["avg_price"],
    )
```

## Balances

Retrieve the cash balances for a subaccount across all connected venues. The response includes available and total balance breakdowns per venue.

```python theme={"dark"}
balances = client.portfolio.balances(subaccount_id="sub_123")

for b in balances:
    print(b["venue"], b["available"], b["total"])
```

## Fills

Retrieve the fill history for a subaccount. Fills represent individual execution events — each fill records the quantity and price at which an order was matched.

```python theme={"dark"}
fills = client.portfolio.fills(subaccount_id="sub_123")

for fill in fills:
    print(
        fill["order_id"],
        fill["instrument_id"],
        fill["side"],
        fill["qty"],
        fill["price"],
    )
```

## PnL

### Current PnL

Retrieve the current realized and unrealized profit and loss for a subaccount.

```python theme={"dark"}
pnl = client.portfolio.pnl(subaccount_id="sub_123")
print(pnl["realized"], pnl["unrealized"])
```

### PnL History

Retrieve a time series of PnL snapshots. The `limit` parameter controls how many entries are returned (default `200`).

```python theme={"dark"}
history = client.portfolio.pnl_history(subaccount_id="sub_123", limit=100)

for snapshot in history:
    print(snapshot["ts"], snapshot["realized"], snapshot["unrealized"])
```

## Fair Values

Override the mark-to-market prices used for unrealized PnL calculations by supplying your own fair values. This is useful when your internal mid-market model differs from the last traded price.

Call `client.portfolio.set_fair_values(subaccount_id, values)` — `PUT /v1/fair-values`. Pass a list of objects, each containing an `instrument_id` and a `fair_value` string.

```python theme={"dark"}
client.portfolio.set_fair_values(
    subaccount_id="sub_123",
    values=[
        {"instrument_id": 42, "fair_value": "0.51"},
        {"instrument_id": 43, "fair_value": "0.49"},
    ],
)
```

<Info>
  Fair values affect only PnL calculations — they do not influence order routing or execution. Submit updated values whenever your internal model reprices.
</Info>

## Fees

### Fee Schedule

Retrieve the fee schedule for a venue or all venues. Pass `venue=None` (the default) to return schedules for every connected venue.

```python theme={"dark"}
# All venues
all_fees = client.portfolio.fees()

# Fees for a specific venue
kalshi_fees = client.portfolio.fees(venue="Kalshi")
```

### Per-Instrument Fees

Look up the effective fee rates for a specific list of instruments. This is useful before placing large orders when you need precise cost estimates.

```python theme={"dark"}
fees = client.portfolio.lookup_fees(instrument_ids=[4001, 4002, 4003])

for entry in fees:
    print(entry["instrument_id"], entry["maker_fee"], entry["taker_fee"])
```

## Risk Management

The `client.risk` sub-client provides controls that span all order activity on your account. These endpoints require the same Ed25519 credentials as trading operations.

### Risk State

Retrieve the current risk state for a subaccount, including utilization against configured limits.

```python theme={"dark"}
state = client.risk.state(subaccount_id="sub_123")
print(state)
```

### Risk Limits

Retrieve the configured risk limits for a subaccount.

```python theme={"dark"}
limits = client.risk.limits(subaccount_id="sub_123")
print(limits)
```

Update limits with `client.risk.set_limits(**payload)`. The payload fields depend on the limit types your account supports.

```python theme={"dark"}
client.risk.set_limits(
    subaccount_id="sub_123",
    max_open_orders=500,
    max_net_position="10000",
)
```

### Cancel All Orders (Risk)

Cancel all open orders for a subaccount through the risk API. This mirrors `client.orders.cancel_all()` but is scoped to the risk control plane.

```python theme={"dark"}
client.risk.cancel_all(subaccount_id="sub_123")
```

### Kill Switch

Activate the kill switch to immediately halt all order submission and cancel every open order on your account. Deactivate it by calling the same method with `enabled=False`.

```python theme={"dark"}
# Halt all activity immediately
client.risk.kill_switch(enabled=True)

# Resume trading
client.risk.kill_switch(enabled=False)
```

<Warning>
  Activating the kill switch (`enabled=True`) **immediately halts all order submission** and cancels every open order on your account. The account remains locked until you explicitly deactivate the switch with `enabled=False`. Use this only in emergency or automated circuit-breaker scenarios.
</Warning>


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