docs/websocket-api.md

ClawSportBot WebSocket API Reference

Connection

wss://stream.clawsportbot.io/v2/live

Authentication

Send authentication immediately after connecting:

{
  "action": "auth",
  "api_key": "YOUR_API_KEY"
}

Response:

{
  "type": "auth_success",
  "tier": "pro",
  "max_subscriptions": 5
}

Subscribing to Channels

Subscribe

{
  "action": "subscribe",
  "channels": ["signals", "consensus", "market_sync"],
  "match_ids": ["epl-2025-arsenal-chelsea"]
}

Available Channels

Channel	Description	Events
signals	Real-time agent signal generation	signal_update
consensus	Consensus formation and updates	consensus_update, consensus_reached, consensus_failed
market_sync	Market synchronization results	market_sync_update
authorization	Signal authorization decisions	signal_authorized, signal_rejected
audit	Post-match audit results	audit_complete
network	Network-wide events	agent_online, agent_offline, network_stats

Unsubscribe

{
  "action": "unsubscribe",
  "channels": ["signals"],
  "match_ids": ["epl-2025-arsenal-chelsea"]
}

Event Messages

All events follow this structure:

{
  "type": "event_type",
  "lifecycle_stage": "stage_name",
  "data": { },
  "timestamp": "2025-03-14T18:15:00Z"
}

Signal Update

Emitted when an agent generates a new signal.

{
  "type": "signal_update",
  "lifecycle_stage": "signal_generation",
  "data": {
    "signal_id": "sig_live001",
    "agent_id": "match-analyst-v3",
    "match_id": "epl-2025-arsenal-chelsea",
    "signal_type": "match_outcome",
    "prediction": {
      "home_win": 0.52,
      "draw": 0.24,
      "away_win": 0.24
    },
    "confidence": 0.78,
    "layer": "cognitive"
  },
  "timestamp": "2025-03-14T18:15:00Z"
}

Consensus Reached

Emitted when multi-agent consensus is achieved.

{
  "type": "consensus_reached",
  "lifecycle_stage": "cross_agent_validation",
  "data": {
    "consensus_id": "con_live001",
    "match_id": "epl-2025-arsenal-chelsea",
    "consensus_score": 0.80,
    "threshold_met": true,
    "weighted_prediction": {
      "home_win": 0.50,
      "draw": 0.26,
      "away_win": 0.24
    }
  },
  "timestamp": "2025-03-14T18:20:00Z"
}

Signal Authorized

Emitted when a signal passes all authorization checks.

{
  "type": "signal_authorized",
  "lifecycle_stage": "execution_authorization",
  "data": {
    "auth_id": "auth_live001",
    "match_id": "epl-2025-arsenal-chelsea",
    "authorized": true,
    "delivery_channels": ["web_app", "telegram", "api"]
  },
  "timestamp": "2025-03-14T18:25:00Z"
}

Connection Limits

Tier	Max Connections	Max Subscriptions
Free	1	1 match
Pro	5	10 matches
Institutional	Unlimited	Unlimited

Heartbeat

The server sends a heartbeat every 30 seconds:

{
  "type": "heartbeat",
  "timestamp": "2025-03-14T18:30:00Z"
}

Clients should respond with:

{
  "action": "pong"
}

If no pong is received within 60 seconds, the connection is closed.

Reconnection

If disconnected:

1. Wait 1 second before reconnecting
2. Double the wait time on each subsequent failure (exponential backoff)
3. Maximum wait time: 30 seconds
4. Re-authenticate and re-subscribe after reconnecting