Quickstart

Aleatoric Data provides institutional-grade blockchain data infrastructure for Hyperliquid L1. This guide takes you from zero to your first streaming data request in minutes.

1. Create an Account

Sign up at data.aleatoric.systems/get-started.

The public self-serve onboarding flow currently defaults to the Founder tier, which maps to Quant-level backend access while the promotion is active. The underlying service tiers remain:

Plan	Target Use Case	Transports	Regions
Basic	Prototyping, block queries, on-demand lookups	JSON-RPC	US
Pro	Trading systems, dashboards, signal pipelines	JSON-RPC, gRPC, Unified Stream (SSE)	US + JP
Quant	Full-depth execution, replica streams, co-location	All transports incl. Disk-Sync WebSocket	US + JP

Registration is required before MCP or transport access is granted. The same account and issued ak_live_... key work across both the live data surface and the simulation/MCP surface hosted on mcp.aleatoric.systems.

After registration you will be redirected to Stripe to complete payment. Once payment is confirmed, your API key is immediately available in the app console.

2. Get Your API Key

Visit App Console > API Keys after registration. Your API key is displayed in the API Keys card. All live keys are prefixed with ak_live_:

ak_live_c51nSdWI9msCrjFnLcZfDS8n...

Copy the key and store it securely. The key is shown in full only once at creation time. If you lose it, you can rotate it from App Console > API Keys (see Key Rotation).

Security note — Your key is verified server-side using an HMAC-SHA256 hash. The plaintext key is never stored by Aleatoric. See Authentication for the full security model.

3. Understand the Transport Architecture

Aleatoric exposes four transport protocols, each optimized for different latency and throughput profiles:

Transport	Protocol	Typical Latency	Best For
JSON-RPC	HTTPS POST	$< 50\text{ms}$ p50	Block queries, state reads, on-demand lookups
gRPC	HTTP/2 + Protobuf	$< 10\text{ms}$ p50	Streaming prices, execution engines, low-latency trading
Unified Stream	Server-Sent Events (SSE)	$< 500\mu\text{s}$ event delivery	Dashboards, monitoring, signal processing
Disk-Sync WebSocket	WSS	Raw replica latency	Full Hyperliquid replica stream (Enterprise)

4. Make Your First Request

JSON-RPC (curl)

The simplest way to verify your key is working. This returns the latest Hyperliquid L1 block number:

curl -s -X POST https://rpc.aleatoric.systems \
  -H "Content-Type: application/json" \
  -H "x-api-key: ak_live_YOUR_KEY_HERE" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_blockNumber",
    "params": [],
    "id": 1
  }'

Expected response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x1a4b3f"
}

The result field is the block height as a hex-encoded integer. To convert: $\text{blockNumber} = \texttt{parseInt}(\texttt{result}, 16)$.

JSON-RPC (ethers.js)

For JavaScript/TypeScript applications using the ethers library:

import { JsonRpcProvider, FetchRequest } from 'ethers';

const API_KEY = 'ak_live_YOUR_KEY_HERE';

// Create a custom FetchRequest to inject the API key header
const fetchReq = new FetchRequest('https://rpc.aleatoric.systems');
fetchReq.setHeader('x-api-key', API_KEY);

const provider = new JsonRpcProvider(fetchReq, undefined, {
  staticNetwork: true,
  batchMaxCount: 1,
});

const blockNumber = await provider.getBlockNumber();
console.log('Latest block:', blockNumber);

const balance = await provider.getBalance('0x...');
console.log('Balance (wei):', balance.toString());

Tip — Set batchMaxCount: 1 to disable request batching. Aleatoric processes individual requests with lower latency than batched payloads at the Basic tier.

gRPC (Python)

For low-latency streaming use cases. Requires the Aleatoric proto definitions (see gRPC Reference for .proto files):

import grpc
from hypercore_bridge_pb2_grpc import PriceServiceStub
from hypercore_bridge_pb2 import MidPriceRequest, StreamMidsRequest

API_KEY = "ak_live_YOUR_KEY_HERE"
TARGET  = "hl.grpc.aleatoric.systems:443"

# Create a secure channel with TLS
channel = grpc.secure_channel(TARGET, grpc.ssl_channel_credentials())
stub = PriceServiceStub(channel)
auth_metadata = [("x-api-key", API_KEY)]

# Unary request: get current BTC mid price
response = stub.GetMidPrice(
    MidPriceRequest(coin="BTC"),
    metadata=auth_metadata,
)
print(f"BTC mid price: {response.price}")

# Server-streaming: subscribe to live BTC mid prices
stream = stub.StreamMids(
    StreamMidsRequest(coin="BTC", subscription="allMids"),
    metadata=auth_metadata,
)
for update in stream:
    print(f"BTC mid: {update.price} @ {update.timestamp}")

gRPC streaming maintains a persistent HTTP/2 connection. Expected throughput on Pro tier is $\geq 200$ messages/second with $p_{99} < 25\text{ms}$ delivery latency.

Unified Stream (curl SSE)

Server-Sent Events provide a pre-decoded, human-readable event feed. Ideal for dashboards and monitoring pipelines:

# Stream all events (trades, liquidations, funding, order book updates)
curl -N -H "x-api-key: ak_live_YOUR_KEY_HERE" \
  "https://unified.grpc.aleatoric.systems/api/v1/unified/stream"

Each SSE frame is a JSON object:

data: {"event_type":"trade","coin":"BTC","price":"98423.50","size":"0.15","side":"buy","ts":1741871234567}

data: {"event_type":"liquidation_warning","coin":"ETH","position_size":"12.5","margin_ratio":"0.062","ts":1741871234890}

To filter by event type:

# Only trades and liquidation warnings
curl -N -H "x-api-key: ak_live_YOUR_KEY_HERE" \
  "https://unified.grpc.aleatoric.systems/api/v1/unified/stream?types=trade,liquidation_warning"

5. Choose Your Region

Aleatoric exposes public production regions in both the US and Japan:

Region	JSON-RPC Endpoint	gRPC Endpoint
US (default)	rpc.aleatoric.systems	hl.grpc.aleatoric.systems:443
Japan	rpc-jp.aleatoric.systems	hl-jp.grpc.aleatoric.systems:443

Pro and higher plans are eligible for JP. Use the JP endpoints when your account includes Japan East access.

For Asia-Pacific clients, JP remains the intended future low-latency region. As a rough model, one-way propagation delay from Tokyo to US East is approximately:

$\Delta t_{\text{US}\to\text{JP}} \approx \frac{d}{c_{\text{fiber}}} \approx \frac{15{,}000\text{ km}}{2 \times 10^5\text{ km/s}} \approx 75\text{ ms}$

Using the JP endpoint eliminates this round-trip overhead for clients co-located in Asia.

For US routing, set the SDK endpoints to the US production hosts:

export HYPER_RPC_URL=https://rpc.aleatoric.systems/
export HYPER_GRPC_TARGET=hl.grpc.aleatoric.systems:443
export HYPER_UNIFIED_STREAM_URL=https://unified.grpc.aleatoric.systems

See Endpoints for the full endpoint matrix including Unified Stream and WebSocket hostnames.

Next Steps

• Authentication — API key security model, scopes, and rotation
• Connecting — Full code examples for every transport and SDK
• JSON-RPC Reference — Complete method list with request/response schemas
• gRPC Reference — Proto definitions, streaming RPCs, and reconnection patterns
• Rate Limits — Per-tier throughput limits and burst allowances