Unified Stream

Overview

The Unified Stream provides a pre-decoded event feed via Server-Sent Events (SSE). It combines HyperCore and HyperEVM events into a single, multiplexed stream with tiered access control, delivering institutional-grade market microstructure data with sub-millisecond ingest-to-publish latency.

The sidecar decodes HyperCore RawAction limit-order payloads for liquidation events and emits derived liquidation_cascade signals when rolling-window statistical thresholds are met.

Unified Stream Pipeline

Regional Endpoints

Region	Base URL
US (East US 2)	`https://unified.grpc.aleatoric.systems`
JP (Japan East)	`https://unified-jp.grpc.aleatoric.systems`

Dashboard clients must connect via the engine proxy at https://mcp.aleatoric.systems/api/v1/unified/*, which validates session tokens and forwards requests to the hypernode with a service key. The direct unified.grpc.aleatoric.systems endpoints are for SDK/bot consumers using provisioned API keys — they do not accept session tokens and will return 401 if accessed from the browser dashboard.

Use the JP hostname when your account includes Japan East access.

Authentication

All endpoints except /healthz require a valid API key passed via the Authorization header:

Authorization: Bearer <your-api-key>

See the Authentication guide for key provisioning and management.

Tier Limits

Tier	Requests per Minute	Requests per Second	SSE Connections
Basic	100	2	1
Pro	120,000	200	10
Quant	Unlimited	Unlimited	Unlimited

Rate limit headers are returned on every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1710360000

Latency Target

The Unified Stream targets $500\,\mu\text{s}$ event delivery latency from ingest to publish. The /api/v1/unified/stats endpoint reports observed percentile distributions so consumers can monitor delivery performance against this target.

API Reference

Health Check

Returns service health status. No authentication required.

GET /healthz

Parameter	Required	Description
(none)

curl https://unified.grpc.aleatoric.systems/healthz

Response 200 OK

{
  "status": "ok",
  "uptime_seconds": 86412.7,
  "version": "0.2.23"
}

Latency Stats

Returns latency percentile summaries, target hit rates, and microstructure statistics.

GET /api/v1/unified/stats

Parameter	Required	Description
(none)

Authentication: Required

curl -H "Authorization: Bearer $API_KEY" \
  https://unified.grpc.aleatoric.systems/api/v1/unified/stats

Response 200 OK

{
  "latency": {
    "p50_us": 312,
    "p95_us": 487,
    "p99_us": 614,
    "target_us": 500,
    "target_hit_rate": 0.961
  },
  "throughput": {
    "events_per_second": 847.3,
    "active_streams": 24
  },
  "window": {
    "start": "2026-03-13T00:00:00Z",
    "end": "2026-03-13T12:34:56Z",
    "sample_count": 1048576
  }
}

Field	Type	Description
`latency.p50_us`	integer	Median ingest-to-publish latency in microseconds
`latency.p95_us`	integer	95th percentile latency
`latency.p99_us`	integer	99th percentile latency
`latency.target_us`	integer	SLA target latency
`latency.target_hit_rate`	float	Fraction of events delivered within target
`throughput.events_per_second`	float	Current event throughput
`throughput.active_streams`	integer	Number of connected SSE consumers

Query Events

Returns historical events matching the specified filters, ordered by descending timestamp.

GET /api/v1/unified/events

Parameter	Required	Type	Default	Description
`event_type`	No	string	(all)	Filter by event type (e.g., `trade`, `liquidation_warning`)
`stream`	No	string	(all)	Filter by stream name
`coin`	No	string	(all)	Filter by asset symbol (e.g., `BTC`, `ETH`)
`limit`	No	integer	`100`	Maximum number of events to return (max 1000)
`since`	No	string (ISO 8601)	(none)	Return events after this timestamp
`until`	No	string (ISO 8601)	(none)	Return events before this timestamp

Authentication: Required

curl -H "Authorization: Bearer $API_KEY" \
  "https://unified.grpc.aleatoric.systems/api/v1/unified/events?event_type=trade&coin=BTC&limit=5"

Response 200 OK

{
  "events": [
    {
      "event_type": "trade",
      "stream": "trade",
      "timestamp": "2026-03-13T12:34:56.789012Z",
      "payload": {
        "coin": "BTC",
        "price": 94512.30,
        "size": 0.125,
        "notional": 11814.04,
        "side": "buy"
      }
    },
    {
      "event_type": "trade",
      "stream": "trade",
      "timestamp": "2026-03-13T12:34:56.654321Z",
      "payload": {
        "coin": "BTC",
        "price": 94510.80,
        "size": 0.250,
        "notional": 23627.70,
        "side": "sell"
      }
    }
  ],
  "count": 2,
  "has_more": true
}

Real-Time Event Stream (SSE)

Opens a persistent Server-Sent Events connection delivering all matching events in real time.

GET /api/v1/unified/stream

Parameter	Required	Type	Default	Description
`event_type`	No	string	(all)	Filter to a specific event type
`stream`	No	string	(all)	Filter by stream name
`coin`	No	string	(all)	Filter by asset symbol

Authentication: Required

curl -N -H "Authorization: Bearer $API_KEY" \
  "https://unified.grpc.aleatoric.systems/api/v1/unified/stream?event_type=trade&coin=ETH"

Response 200 OK (text/event-stream)

event: trade
data: {"event_type":"trade","stream":"trade","timestamp":"2026-03-13T12:34:56.789012Z","payload":{"coin":"ETH","price":3845.20,"size":2.5,"notional":9613.00,"side":"buy"}}

event: trade
data: {"event_type":"trade","stream":"trade","timestamp":"2026-03-13T12:34:57.012345Z","payload":{"coin":"ETH","price":3844.90,"size":1.0,"notional":3844.90,"side":"sell"}}

Each SSE frame uses the event field for the event type and data field for the JSON payload. Clients should handle reconnection using the Last-Event-ID header with the id field if present.

Latest All-Mids Snapshot

Returns the most recent mid-price snapshot for all actively traded assets.

GET /api/v1/unified/all-mids

Parameter	Required	Description
(none)

Authentication: Required

curl -H "Authorization: Bearer $API_KEY" \
  https://unified.grpc.aleatoric.systems/api/v1/unified/all-mids

Response 200 OK

{
  "timestamp": "2026-03-13T12:34:56.789012Z",
  "mids": {
    "BTC": "94512.30",
    "ETH": "3845.20",
    "SOL": "187.45",
    "DOGE": "0.1823",
    "ARB": "1.2340"
  }
}

All prices are returned as string-encoded decimals to preserve full precision.

All-Mids Stream (SSE)

Opens a persistent SSE connection delivering mid-price snapshots as they update.

GET /api/v1/unified/all-mids/stream

Parameter	Required	Description
(none)

Authentication: Required

curl -N -H "Authorization: Bearer $API_KEY" \
  https://unified.grpc.aleatoric.systems/api/v1/unified/all-mids/stream

Response 200 OK (text/event-stream)

event: all_mids
data: {"timestamp":"2026-03-13T12:34:56.789012Z","mids":{"BTC":"94512.30","ETH":"3845.20","SOL":"187.45"}}

event: all_mids
data: {"timestamp":"2026-03-13T12:34:57.123456Z","mids":{"BTC":"94513.10","ETH":"3845.40","SOL":"187.50"}}

L2 Order Book

Returns a depth-limited snapshot of the L2 order book for a given asset.

GET /api/v1/unified/l2-book

Parameter	Required	Type	Default	Description
`coin`	Yes	string		Asset symbol (e.g., `BTC`, `ETH`)
`dex`	No	string	`hyperliquid`	Exchange identifier
`depth`	No	integer	`20`	Number of price levels per side (max 200)

Authentication: Required

curl -H "Authorization: Bearer $API_KEY" \
  "https://unified.grpc.aleatoric.systems/api/v1/unified/l2-book?coin=BTC&depth=5"

Response 200 OK

{
  "coin": "BTC",
  "dex": "hyperliquid",
  "timestamp": "2026-03-13T12:34:56.789012Z",
  "bids": [
    { "px": "94510.00", "sz": "1.250" },
    { "px": "94509.50", "sz": "3.100" },
    { "px": "94509.00", "sz": "0.875" },
    { "px": "94508.00", "sz": "5.200" },
    { "px": "94507.50", "sz": "2.400" }
  ],
  "asks": [
    { "px": "94512.50", "sz": "0.900" },
    { "px": "94513.00", "sz": "2.750" },
    { "px": "94513.50", "sz": "1.600" },
    { "px": "94514.00", "sz": "4.100" },
    { "px": "94515.00", "sz": "0.500" }
  ]
}

Field	Type	Description
`bids`	array	Bid levels sorted by descending price
`asks`	array	Ask levels sorted by ascending price
`px`	string	Price level (string-encoded decimal)
`sz`	string	Cumulative size at this level

Asset Contexts

Returns funding rate, open interest, 24h volume, and mark price for one or all assets.

GET /api/v1/unified/asset-contexts

Parameter	Required	Type	Default	Description
`coin`	No	string	(all)	Filter to a specific asset
`dex`	No	string	`hyperliquid`	Exchange identifier

Authentication: Required

curl -H "Authorization: Bearer $API_KEY" \
  "https://unified.grpc.aleatoric.systems/api/v1/unified/asset-contexts?coin=BTC"

Response 200 OK

{
  "contexts": [
    {
      "coin": "BTC",
      "dex": "hyperliquid",
      "timestamp": "2026-03-13T12:34:56.789012Z",
      "funding_rate": "0.000034",
      "open_interest": "12458.75",
      "volume_24h": "892341567.80",
      "mark_price": "94511.40",
      "oracle_price": "94508.90",
      "next_funding_time": "2026-03-13T16:00:00Z"
    }
  ]
}

Field	Type	Description
`funding_rate`	string	Current 8-hour funding rate (decimal, e.g., `0.000034` = 0.34 bps)
`open_interest`	string	Total open interest in base asset units
`volume_24h`	string	Trailing 24-hour notional volume in USD
`mark_price`	string	Current mark price
`oracle_price`	string	Oracle index price
`next_funding_time`	string (ISO 8601)	Timestamp of next funding settlement

Consensus Pulse

Returns block-level chain health metrics derived from HyperEVM consensus data. Small-block and large-block base fees are separated by inter-block time to expose congestion premiums.

GET /api/v1/unified/consensus-pulse

Parameter	Required	Description
(none)

Authentication: Required

curl -H "Authorization: Bearer $API_KEY" \
  https://unified.grpc.aleatoric.systems/api/v1/unified/consensus-pulse

Response 200 OK

{
  "consensus_pulse": {
    "current_block_height": 29634749,
    "small_block_base_fee_gwei": 0.0001,
    "large_block_base_fee_gwei": 0.0003,
    "gas_delta_gwei": 0.0002,
    "tokyo_p2p_latency_ms": 18.5,
    "small_block_samples": 48,
    "large_block_samples": 6
  }
}

Field	Type	Description
`current_block_height`	integer	Latest observed block number
`small_block_base_fee_gwei`	float	Mean base fee for blocks with inter-block time $\leq 3\text{s}$
`large_block_base_fee_gwei`	float	Mean base fee for blocks with inter-block time $\geq 20\text{s}$
`gas_delta_gwei`	float	$\Delta_{\text{gas}} = \text{large} - \text{small}$ (positive indicates congestion premium)
`tokyo_p2p_latency_ms`	float	Round-trip P2P latency to Tokyo relay node
`small_block_samples`	integer	Number of small blocks in the current sampling window
`large_block_samples`	integer	Number of large blocks in the current sampling window

Event Types

All events share a common envelope:

{
  "event_type": "<type>",
  "stream": "<stream_name>",
  "timestamp": "<ISO 8601 with microseconds>",
  "payload": { }
}

Event Type	Category	Description
`trade`	market	Matched trade from HyperCore gRPC
`l4_delta`	market	Delta-only L4 order book update
`block_metrics`	chain	Block size, throughput, and gas metrics
`liquidation_warning`	evm_log	Decoded HyperCore `RawAction` liquidation event
`liquidation_cascade`	signal	Derived cascade signal from rolling-window analysis
`erc20_transfer`	evm_log	Standard ERC-20 `Transfer` event (decoded)
`raw_log`	evm_log	Unclassified EVM log event

trade

Matched execution from HyperCore.

{
  "event_type": "trade",
  "stream": "trade",
  "timestamp": "2026-03-13T12:34:56.789012Z",
  "payload": {
    "coin": "BTC",
    "price": 94512.30,
    "size": 0.125,
    "notional": 11814.04,
    "side": "buy"
  }
}

l4_delta

Delta-only L4 order book updates. Each entry carries an operation code indicating whether the level was added, modified, or removed.

{
  "event_type": "l4_delta",
  "stream": "l4_delta",
  "timestamp": "2026-03-13T12:34:56.789012Z",
  "payload": {
    "coin": "BTC",
    "bids": [
      { "px": "94510.00", "sz": "1.250", "op": "modify" }
    ],
    "asks": [
      { "px": "94515.00", "sz": "0.000", "op": "remove" }
    ]
  }
}

`op` Value	Description
`add`	New price level inserted
`modify`	Size at existing level changed
`remove`	Price level removed (`sz` = `"0.000"`)

block_metrics

Block-level chain throughput data from HyperEVM.

{
  "event_type": "block_metrics",
  "stream": "block_metrics",
  "timestamp": "2026-03-13T12:34:56.789012Z",
  "payload": {
    "block_number": 29634749,
    "block_size_bytes": 1024,
    "tx_count": 3,
    "gas_used": 150000,
    "gas_limit": 30000000
  }
}

liquidation_warning

Emitted when the sidecar matches and decodes a HyperCore RawAction liquidation payload from an EVM log.

{
  "event_type": "liquidation_warning",
  "stream": "liquidation_warning",
  "timestamp": "2026-03-13T12:34:56.789012Z",
  "payload": {
    "tx_hash": "0xabc123...",
    "block_number": 29634749,
    "log_index": 3,
    "decoded": {
      "user": "0xdef456...",
      "asset": 0,
      "side": "sell",
      "price": 94123.45,
      "size": 0.5,
      "action": "limit_order",
      "reduce_only": false
    }
  }
}

Field	Type	Description
`decoded.user`	string	Address of the liquidated account
`decoded.asset`	integer	Hyperliquid asset index
`decoded.side`	string	`"buy"` or `"sell"`
`decoded.price`	float	Liquidation fill price
`decoded.size`	float	Position size liquidated (base units)
`decoded.action`	string	Underlying action type
`decoded.reduce_only`	boolean	Whether the order was reduce-only

Liquidation Cascade Detection

The Unified Stream implements a rolling-window statistical detector that identifies clusters of liquidation activity. When individual liquidation_warning events concentrate within a short temporal window at sufficient aggregate notional volume, the system emits a liquidation_cascade signal.

Cascade Detection

Formal Definition

Let $W(t)$ denote a rolling window of duration $\tau$ seconds ending at time $t$ , containing all liquidation_warning events observed within $[t - \tau, \, t]$ . Define:

$N(t) = |W(t)|$ — the count of liquidation events in the window
$V_i$ — the notional value (in USD) of the $i$ -th event in the window

A cascade signal fires at time $t$ when the following conditions are jointly satisfied:

$N(t) \geq N_{\min} \quad \text{and} \quad \sum_{i \in W(t)} V_i \geq V_{\min}$

The dual-threshold requirement ensures that the signal is robust: isolated large liquidations and high-frequency small liquidations are both filtered out. Only clusters with both sufficient event density $N(t)$ and aggregate notional mass $\sum V_i$ produce a signal.

After emission, a cooldown period $\delta$ suppresses duplicate signals to prevent downstream consumers from receiving redundant cascade alerts for the same event cluster.

Cascade Payload

{
  "event_type": "liquidation_cascade",
  "stream": "liquidation_cascade",
  "timestamp": "2026-03-13T12:34:56.789012Z",
  "payload": {
    "window_seconds": 30.0,
    "window_event_count": 5,
    "window_total_notional_usd": 1250000.0,
    "window_buy_notional_usd": 750000.0,
    "window_sell_notional_usd": 500000.0,
    "dominant_side": "buy",
    "last_price": 94123.45,
    "last_size": 0.5,
    "first_block_number": 29634740,
    "last_block_number": 29634749,
    "unique_users": ["0xdef456..."],
    "asset_ids": [0],
    "sample": []
  }
}

Field	Type	Description
`window_seconds`	float	Duration $\tau$ of the detection window
`window_event_count`	integer	$N(t)$ — events in the current window
`window_total_notional_usd`	float	$\sum_{i \in W(t)} V_i$ — aggregate notional
`window_buy_notional_usd`	float	Buy-side notional within the window
`window_sell_notional_usd`	float	Sell-side notional within the window
`dominant_side`	string	`"buy"` or `"sell"` — whichever side has greater notional
`last_price`	float	Price of the most recent liquidation in the window
`last_size`	float	Size of the most recent liquidation
`first_block_number`	integer	Earliest block in the window
`last_block_number`	integer	Latest block in the window
`unique_users`	array	Distinct liquidated addresses
`asset_ids`	array	Distinct asset indices involved
`sample`	array	Subset of contributing events (for inspection)

Error Responses

All endpoints return standard error responses:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Upgrade to Pro for higher limits.",
    "retry_after_seconds": 12
  }
}

HTTP Status	Error Code	Description
`401`	`UNAUTHORIZED`	Missing or invalid API key
`403`	`TIER_INSUFFICIENT`	Endpoint requires a higher tier
`404`	`NOT_FOUND`	Unknown asset or endpoint
`429`	`RATE_LIMIT_EXCEEDED`	Request or connection limit hit
`503`	`SERVICE_UNAVAILABLE`	Upstream hypernode unreachable

Connection Best Practices

SSE Reconnection. Implement exponential backoff starting at 1 second with a maximum of 30 seconds. If the server sends a retry: field, honor its value. Pass the last received event id via the Last-Event-ID header to resume without gaps.

Regional Failover. If the primary region returns 503 for more than 3 consecutive health checks, failover to the secondary region. Both regions serve identical event streams with independent ingest pipelines.

Decompression. Responses are gzip-compressed when the client sends Accept-Encoding: gzip. For SSE streams, ensure your HTTP client handles chunked transfer encoding with streaming decompression.