WebSocket API

Real-time data streaming for Hypercall options trading.

Interactive Reference

Check out the Interactive WebSocket API Reference for a better browsing experience with live examples and schema details.

Machine-Readable Spec

Download the AsyncAPI specification for programmatic use.

Connection

Connect to wss://HOST/ws with optional query parameters:

Parameter	Required	Description
wallet	For auth channels	Your wallet address (hex string)

API Not Yet Public

The Hypercall API is not yet publicly available. The examples below use placeholder URLs (api.hypercall.xyz). Check back after testnet launch for live endpoints.

Endpoints:

• Production: wss://api.hypercall.xyz/ws
• Local: ws://localhost:3000/ws

Subscribing to Channels

Send a JSON message to subscribe:

{"type": "Subscribe", "channel": "orderbook"}

To unsubscribe:

{"type": "Unsubscribe", "channel": "orderbook"}

You'll receive a confirmation:

{"type": "Subscribed", "channel": "orderbook"}

Available Channels

Channel	Auth Required	Description
orderbook	No	L2 orderbook updates for all symbols
trades	No	Public trade feed
markets	No	Market listing changes (created/deleted/expired)
order_updates	Yes	Your order status changes
fills	Yes	Your trade fills
portfolio	Yes	Your position and balance updates
liquidation	Yes	Your liquidation state changes

Message Types

Orderbook Update

L2 orderbook snapshot/update for a symbol.

{
  "type": "OrderbookUpdate",
  "symbol": "BTC-20260131-100000-C",
  "bids": [["95000.5", "10.5"], ["94999.0", "25.0"]],
  "asks": [["95001.0", "8.0"], ["95002.5", "15.0"]],
  "timestamp": 1737331200000
}

Field	Type	Description
symbol	string	Option symbol
bids	array	Bid levels as [price, size] tuples
asks	array	Ask levels as [price, size] tuples
timestamp	integer	Unix timestamp (milliseconds)

Trade

Public trade event.

{
  "type": "Trade",
  "symbol": "BTC-20260131-100000-C",
  "price": "0.0523",
  "size": "5.0",
  "side": "buy",
  "timestamp": 1737331200000
}

Field	Type	Description
symbol	string	Option symbol
price	string	Trade price in USD
size	string	Trade size in contracts
side	string	Aggressor side (buy or sell)
timestamp	integer	Unix timestamp (milliseconds)

Fill (Authenticated)

Your trade fill notification.

{
  "type": "Fill",
  "order_id": 12345,
  "fill_id": 67890,
  "symbol": "BTC-20260131-100000-C",
  "side": "buy",
  "price": "0.0523",
  "size": "5.0",
  "timestamp": 1737331200000,
  "wallet_address": "0x1234...abcd",
  "fee": "0.0005",
  "trade_id": 99999,
  "is_taker": true
}

Field	Type	Description
order_id	integer	Your order ID
fill_id	integer	Fill ID
symbol	string	Option symbol
side	string	Trade side (buy or sell)
price	string	Fill price in USD
size	string	Fill size in contracts
timestamp	integer	Unix timestamp (milliseconds)
wallet_address	string	Your wallet address
fee	string	Trading fee charged
trade_id	integer	Unique trade ID
is_taker	boolean	Whether you were the taker
builder_code_address	string?	Builder code wallet (if any)
builder_code_fee	string?	Builder code fee (if any)

Order Update (Authenticated)

Order status change notification.

{
  "type": "OrderUpdate",
  "order_id": 12345,
  "client_order_id": "my-order-1",
  "status": "filled",
  "filled_size": "10.0",
  "remaining_size": "0",
  "avg_fill_price": "0.0523"
}

Market Update

Market listing changes.

Market Created:

{
  "type": "MarketUpdate",
  "action": "Created",
  "symbol": "BTC-20260131-100000-C",
  "strike": "100000",
  "is_call": true,
  "underlying": "BTC",
  "expiry": 1738281600,
  "timestamp": 1737331200000
}

Market Expired:

{
  "type": "MarketUpdate",
  "action": "Expired",
  "symbol": "BTC-20260131-100000-C",
  "strike": "100000",
  "is_call": true,
  "underlying": "BTC",
  "expiry": 1738281600,
  "timestamp": 1738281600000
}

Position Expired (Authenticated)

Notification when your position settles at expiry.

{
  "type": "PositionExpired",
  "wallet_address": "0x1234...abcd",
  "symbol": "BTC-20260131-100000-C",
  "position_size": "10.0",
  "settlement_price": "105000",
  "settlement_value": "500.0",
  "timestamp": 1738281600000
}

Liquidation State Change (Authenticated)

Your account liquidation state change.

{
  "type": "LiquidationStateChange",
  "wallet_address": "0x1234...abcd",
  "previous_state": "Normal",
  "new_state": "Warning",
  "equity": "10000.0",
  "mm_required": "9500.0",
  "shortfall": "0",
  "auction_id": null,
  "timestamp": 1737331200000
}

State	Description
Normal	Account is healthy
Warning	Approaching margin call
Liquidating	Liquidation auction active

Error

Server error message.

{
  "type": "Error",
  "message": "Invalid channel: foobar"
}

Authentication

Authenticated channels require the wallet query parameter in the connection URL:

wss://api.hypercall.xyz/ws?wallet=0x1234567890abcdef...

Messages on authenticated channels are filtered to only show data for your wallet. No signature is required for WebSocket connections.

Example: Python Client

import asyncio
import websockets
import json

async def main():
    uri = "wss://api.hypercall.xyz/ws?wallet=0xYourWallet"
    
    async with websockets.connect(uri) as ws:
        # Subscribe to orderbook
        await ws.send(json.dumps({
            "type": "Subscribe",
            "channel": "orderbook"
        }))
        
        # Subscribe to your fills
        await ws.send(json.dumps({
            "type": "Subscribe", 
            "channel": "fills"
        }))
        
        # Listen for messages
        async for message in ws:
            data = json.loads(message)
            print(f"Received: {data['type']}")

asyncio.run(main())

Example: TypeScript Client

const ws = new WebSocket(
  "wss://api.hypercall.xyz/ws?wallet=0xYourWallet"
);

ws.onopen = () => {
  // Subscribe to channels
  ws.send(JSON.stringify({ type: "Subscribe", channel: "orderbook" }));
  ws.send(JSON.stringify({ type: "Subscribe", channel: "fills" }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log(`Received: ${msg.type}`);
  
  if (msg.type === "OrderbookUpdate") {
    console.log(`${msg.symbol}: ${msg.bids.length} bids, ${msg.asks.length} asks`);
  }
};