WebSocket Streams

note

WebSocket streaming is a planned feature. The current Outpost is a stateless REST-only edge proxy. This page documents the planned interface for when WebSocket support is implemented.

Connection

wss://<outpost-host>/ws

Authentication

WebSocket connections require mTLS client certificates. The certificate must be issued by a trusted CA registered with PolTrading.

Subscribe

After connection, send a subscription message:

{
  "type": "subscribe",
  "channel": "orderbook_l2",
  "market_id": "0x0000...0001"
}

Channels

Channel	Description	Payload
orderbook_l2	Level 2 order book updates	{bids: [...], asks: [...], ts: ...}
trade_events	Real-time trade executions	{price, size, side, ts}
market_update	Market metadata changes	{question, outcomes, resolution}

Heartbeat

• Client → Server: Send PING every 10 seconds
• Server → Client: Responds with PONG
• Connection is closed after 30 seconds of no client heartbeat

Reconnection Strategy

Attempt 1: 1s delay
Attempt 2: 2s delay
Attempt 3: 4s delay
Attempt 4: 8s delay
Max:       30s delay

After reconnection, request missed events using the last received event ID.

Code Example

import asyncio
import websockets
import json

async def subscribe():
    async with websockets.connect("wss://outpost.poltrading.com/ws") as ws:
        # Subscribe to order book
        await ws.send(json.dumps({
            "type": "subscribe",
            "channel": "orderbook_l2",
            "market_id": "0x0000...0001",
        }))

        # Heartbeat task
        async def heartbeat():
            while True:
                await asyncio.sleep(10)
                await ws.send("PING")

        asyncio.create_task(heartbeat())

        # Listen for events
        async for message in ws:
            if message == "PONG":
                continue
            event = json.loads(message)
            print(f"[{event['channel']}] {event['data']}")

asyncio.run(subscribe())

package main

import (
    "encoding/json"
    "log"
    "time"

    "github.com/gorilla/websocket"
)

func subscribe() {
    conn, _, err := websocket.DefaultDialer.Dial(
        "wss://outpost.poltrading.com/ws", nil)
    if err != nil {
        log.Fatal(err)
    }
    defer conn.Close()

    // Subscribe
    sub := map[string]string{
        "type":      "subscribe",
        "channel":   "orderbook_l2",
        "market_id": "0x0000...0001",
    }
    conn.WriteJSON(sub)

    // Heartbeat ticker
    go func() {
        ticker := time.NewTicker(10 * time.Second)
        defer ticker.Stop()
        for range ticker.C {
            conn.WriteMessage(websocket.TextMessage, []byte("PING"))
        }
    }()

    // Listen
    for {
        _, msg, err := conn.ReadMessage()
        if err != nil {
            log.Printf("read error: %v", err)
            break
        }
        if string(msg) == "PONG" {
            continue
        }
        var event map[string]interface{}
        json.Unmarshal(msg, &event)
        log.Printf("[%s] %v", event["channel"], event["data"])
    }
}