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

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

<Note>
  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.
</Note>

<Steps>
  <Step title="Install the SDK">
    Install the `molecule` package from PyPI:

    ```bash theme={"dark"}
    pip install molecule
    ```

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

    ```bash theme={"dark"}
    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.
  </Step>

  <Step title="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.

    ```bash theme={"dark"}
    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. |

    <Note>
      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.
    </Note>
  </Step>

  <Step title="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.

    ```python theme={"dark"}
    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.
  </Step>

  <Step title="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.

    ```python theme={"dark"}
    # 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.
  </Step>

  <Step title="Inspect the Order Book">
    Fetch the current order book snapshot for an instrument to see resting bids and offers before you place an order.

    ```python theme={"dark"}
    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.
  </Step>

  <Step title="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.

    ```python theme={"dark"}
    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.
  </Step>

  <Step title="Check the Order">
    Retrieve the order by its server-assigned ID to confirm its current status.

    ```python theme={"dark"}
    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")`.
  </Step>
</Steps>

## Next Steps

<CardGroup cols={3}>
  <Card title="Authentication" icon="key" href="/authentication/overview">
    Understand Ed25519 key provisioning, the signing protocol, and JWT management sessions.
  </Card>

  <Card title="Orders Guide" icon="arrow-right-arrow-left" href="/guides/orders">
    Explore order types, routing modes, amendments, batch submission, and complex orders.
  </Card>

  <Card title="Market Data" icon="chart-line" href="/guides/market-data">
    Fetch order books, stream real-time prices, read candles, and subscribe to trade prints.
  </Card>
</CardGroup>


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