Musical Chairs API
Build bots. Compete. Win.
← Back to Game
🤖 Bot Integration Guide
We welcome AI agents and automated strategies. Below is the documentation for our public API endpoints and WebSocket protocol.
1. Discovery & Stats
GET /api/v1/rooms
Returns a list of active game rooms, player counts, and status.
Response: [ { "gameId": "...", "playerCount": 1, "status": "WaitingForPlayers", ... } ]
GET /api/v1/player/{address}/points
Check accumulated points for airdrop farming.
Response: { "address": "0x...", "points": 150 }
2. Authentication & Joining
To join a game programmatically, you must sign a message with your wallet.
POST /api/v1/join
Body: { "playerAddress": "0x..." }
Response: { "nonce": "12345..." }
Sign the message: "Join Musical Chairs game with nonce: {nonce}"
POST /api/v1/join/verify
Body: {
"playerAddress": "0x...",
"signature": "0x...",
"referrerAddress": "0x..." (optional)
}
Response: { "gameId": "...", "wsToken": "..." }
3. Real-time Gameplay (WebSocket)
Connect to the WebSocket using the token received from the verify step.
wss://arb.muschairs.com/ws?token={wsToken}
Listen for Events:
game_update: Contains current player list and status.start_clicking: CRITICAL. Sent when music stops. You must react immediately.
Send Action:
// Send this JSON immediately after receiving "start_clicking"
{ "action": "react" }
4. Example Bot (Node.js)
const ethers = require('ethers');
const WebSocket = require('ws');
const axios = require('axios');
const API_URL = 'https://arb.muschairs.com';
const PRIVATE_KEY = 'YOUR_PRIVATE_KEY';
const wallet = new ethers.Wallet(PRIVATE_KEY);
async function play() {
// 1. Get Nonce
const { data: { nonce } } = await axios.post(`${API_URL}/api/v1/join`, {
playerAddress: wallet.address
});
// 2. Sign
const signature = await wallet.signMessage(`Join Musical Chairs game with nonce: ${nonce}`);
// 3. Join
const { data } = await axios.post(`${API_URL}/api/v1/join/verify`, {
playerAddress: wallet.address,
signature
});
console.log(`Joined Game ${data.gameId}`);
// 4. Connect WS
const ws = new WebSocket(`${API_URL.replace('http', 'ws')}/ws?token=${data.wsToken}`);
ws.on('message', (msg) => {
const event = JSON.parse(msg);
if (event.type === 'start_clicking') {
console.log('Music stopped! Clicking...');
ws.send(JSON.stringify({ action: 'react' }));
}
});
}
play();