WebSocket

Connect to the 4rho WebSocket for real-time market data and user notifications.

Connection

wss://api.4rho.com/ws

Authentication

Market channels need a key with stream:market; the private user channel needs stream:user (see Channel scopes). Authenticate via one of:

Option 1 (recommended - bots and browsers): streaming ticket + first-message auth

1. Call POST /v1/auth/ws-ticket (scope read:account, over normal HMAC or a logged-in session) to mint a single-use wst_… streaming ticket (valid for 60 seconds).
2. Open the socket, then send the ticket as the first message:

{ "type": "auth", "token": "wst_…" }

The token field also accepts a session JWT. The ticket is consumed atomically and can never be replayed. (An Authorization: Bearer wst_… upgrade header works too, but browsers can't set it - hence the first-message path.) The key's scopes (stream:market / stream:user) are enforced per subscription.

Option 2 (direct-to-origin only): HMAC API key headers on the upgrade

When connecting directly to the origin (not through the production edge - the edge strips these headers on WebSocket upgrade, so this does not work against wss://api.4rho.com/ws in production), you can include the standard HMAC headers on the upgrade request. The signature is computed over GET, the request path /ws, and an empty body, exactly like any other HMAC request (see Authentication):

• X-4RHO-API-KEY
• X-4RHO-SIGNATURE
• X-4RHO-TIMESTAMP
• X-4RHO-PASSPHRASE
• X-4RHO-NONCE

Message Format

All messages are JSON with this envelope:

{
  "channel": "market",
  "type": "trade",
  "market_id": "...",
  "data": { ... },
  "seq": 12345,
  "ts": 1709136000000
}

Subscribing

Send a subscribe message after connecting:

{
  "channel": "subscribe",
  "data": {
    "markets": ["market-id-1", "market-id-2"],
    "user": true
  }
}

markets binds you to those markets' public feeds; user: true binds you to your private feed. Both can appear in one message.

Channel scopes

A subscribe for a channel your key lacks the scope for is rejected with an INSUFFICIENT_SCOPE error frame; the rest of the subscribe still applies. Under the hood these map to the server's internal trade.> / orderbook.> / bbo.> (market) and order.fill.> / order.status.> (user) event subjects - you never address those directly; the subscribe envelope above is the only client surface.

Confirmation

{
  "channel": "system",
  "type": "subscribed",
  "data": {
    "channel": "market",
    "market_id": "market-id-1"
  }
}

Unsubscribing

{
  "channel": "unsubscribe",
  "data": {
    "markets": ["market-id-1"],
    "user": false
  }
}

Market Channel Messages

Trade

Emitted when a trade executes in a subscribed market.

{
  "channel": "market",
  "type": "trade",
  "market_id": "...",
  "data": {
    "market_id": "...",
    "trade_id": "...",
    "price": "0.50",
    "amount": "1000000",
    "side": "BUY",
    "outcome_index": 0,
    "timestamp": 1709136000000
  }
}

Book Delta

Emitted when the order book changes (order placed, cancelled, or filled).

{
  "channel": "market",
  "type": "book_delta",
  "market_id": "...",
  "data": {
    "market_id": "...",
    "action": "add",
    "side": "buy",
    "price": "0.49",
    "quantity": "2000000",
    "outcome_index": 0
  }
}

BBO

Emitted when the best bid or offer changes.

{
  "channel": "market",
  "type": "bbo",
  "market_id": "...",
  "data": {
    "market_id": "...",
    "best_bid": "0.49",
    "best_ask": "0.51",
    "bid_size": "5000000",
    "ask_size": "3000000",
    "outcome_index": 0
  }
}

User Channel Messages

Requires authentication. Subscribe with "user": true.

Fill

Emitted when your order is filled (you are either maker or taker).

{
  "channel": "user",
  "type": "fill",
  "data": {
    "trade_id": "...",
    "order_id": "...",
    "order_hash": "0x...",
    "market_id": "...",
    "side": "BUY",
    "role": "maker",
    "price": "0.50",
    "amount": "1000000",
    "outcome_index": 0,
    "timestamp": 1709136000000
  }
}

Order Status

Emitted when your order's status changes.

{
  "channel": "user",
  "type": "order_status",
  "data": {
    "order_id": "...",
    "order_hash": "0x...",
    "market_id": "...",
    "status": "cancelled",
    "side": "BUY",
    "price": "0.50",
    "remaining": "0",
    "filled_amount": "500000",
    "reason": "user_cancelled",
    "timestamp": 1709136000000
  }
}

Ping/Pong

Send pings to keep the connection alive:

{ "channel": "ping" }

Response:

{
  "channel": "system",
  "type": "pong"
}

The server also sends WebSocket-level pings every 45 seconds. Connections that don't respond with a pong within 60 seconds are closed.

Connection Limits

• Maximum message size: 4 KB
• Send buffer: 256 messages
• Slow consumers will have messages dropped (non-blocking delivery)