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

# Kalshi on Molecule: Discover Markets and Submit Orders

> Kalshi is a prediction market exchange. Access Kalshi instruments and submit orders via the Molecule API using venue="Kalshi" in market queries.

Kalshi is a prediction market exchange offering event contracts. Molecule connects to Kalshi as a live execution venue, enabling you to discover Kalshi instruments, retrieve market data, and submit orders without building a separate Kalshi integration. The same authentication, signing, and order-management flow you use across the Molecule API applies here.

## Discovering Kalshi Markets

Use `client.markets.search()` with `venue="Kalshi"` to retrieve available Kalshi instruments. Filter by `status` or keyword to narrow results.

```python theme={"dark"}
from molecule import Molecule

client = Molecule(
    base_url="https://api.molecule.markets",
    key_id="your-key-id",
    private_key="your-private-key",
)

# Search all active Kalshi markets
markets = client.markets.search(venue="Kalshi", status="active")
for market in markets.get("results", []):
    print(market["instrument_id"], market["ticker"], market["outcome"])
```

Use `client.markets.match()` to look up a specific Kalshi market by ticker or slug when you already know its identifier:

```python theme={"dark"}
# Match by ticker
instrument = client.markets.match(ticker="KXBTC-23DEC31-T30000")
print(instrument)
```

Kalshi markets trade binary YES/NO contracts. Each market produces a YES instrument and a NO instrument, each with its own `instrument_id`. Both instruments share a common `generic_asset_id` that you can use for cross-venue routing.

You can inspect the live order book for a specific Kalshi instrument or retrieve the aggregated view across all venues:

```python theme={"dark"}
# Single-instrument order book
book = client.markets.orderbook(instrument_id=12345)
print(book)

# Aggregated order book across all venues for a given asset
agg_book = client.markets.generic_asset_orderbook(generic_asset_id=42)
print(agg_book)
```

## Submitting Orders to Kalshi

### DIRECT routing to Kalshi

Use `routing.mode = "DIRECT"` with a Kalshi `instrument_id` to route an order to a specific Kalshi contract. Retrieve the `instrument_id` from a prior `search()` or `match()` call.

```python theme={"dark"}
# Place a limit buy order for YES on a specific Kalshi instrument
order = client.orders.create(
    subaccount_id="sub_abc123",
    instrument_id=12345,          # Kalshi YES instrument
    side="BUY",
    outcome="YES",
    type="LIMIT",
    tif="GTC",
    price="0.45",
    qty="150",
    routing={"mode": "DIRECT"},
    client_order_id="kal-direct-001",
)
print(order)
```

### Cross-venue routing with BEST\_PRICE

Use `routing.mode = "BEST_PRICE"` with a `generic_asset_id` to let Molecule select whichever connected venue — including Kalshi — currently offers the best available price for the asset.

```python theme={"dark"}
# Route to the venue with the best available price
order = client.orders.create(
    subaccount_id="sub_abc123",
    generic_asset_id=42,          # cross-venue asset identifier
    side="BUY",
    outcome="YES",
    type="LIMIT",
    tif="GTC",
    price="0.45",
    qty="150",
    routing={"mode": "BEST_PRICE"},
    client_order_id="kal-bestprice-001",
)
print(order)
```

To distribute a larger order across Kalshi and other venues simultaneously, use `SPLIT`:

```python theme={"dark"}
# Split the order across all venues with available liquidity
order = client.orders.create(
    subaccount_id="sub_abc123",
    generic_asset_id=42,
    side="BUY",
    outcome="YES",
    type="LIMIT",
    tif="GTC",
    price="0.45",
    qty="400",
    routing={"mode": "SPLIT"},
    client_order_id="kal-split-001",
)
print(order)
```

## Notes

* Kalshi instruments require a venue-specific `instrument_id` for `DIRECT` routing. Retrieve this from `client.markets.search(venue="Kalshi")` or `client.markets.match()`.
* To route across Kalshi and other connected venues without targeting a specific instrument, use `generic_asset_id` with `BEST_PRICE` or `SPLIT` routing mode.
* Each binary Kalshi market produces two separate instruments (YES and NO). Confirm the `outcome` field on the instrument before submitting a `DIRECT` order to ensure you are trading the intended side.
* The `client_order_id` field acts as the idempotency key for simple orders. Resubmitting the same `client_order_id` with an identical payload is safe; resubmitting with a different payload returns a `ConflictError`.

<Note>
  Use the **Demo** venue to validate your integration before sending orders to
  live Kalshi. Demo provides the same API surface without live execution risk.
  Switch to Kalshi by changing `venue="Kalshi"` in your market queries and
  using a Kalshi `instrument_id` or a `generic_asset_id` that maps to Kalshi
  instruments.
</Note>


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