Quickstart: Install the SDK and Place Your First Order

Install the Molecule Python SDK, configure your signing key, search a market, inspect the order book, and submit your first order in under five minutes.

This guide walks you through installing the Molecule Python SDK, authenticating with an Ed25519 trading key, locating a market on the Demo venue, inspecting its order book, and placing a limit order — all from a Python script. By the end you will have a working client and a confirmed order in the system.

The Demo venue is a paper-trading sandbox that mirrors real venue behavior without executing against live markets. Use it freely to validate your integration before connecting to Polymarket or Kalshi.

1. Install the SDK

   Install the molecule package from PyPI:

   pip install molecule
   

   If the PyPI release is not yet available, install directly from the GitHub repository:

   pip install "molecule @ git+https://github.com/Molecule-Trading/molecule-python-sdk.git"
   

   The SDK requires Python 3.10 or later. It depends on httpx for HTTP transport, PyNaCl for Ed25519 signing, and websockets for WebSocket streaming.

2. Set Environment Variables

   Configure three environment variables before running your code. The SDK reads them automatically if you do not pass the values explicitly to the constructor.

   export MOLECULE_BASE_URL="https://api.molecule.markets"
   export MOLECULE_KEY_ID="your-key-id"
   export MOLECULE_PRIVATE_KEY="base64-encoded-32-byte-ed25519-seed"
   

   Variable	Required	Description
   MOLECULE_BASE_URL	Yes	Base URL of the Molecule API. Provided during onboarding.
   MOLECULE_KEY_ID	For trading	Identifier for your Ed25519 key pair, registered with Molecule.
   MOLECULE_PRIVATE_KEY	For trading	Base64-encoded 32-byte Ed25519 seed. Hex and raw bytes are also accepted.

   Keep your private key in an environment variable or a secrets manager — never commit it to source control or include it as a literal string in your code. The key never leaves your process; Molecule stores only the corresponding public key.

3. Initialize the Client

   Import Molecule and instantiate the client. The constructor reads MOLECULE_BASE_URL, MOLECULE_KEY_ID, and MOLECULE_PRIVATE_KEY from the environment if you omit those arguments.

   import os
   from molecule import Molecule
   
   client = Molecule(
       base_url=os.environ["MOLECULE_BASE_URL"],
       key_id=os.environ["MOLECULE_KEY_ID"],
       private_key=os.environ["MOLECULE_PRIVATE_KEY"],
   )
   

   The client is synchronous. If your application uses asyncio, import AsyncMolecule instead — it exposes the same methods.

   base_url is required. The constructor raises ValueError if it is absent from both the argument and the environment variable.

4. Search a Market

   Use client.search_markets() to run a full-text search across available instruments, or client.markets.match() to resolve a specific ticker or slug to a single instrument record.

   # Full-text search on the Demo venue
   results = client.search_markets(q="house", venue="Demo")
   print(results)
   
   # Resolve a known ticker to an instrument
   instrument = client.markets.match(ticker="FAKE-HOUSE-DEM")
   print(instrument["instrument_id"], instrument["title"])
   

   search_markets() returns a paginated list of instrument objects. markets.match() returns a single instrument object. Both calls are unauthenticated-compatible but will be signed automatically when a trading key is configured.

   Hold on to instrument["instrument_id"] — you will need it for the order book and order submission steps below.

5. Inspect the Order Book

   Fetch the current order book snapshot for an instrument to see resting bids and offers before you place an order.

   instrument_id = instrument["instrument_id"]
   
   book = client.markets.book(instrument_id)
   
   print("Bids:", book.get("bids", [])[:5])
   print("Asks:", book.get("asks", [])[:5])
   

   The response contains bids and asks arrays, each with price and size entries sorted from best to worst. Use this to inform your limit price before submission.

6. Submit an Order

   Place a limit order on the Demo venue using client.create_order(). Supply a client_order_id to make the request idempotent — retrying with the same client_order_id and identical payload is safe and returns the original order rather than creating a duplicate.

   order = client.create_order(
       subaccount_id=os.environ["MOLECULE_SUBACCOUNT_ID"],
       instrument_id=instrument_id,
       side="BUY",
       type="LIMIT",
       tif="GTC",
       price="0.48",
       qty="10",
       routing={"mode": "DIRECT"},
       client_order_id="desk-house-1",
   )
   
   print(order["id"], order["status"])
   

   Field	Value	Description
   subaccount_id	string	Your subaccount on the Molecule platform.
   instrument_id	integer	Venue-specific instrument resolved in the previous step.
   side	"BUY" | "SELL"	Direction of the order.
   type	"LIMIT" | "MARKET"	Order type.
   tif	"GTC" | "IOC" | "FOK" | "GTD"	Time-in-force policy.
   price	decimal string	Limit price. Omit for MARKET orders.
   qty	decimal string	Order quantity.
   routing	object	Routing configuration. DIRECT routes to the specific instrument_id.
   client_order_id	string	Client-supplied idempotency key.

   A routing.mode of "DIRECT" pairs with instrument_id. Use "BEST_PRICE" or "SPLIT" with generic_asset_id to route across venues.

7. Check the Order

   Retrieve the order by its server-assigned ID to confirm its current status.

   order_id = order["id"]
   
   refreshed = client.orders.get(order_id)
   print("Status:", refreshed["status"])
   

   Order status transitions through the following values:

   Status	Meaning
   PENDING_SUBMISSION	Accepted by Molecule, awaiting venue submission.
   OPEN	Resting on the venue order book.
   PARTIAL	Partially filled, remainder resting.
   FILLED	Fully executed.
   CANCELLED	Cancelled by request or venue.
   REJECTED	Rejected by the venue.
   EXPIRED	Expired per time-in-force policy.

   For continuous order updates without polling, subscribe to the /v1/ws/orders WebSocket stream using client.iter_ws("/v1/ws/orders").

Next Steps

Authentication

Understand Ed25519 key provisioning, the signing protocol, and JWT management sessions.

Orders Guide

Explore order types, routing modes, amendments, batch submission, and complex orders.

Market Data

Fetch order books, stream real-time prices, read candles, and subscribe to trade prints.