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

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

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

```python theme={"dark"}
# Match by ticker
instrument = client.markets.match(ticker="TRUMP-2024-WIN")
print(instrument)
```

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

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

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

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

```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.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`:

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

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


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