WebSocket Real-Time Streaming

import { HodlbaseProvider, useHodlbaseRealtime } from "@hodlbase/realtime/react"

function App() {
  return (
    <HodlbaseProvider apiKey="hb_YOUR_API_KEY">
      <Dashboard />
    </HodlbaseProvider>
  )
}

function Dashboard() {
  // Stream Strategy's stock price and mNAV
  const mstr = useHodlbaseRealtime("company", "MSTR", {
    metrics: ["common_stock_price", "mnav"],
    interval: 5,
  })

  // Stream STRC's close price and effective yield
  const strc = useHodlbaseRealtime("security", "STRC", {
    metrics: ["close_price", "effective_yield"],
    interval: 5,
  })

  return (
    <div>
      <h2>Strategy (MSTR)</h2>
      <p>Stock Price: ${mstr.data?.common_stock_price ?? "—"}</p>
      <p>mNAV: {mstr.data?.mnav ?? "—"}</p>

      <h2>STRC Preferred</h2>
      <p>Close Price: ${strc.data?.close_price ?? "—"}</p>
      <p>Effective Yield: {strc.data?.effective_yield ?? "—"}%</p>

      <p>Updated: {mstr.updatedAt ?? "Connecting..."}</p>
    </div>
  )
}

import { HodlbaseRealtime } from "@hodlbase/realtime"

const client = new HodlbaseRealtime({
  apiKey: "hb_YOUR_API_KEY",
  // baseUrl: "wss://api.hodlbase.io",  // default
  // reconnect: true,                    // auto-reconnect (default)
  // debug: false,                       // console logging
})

// Subscribe with per-subscription callback
const sub = client.subscribe("company", "MSTR", {
  metrics: ["mnav", "market_cap"],
  interval: 5,
  onUpdate: (msg) => {
    console.log("mNAV:", msg.data.mnav)
    console.log("Market Cap:", msg.data.market_cap)
  },
})

// Global event listeners
client.on("welcome", (msg) => console.log("Plan:", msg.plan))
client.on("statusChange", (status) => console.log("Status:", status))
client.on("error", (msg) => console.error("Error:", msg.message))

// Later: unsubscribe
sub.unsubscribe()

// Or disconnect entirely
client.disconnect()

wss://api.hodlbase.io/v1/ws/realtime?api_key=hb_YOUR_API_KEY

{
  "type": "welcome",
  "plan": "professional",
  "limits": {
    "max_connections": 5,
    "max_entity_subscriptions": 3,
    "min_update_interval": 10
  },
  "usage": {
    "connections": 1,
    "connections_limit": 5,
    "entity_subscriptions": 0,
    "entity_subscriptions_limit": 3,
    "monthly_ws_updates": 0
  }
}

{
  "action": "subscribe",
  "channel": "company",
  "ticker": "MSTR",
  "metrics": ["mnav", "market_cap"],
  "interval": 5
}

{
  "action": "unsubscribe",
  "channel": "company",
  "ticker": "MSTR"
}

{ "action": "ping" }

{ "action": "usage" }

{
  "type": "subscribed",
  "channel": "company",
  "ticker": "MSTR",
  "metrics": ["mnav", "market_cap", "common_stock_price"],
  "interval": 15,
  "usage": { ... },
  "rejected": [
    { "metric": "enterprise_value_usd", "reason": "requires enterprise plan" }
  ],
  "interval_adjusted": true,
  "requested_interval": 0,
  "min_interval": 15
}

{
  "type": "update",
  "channel": "company",
  "ticker": "MSTR",
  "data": {
    "mnav": "2.34",
    "market_cap": "115000000000",
    "common_stock_price": "398.50"
  },
  "updated_at": "2026-03-17T14:30:00Z"
}

{
  "type": "error",
  "message": "Entity subscription limit (1) reached for your plan"
}

{
  "type": "usage",
  "user_limits": {
    "max_connections": 5,
    "max_entity_subscriptions": 3,
    "min_update_interval": 10
  },
  "user_usage": {
    "user_id": "usr-abc",
    "connections": 2,
    "entity_subscriptions": 1,
    "monthly_ws_updates": 42
  },
  "per_api_key_usage": {
    "api_key_id": "key-abc",
    "connections": 1,
    "entity_subscriptions": 1,
    "monthly_ws_updates": 12
  }
}