Skip to main content
When you need state updates faster than 15-second polling allows, open a WebSocket. The server pushes every state transition and a heartbeat every 5 seconds. Endpoint: wss://api.pegana.xyz/v1/ws

Open a connection

No auth, no key. Origin header is checked against an allowlist — https://pegana.xyz, https://www.pegana.xyz, http://localhost:3000 by default. Add more origins via the CORS_EXTRA_ORIGINS env var on self-hosted instances.

Message shapes

All messages are JSON, single-line per frame. The op field discriminates.

Server → client: state update

Pushed on every peg-state change for the asset. The envelope carries the asset symbol; payload carries the new state, the discount, the two underlying values (intrinsic_usd, market_usd), and updated_at. There is no previous_state or confidence field on this frame — fetch the prior state from your own last-seen value, and use /v1/assets/{symbol}/state for the confidence score.

Server → client: heartbeat

Every 5 seconds. Use this to detect connection death — if you go 15s without any frame (update or heartbeat), drop and reconnect.

Server → client: error

Returned on bad input. Connection stays open.

Client → server: ping

Server responds with { "op": "pong" }. Optional — heartbeats already keep the connection alive on most NAT/proxy configurations.

Client → server: subscribe / unsubscribe

In v1 these are no-ops — the server broadcasts updates for every asset to every connection. Filter client-side by inspecting msg.asset. Per-asset subscription is planned for v2.

Connection limits

  • Per-IP cap: 5 concurrent connections. Beyond that, handshakes return 429.
  • Idle timeout: None. If both server heartbeat and client ping flow normally, the connection stays open indefinitely.

Reconnect strategy

Recommended client logic:

What about historical data?

The WebSocket is stream-only. For history, use /v1/assets/{symbol}/history. A common pattern is to fetch the last 24h via REST on connect, then maintain real-time via WebSocket.

Next

Webhooks

Push to your endpoint instead of holding a connection.

MCP for agents

Native MCP tool for Claude, Cursor, Cline.