# Optimizing latency

The lowest-latency Mosaiq integration uses one socket for order entry and a
second socket for lifecycle events. Keep both connected and keep account
snapshots and market data outside the order-entry loop.

| Path | Purpose | Client key |
| --- | --- | --- |
| [`/v1/exchange/ws`](/api/exchange-websocket) | Place, modify, and cancel | Frame `id` |
| [`/v1/ws`](/api/websocket): `orderUpdates` | Order lifecycle | `cloid` |
| [`/v1/ws`](/api/websocket): `userFills` | Confirmed executions | `fillId` |
| [`/v1/ws`](/api/websocket): `clearinghouseState` | Balances, positions, limits, and constraints | Account snapshot |

:::warning\[Hyperliquid only]
The low-latency path and its measurements are currently validated only for
`venue: "hyperliquid"`. Lighter is supported by the API, but these latency
expectations do not apply to it.
:::

## Order entry

Keep one authenticated `/v1/exchange/ws` connection open:

1. Send one order per frame and pipeline independent frames. Do not wait for
   each response before sending the next frame.
2. Keep at most eight frames in flight. At the limit, Mosaiq stops reading until
   a slot becomes available; it does not reject the ninth frame.
3. Assign every frame a unique, monotonically increasing numeric `id`. Match
   responses by `data.id`; completion order is not guaranteed.
4. Assign every placement a fresh `cloid`: lowercase `0x` followed by 32
   lowercase hexadecimal digits, excluding the all-zero value.
5. Send a dependent cancel or modify on the same connection after its place.
   Mosaiq preserves frame arrival order through the Hyperliquid handoff without
   waiting for the place acknowledgement.
6. Send a WebSocket protocol ping before the 30-second inbound idle timeout.
   Ten seconds is a reasonable interval.

Use batches only when batch semantics are useful. A batch is not atomic, and
its item statuses are aligned with `orders[]`. Separate pipelined frames are
correlated by frame `id`.

See the [write WebSocket reference](/api/exchange-websocket) for frame and
response formats. Market constraints and order fields are defined in the
[exchange reference](/api/exchange).

## Lifecycle processing

Keep a separate `/v1/ws` connection subscribed to `orderUpdates` and
`userFills`. Mosaiq checks both streams every 100 ms.

Write responses and lifecycle events are independent. An `orderUpdates` event
can arrive before the matching write response. The client state machine should
therefore:

* key orders by `cloid`;
* key fills by `fillId`;
* accept duplicate observations;
* make every transition idempotent;
* treat a successful write response as an acknowledgement, not fill finality.

`clearinghouseState` is produced every 500 ms. Use it to refresh account state
and market constraints, not to confirm individual orders.

:::note\[Market data is coming]
Mosaiq does not expose order book streams yet. They are planned; until then,
source market data from the feed or node path used by the strategy.
:::

## Disconnect recovery

A dropped connection does not tell you whether the last frame reached Mosaiq.
Do not resend an ambiguous action immediately.

1. Reconnect both sockets with backoff.
2. Consume the new `orderUpdates` and `userFills` snapshots.
3. Query [`GET /v1/openOrders?cloid=<cloid>`](/api/open-orders) for each
   ambiguous order.
4. Reconcile local state before retrying or issuing a replacement action.

Reuse the original `cloid` for reconciliation. A replacement placement needs a
new `cloid`.

## Network placement

Measure round-trip time from the host that will run the strategy. Reuse
established sockets so DNS, TCP, TLS, and authentication stay outside the
per-order path.

Private VPC peering is available during onboarding for latency-sensitive
traders. Confirm availability and network details with Mosaiq before depending
on a private endpoint.

## Production checklist

* Track outstanding frame IDs, order state by `cloid`, and processed `fillId`
  values.
* Reconnect with backoff and rebuild state from snapshots.
* Monitor in-flight frames, write-response latency, disconnects, and ambiguous
  actions from the strategy host.
* Validate venue status, account limits, and market constraints before entering
  the hot path.

Mosaiq does not guarantee a specific latency or trading outcome. Benchmark the
complete client-to-venue path under the workload and network topology used in
production.