WebSocket API

Real-time event streaming for room, contract, and storage updates

Service API Documentation

Explore the REST API documentation for all Arcade microservices:

Players

Player profiles and accounts

Solana smart contracts

Connection

WebSocket URL

wss://socket.dev.arcade.fyi?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.arcade.fyi?token=${token}`);

ws.onopen = () => {
  console.log('Connected to Arcade 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" | "room: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 room for targeted events
`unsubscribe`	Unsubscribe from a 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",
    "roomId": "ABC123",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "payload": {
      // Full Contract object
    }
  }
}

Room Events

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

room.created

New room created

room.joined

Player joined the room

room.left

Player left the room

room.deleted

Room deleted (last player left)

Room Event Payload

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

Storage Events

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

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": "...",
    "roomId": "...",
    "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"
  }
}