Manage Positions, Balances, and Risk with Molecule

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.

Overview

Authentication

Guides

Venues

Security

Manage Positions, Balances, and Risk with Molecule

Positions

Balances

Fills

PnL

Current PnL

PnL History

Fair Values

Fees

Fee Schedule

Per-Instrument Fees

Risk Management

Risk State

Risk Limits

Cancel All Orders (Risk)

Kill Switch

​Positions

​Balances

​Fills

​PnL

​Current PnL

​PnL History

​Fair Values

​Fees

​Fee Schedule

​Per-Instrument Fees

​Risk Management

​Risk State

​Risk Limits

​Cancel All Orders (Risk)

​Kill Switch

Positions

Balances

Fills

PnL

Current PnL

PnL History

Fair Values

Fees

Fee Schedule

Per-Instrument Fees

Risk Management

Risk State

Risk Limits

Cancel All Orders (Risk)

Kill Switch