WebSocket Protocol

Connect to wss://vela-engine.fly.dev/ws for real-time order book, trades, and private data.

const ws = new WebSocket('wss://vela-engine.fly.dev/ws')

All messages are JSON-encoded objects with a type field in snake_case. The connection does not require authentication for public channels. Subscribe to public channels immediately after connecting.

Subscribe

Subscribe to one or more channels.

{
  "type": "subscribe",
  "channels": ["book:ETH-USDC", "trades:ETH-USDC", "book:BTC-USDC"]
}

Unsubscribe

{ "type": "unsubscribe", "channels": ["book:ETH-USDC"] }

Request Challenge

Begin the private channel authentication flow.

{ "type": "request_challenge" }

Authenticate

{
  "type": "auth",
  "address": "0xAbCd...1234",
  "signature": "0x..."
}

Ping

{ "type": "ping" }

Book Snapshot

Full order book snapshot, sent on subscription and after significant changes.

{
  "type": "book_snapshot",
  "market": "ETH-USDC",
  "bids": [["3200.000000", "1.500000"], ["3199.000000", "3.200000"]],
  "asks": [["3201.600000", "2.000000"], ["3202.000000", "0.800000"]],
  "timestamp": 1734567890
}

Trade

Anonymized public trade event.

{
  "type": "trade",
  "market": "ETH-USDC",
  "price": "3200.000000",
  "size": "0.500000",
  "side": "buy",
  "timestamp": 1734567890
}

Challenge

Response to request_challenge. Sign the nonce to authenticate.

{ "type": "challenge", "nonce": "a3f8c1d2e4b59f..." }

Fill (private)

Sent when one of your orders is matched. Requires authentication.

{
  "type": "fill",
  "order_id": "ord_abc123",
  "market": "ETH-USDC",
  "side": "bid",
  "price": "3200.000000",
  "size": "1.000000",
  "fee": "-0.640000",
  "timestamp": 1734567890
}

Order Update (private)

{
  "type": "order_update",
  "order_id": "ord_abc123",
  "status": "partially_filled",
  "filled": "0.500000",
  "remaining": "0.500000",
  "timestamp": 1734567890
}

Balance Update (private)

{
  "type": "balance_update",
  "asset": "USDC",
  "available": "9500.000000",
  "locked": "500.000000",
  "timestamp": 1734567890
}

Pong

{ "type": "pong" }