WebSocket Overview

Openfish exposes five WebSocket endpoints spread across two servers. These connections push real-time updates for order book deltas, trades, price feeds, live sports scores, and community discussion.

Endpoints

Channel	Endpoint	Server	Auth
Market	wss://api.openfish.me/ws/market	CLOB (3002)	No
User	wss://api.openfish.me/ws/user	CLOB (3002)	Yes
RTDS	wss://api.openfish.me/ws/rtds	CLOB (3002)	No
Sports	wss://api.openfish.me/ws/sports	CLOB (3002)	No
Comments	wss://gamma.openfish.me/ws/comments	Gamma	No

Channel Summary

Market Channel

Live order book deltas and trade data. Subscribe by token asset ID or market condition ID; request initial_dump=true with level 3 when you need a one-time full book snapshot before processing deltas.

Event Type	Description
book	One-time full order book snapshot on initial dump
price_change	Price level added/removed/updated
last_trade_price	Trade execution
best_bid_ask	Best prices changed
tick_size_change	Tick size updated
new_market	New market created
market_resolved	Market outcome determined

User Channel

Private stream of order and trade updates scoped to a specific API key.

Event Type	Description
order	Order placement, partial fill, cancellation
trade	Trade lifecycle (MATCHED, MINED, CONFIRMED, FAILED)

RTDS (Real-Time Data Streaming)

Streaming price feeds for crypto assets. Subscribe by asset symbol.

Event Type	Description
subscribed	Subscription acknowledgment
Price tick	Asset price update

Sports

Live game scores and status updates. Subscribe by game ID.

Event Type	Description
subscribed	Subscription acknowledgment
Score update	Game score, period, status

Comments

Real-time comment feed for events and markets. Subscribe by entity type and ID.

Event Type	Description
subscribed	Subscription acknowledgment
Comment	New comment posted

Connection Lifecycle

All five WebSocket endpoints share the same lifecycle pattern:

1. Connect — Open a WebSocket connection to the endpoint.
2. Subscribe — Send a JSON subscription message with your channel and filter criteria.
3. Receive — The server pushes events that match your subscription.
4. Heartbeat — Reply to periodic keep-alive messages to hold the connection open.
5. Disconnect — Close the connection when finished.

Heartbeat Protocol

Every Openfish WebSocket endpoint uses a text-based PING/PONG protocol with a 10-second interval. The server sends a text message "PING" and expects the client to reply with a text message "PONG".

Note: These are text messages, not WebSocket-level ping/pong frames. Your client must explicitly send "PONG" when it receives a "PING" text message.

If no PONG arrives within the timeout window, the server terminates the connection.

Rust SDK Example

use openfish_client_sdk::ws::{MarketSocket, UserSocket, RtdsSocket, SportsSocket, CommentSocket};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Market channel -- no auth
    let mut market_ws = MarketSocket::connect("wss://api.openfish.me/ws/market").await?;
    market_ws.subscribe(&["71321045679252212594626385532706912750332728571942532289631379312455583992563"]).await?;

    // User channel -- requires API key as query param
    let mut user_ws = UserSocket::connect(
        "wss://api.openfish.me/ws/user?token=your-api-key"
    ).await?;

    // RTDS channel
    let mut rtds_ws = RtdsSocket::connect("wss://api.openfish.me/ws/rtds").await?;
    rtds_ws.subscribe_assets(&["BTC", "ETH"]).await?;

    // Sports channel
    let mut sports_ws = SportsSocket::connect("wss://api.openfish.me/ws/sports").await?;
    sports_ws.subscribe_games(&["game-123"]).await?;

    // Comments channel (gamma server)
    let mut comment_ws = CommentSocket::connect("wss://gamma.openfish.me/ws/comments").await?;
    comment_ws.subscribe("market", "abc123").await?;

    // Process events from any channel...
    while let Some(event) = market_ws.next().await {
        println!("{:?}", event);
    }

    Ok(())
}

Error Handling

Symptom	Cause	Fix
Connection closes immediately	No subscription message sent after connecting	Send a valid subscription message right away
Connection drops after ~10 seconds	Missing heartbeat responses	Ensure PONG frames are sent
No messages received	Invalid token IDs or inactive markets	Verify IDs and check market status
{"error": "invalid token"} on user WS	Invalid API key	Check your API key UUID

Next Steps

• Market Channel — Order book and trade events.
• User Channel — Authenticated order and trade updates.
• RTDS — Real-time asset price streaming.
• Sports — Live game scores.
• Comments — Real-time comment feed.