Polymarket on Molecule: Discover Markets and Submit Orders

Polymarket is a decentralized prediction market platform. Access Polymarket instruments via the Molecule API using venue=“Polymarket” in market queries.

Polymarket is a decentralized prediction market platform. Molecule connects to Polymarket as a first-class execution venue, letting you discover Polymarket instruments, stream live market data, and submit orders using the same API you use for every other connected venue. You do not need a separate Polymarket integration — authentication, signing, and execution flow through the Molecule API.

Discovering Polymarket Markets

Use client.markets.search() with venue="Polymarket" to retrieve a paginated list of available Polymarket instruments. Pass a q string to narrow results by keyword.

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 Polymarket markets
markets = client.markets.search(venue="Polymarket", 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 market by ticker or slug when you already know its identifier:

# Match by ticker
instrument = client.markets.match(ticker="TRUMP-2024-WIN")
print(instrument)

Each Polymarket binary market exposes two instruments — one for the YES outcome and one for the NO outcome. Both instruments share the same generic_asset_id but have distinct instrument_id values. When submitting a DIRECT order, specify the instrument_id that corresponds to the outcome you want to trade.

You can also fetch the aggregated order book across all venues for a given asset using the generic_asset_id:

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

Submitting Orders to Polymarket

DIRECT routing to Polymarket

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

# Place a limit buy order for YES on a specific Polymarket instrument
order = client.orders.create(
    subaccount_id="sub_abc123",
    instrument_id=98765,          # Polymarket YES instrument
    side="BUY",
    outcome="YES",
    type="LIMIT",
    tif="GTC",
    price="0.58",
    qty="200",
    routing={"mode": "DIRECT"},
    client_order_id="pm-direct-001",
)
print(order)

Cross-venue routing with BEST_PRICE

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

# 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.58",
    qty="200",
    routing={"mode": "BEST_PRICE"},
    client_order_id="pm-bestprice-001",
)
print(order)

You can also split a larger order across Polymarket and other venues simultaneously using SPLIT:

# 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.58",
    qty="500",
    routing={"mode": "SPLIT"},
    client_order_id="pm-split-001",
)
print(order)

Notes

• Polymarket instruments require a venue-specific instrument_id for DIRECT routing. Retrieve this from client.markets.search(venue="Polymarket") or client.markets.match().
• To route across Polymarket and other connected venues without targeting a specific instrument, use generic_asset_id with BEST_PRICE or SPLIT routing mode.
• Each binary Polymarket market produces two separate instruments (YES and NO). Confirm the outcome field on the instrument matches the side you intend to trade before submitting a DIRECT order.
• 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.

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