> For the complete documentation index, see [llms.txt](https://k4k3ru.gitbook.io/k4k3ru-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://k4k3ru.gitbook.io/k4k3ru-docs/api/market-hub/spread-subscribe.md).

# Subscribe to Cross-Market Spread Data

`MarketHub.Spread.Subscribe` creates an authenticated WebSocket subscription for gross cross-market spread evaluations. Order-book markets use VWAP for the requested quantity; AMMs use each pool's latest mid. Use `MarketHub.Spread.Unsubscribe` with the same normalized parameters to remove it.

## Subscribe

```json
{
  "id": "1",
  "method": "MarketHub.Spread.Subscribe",
  "params": {
    "symbol": "BTC/USDC",
    "baseAsset": "BTC",
    "quantity": "0.1",
    "minimumGrossSpreadBps": "0",
    "maxAgeSeconds": 30
  },
  "auth": {
    "apiKey": "YOUR_API_KEY",
    "timestamp": 1788533857,
    "nonce": "UNIQUE_NONCE",
    "signature": "REQUEST_SIGNATURE"
  }
}
```

The acknowledgement returns normalized parameters. Subsequent `sp` events contain the compact result fields documented by [Get a Cross-Market Spread Snapshot](/k4k3ru-docs/api/market-hub/get-spread-snapshot.md). OrderBook, BBO and common AMMPool updates affecting the symbol trigger reevaluation. Retained quantity-calculator updates alone do not trigger Spread pricing.

Market updates arriving within a 100 millisecond window are coalesced to the latest state. An `sp` event is emitted only when the eligible routes or their economic values change; source timestamps, book versions, and evaluation timestamps alone do not trigger another event. When the final eligible route disappears, one result with an empty `er` is emitted so consumers can invalidate the previous opportunity.

The service applies source-aware freshness windows to account for normal publication cadence while still excluding stale books. Counts such as `emc`, `erc`, and `prc` can change when a source becomes unavailable. A route crossing below `minimumGrossSpreadBps` is an economic state change and therefore emits an updated result, including an empty `er` when no route remains.

`maxAgeSeconds` limits AMM price receipt age only. Omitted or zero defaults to 5 seconds; a positive value can be at most 4294967295. Order-book markets retain their existing 5-second limit, or 10 seconds for Hyperliquid. Expiry is reevaluated locally once per second even when no market event arrives. This timer does not call RPC endpoints or refresh observation timestamps. Different normalized age limits identify separate subscriptions, and each result echoes `maxAgeSeconds`.

Spread events are derived market-data signals, not execution instructions. In particular, `perp-spot` requires Spot inventory or margin borrowing and does not by itself guarantee a delta-neutral position.

## Unsubscribe

```json
{
  "id": "2",
  "method": "MarketHub.Spread.Unsubscribe",
  "params": {
    "symbol": "BTC/USDC",
    "baseAsset": "BTC",
    "quantity": "0.1",
    "minimumGrossSpreadBps": "0",
    "maxAgeSeconds": 30
  },
  "auth": {
    "apiKey": "YOUR_API_KEY",
    "timestamp": 1788533860,
    "nonce": "ANOTHER_UNIQUE_NONCE",
    "signature": "REQUEST_SIGNATURE"
  }
}
```

Subscribe and Unsubscribe require valid signed WebSocket requests. Unsubscribe parameters must identify the same normalized subscription, including route families, `sourceFilter` and `maxAgeSeconds`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://k4k3ru.gitbook.io/k4k3ru-docs/api/market-hub/spread-subscribe.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.