GET /v1/fills — Query Subaccount Execution Fill Records

A fill record is created each time one of your orders executes against the book, in whole or in part. Call client.portfolio.fills() to retrieve the complete fill history for a subaccount, giving you a granular audit trail of every execution including instrument, side, price, quantity, and timestamp. This data underpins your trade reconciliation, PnL attribution, and post-trade reporting workflows.

Method

client.portfolio.fills(subaccount_id=None)

Endpoint: GET /v1/fills

Example

from molecule import Molecule

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

fills = client.portfolio.fills(subaccount_id="sa_abc123")

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

Parameters

string

The subaccount whose fill history to retrieve. Omit to retrieve fills across all subaccounts associated with your key.

Response

The endpoint returns a list of fill objects. Common fields:

string

Unique fill identifier.

string

The Molecule order ID that generated this fill.

integer

The venue-specific instrument that was executed.

"BUY" | "SELL"

Direction of the fill.

string

Execution price as a decimal string.

string

Executed quantity as a decimal string.

string

ISO 8601 timestamp of the fill event.

Accessing fills via the orders namespace

The same GET /v1/fills endpoint is also accessible as client.orders.fills(subaccount_id). Both methods call the same endpoint with the same parameters. Use whichever namespace fits your code organisation — portfolio.fills for post-trade analysis, orders.fills when working alongside order lifecycle methods.

# Equivalent to client.portfolio.fills(subaccount_id="sa_abc123")
fills = client.orders.fills(subaccount_id="sa_abc123")

Real-time fills

Subscribe to the /v1/ws/fills WebSocket stream to receive fill events as they occur, rather than polling this REST endpoint. See the WebSocket overview for connection details.

⌘I

Python SDK

Markets

Orders

Portfolio

WebSockets

GET /v1/fills — Query Subaccount Execution Fill Records

Method

Example

Parameters

Response

Accessing fills via the orders namespace

Real-time fills

​Method

​Example

​Parameters

​Response

​Accessing fills via the orders namespace

​Real-time fills

Method

Example

Parameters

Response

Accessing fills via the orders namespace

Real-time fills