WebSocket API

Real-time event streaming for lobby, contract, bounty, and storage updates

Service API Documentation

Explore the REST API documentation for all Hashi microservices:

Players

Player profiles and accounts

Lobby

Game lobby management

Solana smart contracts

Connection

WebSocket URL

wss://socket.dev.hashi.gg?token=YOUR_JWT_TOKEN

Connect to the WebSocket server using a valid Privy JWT token in the query string. The token is used to authenticate and identify the player.

Connection Example (JavaScript)

const token = 'eyJhbGciOiJS...'; // Privy JWT token
const ws = new WebSocket(`wss://socket.dev.hashi.gg?token=${token}`);

ws.onopen = () => {
  console.log('Connected to Hashi WebSocket');
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log('Received:', message.type, message.data);
};

ws.onclose = () => {
  console.log('Disconnected');
};

Message Format

Server Messages

All messages from the server follow this structure:

{
  "type": "contract:event" | "lobby:event" | "storage:event" | "connected" | "pong" | "error",
  "data": { ... }
}

Client Messages

Clients can send these message types:

Type	Description
`ping`	Keep-alive ping, server responds with `pong`
`subscribe`	Subscribe to a lobby room for targeted events
`unsubscribe`	Unsubscribe from a lobby room

Contract Events

Contract events are broadcast globally to all connected clients. These events track the lifecycle of smart contract interactions.

contract.created

Contract record created in database

contract.initializing

Blockchain transaction submitted

contract.initialized

Transaction confirmed on-chain

contract.deleted

Contract rolled back or deleted

contract.payment_transferred

Player funded their stake

contract.outcome_attested

Player submitted outcome and proof

contract.decision_contested

Player contested mediation decision

contract.mediation_submitted

Mediator submitted decision

contract.admin_decision

Admin made final decision

contract.payout_finalized

Payout completed and distributed

Contract Event Payload

{
  "type": "contract:event",
  "data": {
    "type": "contract.initialized",
    "contractId": "550e8400-e29b-41d4-a716-446655440000",
    "lobbyId": "ABC123",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "payload": {
      // Full Contract object
    }
  }
}

Lobby Events

Lobby events are broadcast to room members only. Players automatically join the room when they're a lobby participant.

lobby.created

New lobby created

lobby.joined

Player joined the lobby

lobby.left

Player left the lobby

lobby.deleted

Lobby deleted (last player left)

Lobby Event Payload

{
  "type": "lobby:event",
  "data": {
    "type": "lobby.joined",
    "lobbyId": "550e8400-e29b-41d4-a716-446655440000",
    "lobbyCode": "ABC123",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "payload": {
      "lobby": { /* Full Lobby object */ },
      "playerId": "...",
      "participantCount": 2
    }
  }
}

Storage Events

Storage events are broadcast to lobby room members for the contract's associated lobby.

storage.external_url_created

External URL stored for a contract

storage.presigned_url_created

Presigned upload URL generated (file not yet uploaded)

storage.multipart_completed

Multipart upload completed

storage.multipart_aborted

Multipart upload aborted

storage.deleted

Storage item deleted

Storage Event Payload

{
  "type": "storage:event",
  "data": {
    "type": "storage.presigned_url_created",
    "storageId": "550e8400-e29b-41d4-a716-446655440000",
    "contractId": "...",
    "lobbyId": "...",
    "playerId": "...",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "payload": {
      "storage": { /* Full Storage object */ }
    }
  }
}

Error Handling

If authentication fails or an error occurs, you'll receive an error message:

{
  "type": "error",
  "data": {
    "message": "Authentication failed",
    "code": "AUTH_ERROR"
  }
}