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.

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":

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":

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

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']}")

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.

Venue Reference

Polymarket

Discover markets and submit orders on the Polymarket decentralized prediction market platform.

Kalshi

Discover markets and submit orders on the Kalshi prediction market exchange.