TypeScript SDK

Overview

hypercore-ts-sdk is the official TypeScript client for accessing Hyperliquid market data through Aleatoric infrastructure. It is open-source, published on npm, and available on GitHub.

The SDK is fully typed under TypeScript strict mode and supports all four Aleatoric transport protocols: JSON-RPC over HTTP, gRPC with TLS, WebSocket for live subscriptions, and Unified Stream via Server-Sent Events. It runs in both Node.js (>=20) and browser environments.

Installation

npm install hypercore-ts-sdk

Configuration

The SDK reads configuration from environment variables. All values have sensible defaults pointing to the Aleatoric production endpoints.

Variable	Purpose	Default
HYPER_RPC_URL	JSON-RPC endpoint	https://rpc.aleatoric.systems/
HYPER_GRPC_TARGET	gRPC endpoint	hl.grpc.aleatoric.systems:443
HYPER_UNIFIED_STREAM_URL	Unified Stream endpoint	https://unified.grpc.aleatoric.systems
HYPER_WS_URL	WebSocket endpoint	wss://api.hyperliquid.xyz/ws
HYPER_API_KEY	API key for authenticated requests	—
UNIFIED_STREAM_KEY	Unified Stream API key	—
ALEATORIC_GRPC_KEY	gRPC API key	—
HYPER_TIMEOUT_MS	Request timeout in milliseconds	10000
HYPER_VERIFY_TLS	TLS verification for HTTP/SSE	—
HYPER_GRPC_TLS	TLS configuration for gRPC	—

Set these in your shell, a .env file, or your deployment platform’s secret management. The SDK will pick them up at client construction time.

Core Clients

HyperCoreAPI

The HTTP client for JSON-RPC calls. This is the simplest way to fetch point-in-time snapshots of on-chain and exchange state.

import { HyperCoreAPI } from 'hypercore-ts-sdk';

const api = new HyperCoreAPI();
const block = await api.blockNumber();
const mids = await api.allMids();
const btc = await api.coinMid('BTC');

For calls not covered by the convenience methods, use the generic RPC interface directly:

const result = await api.rpcCall('eth_getBalance', ['0x...', 'latest']);

The client uses the native fetch API under the hood, so it works without additional HTTP dependencies in both Node.js 20+ and modern browsers.

GrpcClient

The gRPC client provides low-latency streaming access with TLS encryption, metadata-based authentication, and built-in health checking. It is built on @grpc/grpc-js and @grpc/proto-loader.

import { GrpcClient } from 'hypercore-ts-sdk';

const grpc = new GrpcClient();

// Health check
const health = await grpc.healthCheck();

// Price streaming
await grpc.streamMids('BTC', (price) => {
  console.log(`BTC: ${price.price}`);
}, { maxEvents: 10 });

// Liquidation feed
await grpc.streamLiquidations('BTC', (event) => {
  console.log(`Liquidation: ${event}`);
}, { maxEvents: 5 });

The maxEvents option provides a clean way to consume a fixed number of events and then close the stream. Omit it for indefinite streaming.

UnifiedStreamClient

The Unified Stream client consumes Server-Sent Events from the Aleatoric aggregation layer. It combines REST snapshot endpoints with SSE streaming, giving you both current state and real-time updates through a single client.

import { UnifiedStreamClient } from 'hypercore-ts-sdk';

const unified = new UnifiedStreamClient();

// REST snapshots
const stats = await unified.stats();
const pulse = await unified.consensusPulse();
const book = await unified.l2Book({ coin: 'BTC', depth: 10 });
const mids = await unified.allMids();

// Filtered events
const events = await unified.events({ event_type: 'trade', limit: 10 });

// Liquidation cascades
const cascades = await unified.liquidationCascades({ limit: 5 });

The snapshot methods return typed objects matching the Unified Stream event schema. See the Unified Stream reference for the full event type catalog.

WebSocket

For direct WebSocket subscriptions, the SDK provides a lightweight utility that handles connection management and message parsing.

import { getPriceFromWS } from 'hypercore-ts-sdk';

await getPriceFromWS({
  coin: 'BTC',
  channel: 'allMids',
  onPrice: (price) => console.log(price),
});

Supported channels: allMids, trades, l2Book.

The WebSocket client is built on the ws library and follows auto-reconnection patterns for resilience in long-running processes.

Type Definitions

The SDK exports typed interfaces for all response payloads. Import them directly for use in your application code:

import type {
  GrpcMidPrice,
  GrpcBlockNumber,
  LiquidationFeedEvent,
  UnifiedTradePayload,
  UnifiedL4DeltaPayload,
  UnifiedAllMidsSnapshot,
  UnifiedL2BookSnapshot,
  UnifiedAssetContextsSnapshot,
  UnifiedLiquidationWarningEvent,
  UnifiedLiquidationCascadeEvent,
  UnifiedStats,
  UnifiedConsensusPulse,
} from 'hypercore-ts-sdk';

These types are generated from the actual protocol definitions and kept in sync with the server schema, so your compiler will catch breaking changes at build time rather than at runtime.

CLI

The package ships a CLI for quick exploration and scripting. It is available as hypercore-ts-sdk after installation, or via npx without installing globally.

npx hypercore-ts-sdk --help
npx hypercore-ts-sdk block-number
npx hypercore-ts-sdk all-mids
npx hypercore-ts-sdk grpc-health
npx hypercore-ts-sdk unified-stats

The CLI reads the same environment variables as the library clients, so you can point it at different endpoints by setting HYPER_RPC_URL or HYPER_GRPC_TARGET before invoking a command.

MCP Server

The SDK includes a built-in Model Context Protocol server that exposes 12 tools to AI assistants. See MCP Servers for detailed setup instructions covering Claude Desktop, ChatGPT, and other compatible hosts.

npx hypercore-ts-mcp

The MCP server wraps the same client methods documented above, so any environment variable configuration you apply to the library also applies to the MCP server.

Quality

Aspect	Detail
Type safety	TypeScript strict mode
Protocols	JSON-RPC, gRPC, WebSocket, SSE
gRPC	@grpc/grpc-js with TLS and metadata auth
HTTP	Native fetch API
WebSocket	ws library with auto-reconnection patterns
MCP	Built-in server with 12 tools

Changelog

0.2.2

• Added UnifiedStreamClient with consensus pulse, liquidation cascades, and filtered event queries.
• Added full type exports for all payload types across every transport.
• MCP server with 12 tools for AI assistant integration.

0.1.0

• Initial release with HyperCoreAPI, GrpcClient, and WebSocket utilities.

Next Steps

• Python SDK — Python client with async generators
• MCP Servers — Connect to Claude, ChatGPT, and other AI assistants
• Connecting — Transport-level integration examples
• Unified Stream — Full event type reference