Developer Overview

The DegensQuest API is a REST + GraphQL + WebSocket API that powers the Telegram Mini App, app.degensquest.xyz, and third-party integrations.

Property	Value
Base URL	`https://api.degensquest.xyz/api/v1`
Response format	JSON
Versioning	URI-based (`/v1`)
Auth	JWT Bearer token
Rate limit	120 requests per minute per IP (authenticated); 30/min unauthenticated
Status page	`https://status.degensquest.xyz`

Authentication

The API supports two authentication methods:

1. Telegram OAuth (Mini App)

Used by the Telegram Mini App. Pass initData from window.Telegram.WebApp.initData to the /auth/telegram endpoint. Returns a short-lived accessToken (15 minutes) and sets a long-lived refreshToken in an httpOnly cookie.

2. Wallet Auth (SIWE)

Used by app.degensquest.xyz and external integrations. Complete the nonce → SIWE sign → verify flow. Returns the same token format.

All authenticated endpoints require:

Authorization: Bearer <accessToken>

Quick Start (TypeScript)

const API = 'https://api.degensquest.xyz/api/v1';
 
// Step 1: Authenticate with Telegram initData (inside Telegram Mini App)
const authRes = await fetch(`${API}/auth/telegram`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ initData: window.Telegram.WebApp.initData }),
});
const { accessToken } = await authRes.json();
 
// Step 2: Fetch your profile
const profileRes = await fetch(`${API}/users/me`, {
  headers: { Authorization: `Bearer ${accessToken}` },
});
const user = await profileRes.json();
console.log(`Hello ${user.displayName}, level ${user.level}`);
 
// Step 3: Check economy balance
const balanceRes = await fetch(`${API}/economy/balance`, {
  headers: { Authorization: `Bearer ${accessToken}` },
});
const { degen, qbot } = await balanceRes.json();
console.log(`$DEGEN: ${degen} | QUEST: ${qbot}`);

Token Refresh

Access tokens expire after 15 minutes. Refresh silently using the httpOnly cookie:

const refreshRes = await fetch(`${API}/auth/refresh`, {
  method: 'POST',
  credentials: 'include', // sends the httpOnly refresh cookie
});
const { accessToken } = await refreshRes.json();

Resource Groups

Group	Description	Auth Required
`/auth`	Login, SIWE, refresh, logout	No (to obtain token)
`/users`	Profiles, stats, achievements	Partial (public profiles are open)
`/guilds`	Guild list, detail, members	No (read); Yes (write)
`/games`	Active games, history, leaderboards	No (read)
`/economy`	Balance, $DEGEN ledger, QUEST data	Yes
`/quests`	Active quests, progress, completions	No (list); Yes (progress)
`/leaderboards`	Global, guild, and per-game rankings	No
`/marketplace`	Listings, bids, purchases, NFTs	Yes
`/notifications`	User notification stream	Yes
`/admin`	Admin-only endpoints (RBAC protected)	Yes + admin role

Full endpoint documentation: API Reference

WebSocket Events

Real-time game events are delivered via WebSocket at:

wss://api.degensquest.xyz/ws

Connecting

const ws = new WebSocket('wss://api.degensquest.xyz/ws');
 
ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'auth',
    token: accessToken,
  }));
};
 
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log(msg.type, msg.payload);
};

Event Types

Event Type	Description
`game.round_start`	A new game round has begun
`game.round_end`	Round ended with scores
`game.player_joined`	A player joined a game lobby
`game.player_left`	A player left or was eliminated
`game.ended`	Game over — final leaderboard
`raid.attack`	A raid attack was registered
`raid.boss_hp`	Updated boss HP bar
`economy.balance_update`	Your $DEGEN balance changed
`quest.completed`	A quest was completed
`notification`	General notification event

Webhooks

Guild integrations can subscribe to webhooks for bot-free automation:

POST /guilds/:slug/webhooks
{
  "url": "https://your-server.example.com/webhook",
  "events": ["game.ended", "raid.boss_hp", "quest.completed"],
  "secret": "your_hmac_secret"
}

Webhook payloads are signed with HMAC-SHA256. Verify with:

const signature = req.headers['x-degensquest-signature'];
const expected = crypto
  .createHmac('sha256', webhookSecret)
  .update(JSON.stringify(req.body))
  .digest('hex');
const valid = crypto.timingSafeEqual(
  Buffer.from(signature),
  Buffer.from(`sha256=${expected}`)
);

TypeScript SDK

A first-party TypeScript SDK is under development:

# Coming soon
npm install @quest/sdk

The SDK will wrap all REST endpoints with typed methods, handle token refresh automatically, and provide typed WebSocket event handlers. Track progress in the DegensQuest GitHub repository.

API Key (Server-to-Server)

For server-side integrations that don’t act as a specific user, request an API key from developers@degensquest.xyz. Server API keys bypass the per-IP rate limit and are not tied to a user session. They have restricted scope (read-only by default) and require HMAC request signing.

Battle Pass API Reference