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

# Molecule Venue Overview: Prediction Market Connections

> Molecule connects to multiple prediction market venues through a single API. Each venue has its own instruments, settlement rules, and market structure.

Molecule aggregates multiple prediction market venues behind a single authenticated API. Rather than integrating each venue's native API separately, you discover markets, submit orders, and manage positions through one consistent interface. Molecule normalises instrument identifiers, order semantics, and market data across venues so that the same order-submission code works regardless of the underlying execution venue.

## Live Venues

The following venues are live and available for order submission:

| Name | Status | Description |
| - | - | - |
| **Demo** | Live | Sandbox venue for testing. Safe for integration and development without live execution risk. |
| **Polymarket** | Live | Decentralized prediction market platform. |
| **Kalshi** | Live | Prediction market exchange offering event contracts. |

## Routing Across Venues

Molecule exposes two identifier types that control how orders are routed:

* **`instrument_id`** — A venue-specific instrument identifier. Use this with `routing.mode = "DIRECT"` to send an order to a specific instrument on a specific venue. You must know the exact instrument before submitting.
* **`generic_asset_id`** — A cross-venue asset identifier. Use this with `routing.mode = "BEST_PRICE"` or `routing.mode = "SPLIT"` to let Molecule find the best available price across venues, or to split a larger order across multiple venues simultaneously.

Use `client.markets.venues()` to retrieve the list of connected venues, and `client.markets.venue_health()` to inspect their current connectivity status.

```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",
)

# List all connected venues
venues = client.markets.venues()
print(venues)

# Check real-time venue health
health = client.markets.venue_health()
print(health)
```

### DIRECT routing

Route an order to a specific venue instrument by passing `instrument_id` and setting `routing.mode` to `"DIRECT"`:

```python theme={"dark"}
order = client.orders.create(
    subaccount_id="sub_abc123",
    instrument_id=98765,          # venue-specific instrument
    side="BUY",
    outcome="YES",
    type="LIMIT",
    tif="GTC",
    price="0.62",
    qty="100",
    routing={"mode": "DIRECT"},
    client_order_id="order-direct-001",
)
```

### BEST\_PRICE and SPLIT routing

Route an order across venues by passing `generic_asset_id` and setting `routing.mode` to `"BEST_PRICE"` or `"SPLIT"`:

```python theme={"dark"}
# Best price — fills at the single venue offering 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.62",
    qty="100",
    routing={"mode": "BEST_PRICE"},
    client_order_id="order-bestprice-001",
)

# Split — distributes 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.62",
    qty="100",
    routing={"mode": "SPLIT"},
    client_order_id="order-split-001",
)
```

## Venue Health

Before submitting orders, check that the target venue is reachable. If a venue is unavailable and you attempt to route to it, the API returns a `RoutingUnavailableError`.

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

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

health = client.markets.venue_health()

# health is a dict keyed by venue name, e.g.:
# {
#   "Polymarket": {"status": "ok", "latency_ms": 12},
#   "Kalshi":     {"status": "ok", "latency_ms": 8},
#   "Demo":       {"status": "ok", "latency_ms": 3},
# }

for venue, status in health.items():
    print(f"{venue}: {status['status']}")
```

<Warning>
  If `venue_health()` reports a venue as degraded or unreachable, orders routed
  directly to that venue will fail with `RoutingUnavailableError`. Use
  `BEST_PRICE` or `SPLIT` routing with a `generic_asset_id` to automatically
  avoid unavailable venues.
</Warning>

## Venue Reference

<CardGroup cols={2}>
  <Card title="Polymarket" icon="circle-nodes" href="/venues/polymarket">
    Discover markets and submit orders on the Polymarket decentralized
    prediction market platform.
  </Card>

  <Card title="Kalshi" icon="landmark" href="/venues/kalshi">
    Discover markets and submit orders on the Kalshi prediction market
    exchange.
  </Card>
</CardGroup>


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