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.

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.

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.

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.

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

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.

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

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

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.

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

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.

state = client.risk.state(subaccount_id="sub_123")
print(state)

Risk Limits

Retrieve the configured risk limits for a subaccount.

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.

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.

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.

# Halt all activity immediately
client.risk.kill_switch(enabled=True)

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

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.