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://hyperscape-production.up.railway.app

The production API is deployed on Railway. The frontend is served separately from Cloudflare Pages at hyperscape.club.

Authentication

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

curl -H "Authorization: Bearer <your-token>" \
  https://hyperscape-production.up.railway.app/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.club/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

Game Data

GET /api/data/skill-unlocks · endpoint

Get skill unlock definitions for all skills

New in v1.0: Server-authoritative skill unlock data for the Skill Guide Panel.

curl https://api.hyperscape.club/api/data/skill-unlocks

Response

{
  "attack": [
    {
      "level": 1,
      "description": "Bronze weapons, Iron weapons",
      "type": "item"
    },
    {
      "level": 5,
      "description": "Steel weapons",
      "type": "item"
    },
    {
      "level": 40,
      "description": "Rune weapons",
      "type": "item"
    },
    {
      "level": 60,
      "description": "Dragon weapons",
      "type": "item"
    }
  ],
  "woodcutting": [
    {
      "level": 1,
      "description": "Normal trees",
      "type": "item"
    },
    {
      "level": 15,
      "description": "Oak trees",
      "type": "item"
    }
  ],
  "prayer": [
    {
      "level": 1,
      "description": "Thick Skin (+5% Defense)",
      "type": "ability"
    },
    {
      "level": 4,
      "description": "Burst of Strength (+5% Strength)",
      "type": "ability"
    }
  ]
}

Response Fields:

• level (number) - Required skill level
• description (string) - What is unlocked
• type (string) - Unlock category: item, ability, area, quest, or activity

Usage:

• Fetched by Skills Panel on mount
• Cached in client state
• Used by Skill Guide Panel to display unlocks
• No authentication required (public data)

Implementation:

// packages/server/src/startup/routes/data-routes.ts
import { getAllSkillUnlocks } from "@hyperscape/shared";

fastify.get("/api/data/skill-unlocks", async (_req, reply) => {
  const unlocks = getAllSkillUnlocks();
  return reply.send(unlocks);
});

WebSocket Events

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

const ws = new WebSocket('wss://api.hyperscape.club/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
tradeRequest	Request trade with another player
tradeRequestRespond	Accept/decline trade request
tradeAddItem	Add item to trade offer
tradeRemoveItem	Remove item from trade offer
tradeAccept	Accept current trade state
tradeCancel	Cancel trade

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
tradeIncoming	Trade request received
tradeStarted	Trade session started
tradeUpdated	Trade offer changed
tradeConfirmScreen	Move to confirmation screen
tradeCompleted	Trade completed successfully
tradeCancelled	Trade cancelled
tradeError	Trade error occurred

Trading Protocol

Trade Request Flow

Trade Offer Flow

Trade Completion Flow

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