> ## Documentation Index
> Fetch the complete documentation index at: https://mathematicalcompany.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Cross-Venue Liquidity

> Aggregate orderbooks across exchanges. Smart order routing, best venue selection, and cross-venue market making.

<Warning>
  **Ultra Feature.** Requires an Ultra subscription. [Get started at api.mathematicalcompany.com](https://api.mathematicalcompany.com)
</Warning>

# Cross-Venue Liquidity

The same prediction can trade on Polymarket, Kalshi, and other platforms at different prices. Horizon's liquidity aggregation module merges orderbooks from multiple venues into a unified view, routes orders to the best venue, and enables cross-venue market making. All aggregation math is in Rust.

## Overview

<CardGroup cols={2}>
  <Card title="Book Aggregation" icon="layer-group">
    `hz.aggregate_books()` merges bid/ask levels from multiple venues.
  </Card>

  <Card title="Smart Routing" icon="route">
    `hz.smart_route()` picks the best venue for a given order.
  </Card>

  <Card title="Best Venue" icon="trophy">
    `hz.best_venue()` returns the venue with the best price for a side.
  </Card>

  <Card title="Cross-Venue MM" icon="arrows-left-right">
    `hz.cross_venue_mm()` market-makes using the aggregated book.
  </Card>
</CardGroup>

***

## Core Functions

### hz.aggregate\_books

Merge bid/ask levels from multiple venues into a unified orderbook.

```python theme={null}
import horizon as hz

book = hz.aggregate_books(
    bids=[("polymarket", 0.55, 1000), ("kalshi", 0.54, 500)],
    asks=[("polymarket", 0.57, 800), ("kalshi", 0.56, 600)],
)
print(f"Best bid: {book.best_bid} | Best ask: {book.best_ask}")
print(f"Mid: {book.mid_price:.4f}")
print(f"Bid depth: {book.total_bid_size} | Ask depth: {book.total_ask_size}")
```

| Parameter | Type                             | Description                 |
| --------- | -------------------------------- | --------------------------- |
| `bids`    | `list[tuple[str, float, float]]` | (venue, price, size) tuples |
| `asks`    | `list[tuple[str, float, float]]` | (venue, price, size) tuples |

Returns an `AggregatedBook` with fields: `bids`, `asks`, `best_bid`, `best_ask`, `mid_price`, `total_bid_size`, `total_ask_size`.

### hz.smart\_route

Route an order to the venue(s) offering best execution.

```python theme={null}
decision = hz.smart_route(book, side="buy", size=500.0)
print(f"Route to: {decision.venue} at {decision.price}")
print(f"Expected cost: {decision.expected_cost:.2f}")
for fill in decision.fills_across_venues:
    print(f"  {fill[0]}: {fill[2]} @ {fill[1]}")
```

| Parameter | Type             | Description          |
| --------- | ---------------- | -------------------- |
| `book`    | `AggregatedBook` | Aggregated orderbook |
| `side`    | `str`            | `"buy"` or `"sell"`  |
| `size`    | `float`          | Order size           |

### hz.best\_venue

Return the venue with the best price for a given side.

```python theme={null}
venue, price = hz.best_venue(book, "buy")
print(f"Best venue to buy: {venue} at {price}")
```

### hz.merged\_mid\_price

Compute the size-weighted mid price across venues.

```python theme={null}
mid = hz.merged_mid_price(book)
```

***

## Pipeline Functions

### hz.aggregate\_book

Aggregate orderbooks from multiple venue feeds each cycle.

```python theme={null}
agg = hz.aggregate_book(
    venue_feeds={
        "polymarket": {"bid_feed": "poly_book"},
        "kalshi": {"bid_feed": "kalshi_book"},
    },
)
```

| Parameter     | Type                        | Description                                |
| ------------- | --------------------------- | ------------------------------------------ |
| `venue_feeds` | `dict[str, dict[str, str]]` | venue to `{"bid_feed": feed_name}` mapping |

Returns each cycle:

```python theme={null}
{
    "best_bid": 0.55,
    "best_ask": 0.57,
    "mid_price": 0.56,
    "spread": 0.02,
    "bid_depth": 1500.0,
    "ask_depth": 1400.0,
}
```

### hz.smart\_route\_pipeline

Smart order routing each cycle.

```python theme={null}
router = hz.smart_route_pipeline(
    venue_feeds={...},
    default_size=100.0,
)
```

### hz.cross\_venue\_mm

Market-make using the aggregated book. Quotes around the merged mid price.

```python theme={null}
mm = hz.cross_venue_mm(
    venue_feeds={
        "polymarket": {"bid_feed": "poly_book"},
        "kalshi": {"bid_feed": "kalshi_book"},
    },
    spread_markup=0.01,
    size=50.0,
)
```

| Parameter       | Type              | Default  | Description              |
| --------------- | ----------------- | -------- | ------------------------ |
| `venue_feeds`   | `dict[str, dict]` | required | Venue feed configuration |
| `spread_markup` | `float`           | `0.01`   | Spread around mid        |
| `size`          | `float`           | `50.0`   | Quote size per side      |

***

## Examples

### Cross-Venue Arbitrage

```python theme={null}
import horizon as hz

def arb_strategy(ctx):
    best_bid = ctx.params.get("best_bid", 0)
    best_ask = ctx.params.get("best_ask", 0)
    spread = best_ask - best_bid
    if spread < 0:  # crossed book = arb
        return [
            hz.order(side="buy", price=best_ask, size=50),
            hz.order(side="sell", price=best_bid, size=50),
        ]
    return []

hz.run(
    name="cross_venue_arb",
    exchange=[hz.Polymarket(), hz.Kalshi()],
    feeds={
        "poly_book": hz.PolymarketBook("will-btc-hit-100k"),
        "kalshi_book": hz.KalshiBook("KXBTC-25DEC31"),
    },
    pipeline=[
        hz.aggregate_book(venue_feeds={
            "polymarket": {"bid_feed": "poly_book"},
            "kalshi": {"bid_feed": "kalshi_book"},
        }),
        arb_strategy,
    ],
)
```