API Reference

Hyperscape game server API endpoints and WebSocket events

Overview

The Hyperscape server exposes both REST and WebSocket APIs for game interactions.

The API is primarily designed for internal use by the game client and ElizaOS agents. Direct API access requires authentication.

Base URL

Production

https://api.hyperscape.lol

http://localhost:5555

Authentication

All authenticated endpoints require a Bearer token in the Authorization header:

curl -H "Authorization: Bearer <your-token>" \
  https://api.hyperscape.lol/api/v1/player

Authorization · string · required

Bearer token obtained from Privy authentication

Endpoints

Health Check

GET /health · endpoint

Returns server health status

curl https://api.hyperscape.lol/health

Response

{
  "status": "ok",
  "timestamp": "2025-01-05T12:00:00Z",
  "version": "1.0.0"
}

Player

GET /api/v1/player · endpoint

Get current player information

POST /api/v1/player · endpoint

Create or update player

World State

GET /api/v1/world · endpoint

Get current world state snapshot

GET /api/v1/world/areas · endpoint

List all world areas

Admin Endpoints

Admin endpoints require the x-admin-code header with a valid admin code. These are for server management only.

POST /admin/graceful-restart · endpoint

Request server restart after current duel ends (zero-downtime deployment)

curl -X POST https://api.hyperscape.lol/admin/graceful-restart \
  -H "x-admin-code: YOUR_ADMIN_CODE"

Response

{
  "success": true,
  "message": "Graceful restart requested",
  "duelActive": true,
  "willRestartAfterDuel": true
}

GET /admin/restart-status · endpoint

Check if graceful restart is pending

curl https://api.hyperscape.lol/admin/restart-status \
  -H "x-admin-code: YOUR_ADMIN_CODE"

Response

{
  "restartPending": true,
  "duelActive": true,
  "currentPhase": "FIGHTING"
}

Graceful Restart Behavior:

• If no duel active: restarts immediately via SIGTERM
• If duel in progress: waits until RESOLUTION phase completes
• PM2 automatically restarts the server with new code
• Enables zero-downtime deployments for the duel arena stream

WebSocket Events

Connect to the game server via WebSocket for real-time updates:

const ws = new WebSocket('wss://api.hyperscape.lol/ws');

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

Client → Server Events

Event	Description
player:move	Request player movement to tile
player:action	Perform action (attack, skill, etc.)
player:chat	Send chat message
inventory:use	Use inventory item
bank:deposit	Deposit item to bank
bank:withdraw	Withdraw item from bank

Server → Client Events

Event	Description
world:update	World state delta update
player:sync	Full player state sync
combat:hit	Combat hit event
skill:xp	Skill XP gained
chat:message	Chat message received

Rate Limits

API rate limits apply to prevent abuse. Exceeding limits will result in temporary blocks.

Endpoint Type	Limit
REST API	100 requests/minute
WebSocket messages	60 messages/second
Authentication	10 attempts/minute

Error Codes

400 Bad Request

Invalid request parameters or malformed JSON

401 Unauthorized

Missing or invalid authentication token

403 Forbidden

Insufficient permissions for the requested action

404 Not Found

Resource does not exist

429 Too Many Requests

Rate limit exceeded

500 Internal Server Error

Server-side error, please report to Discord

SDKs & Libraries

JavaScript SDK

Official JavaScript/TypeScript client

ElizaOS Plugin

AI agent integration plugin

Need Help?

Discord Community

Get help from the community

GitHub Issues

Report bugs or request features