REST API Endpoints

Complete reference for the Slotty Labs REST API.

Servers

Environment	Base URL
Production	https://api.slottylabs.com
Staging	https://staging-api.slottylabs.com
Sandbox	https://sandbox-api.slottylabs.com

Authentication

All requests must include a Bearer JWT token in the Authorization header:

Authorization: Bearer <api_key_or_session_token>

Additionally, operator API calls require HMAC signature headers:

X-Slotty-Timestamp: <unix seconds>
X-Slotty-Signature: sha256=<HMAC-SHA256>

See Authentication for details.

Rate Limits

By Scope

Scope	Limit
Per API key	1,000 req/min
Per player	100 req/min
Per IP	500 req/min

By Plan Tier

Tier	API Key Limit	Player Limit	Burst
Starter	500 req/min	50 req/min	2× for 10s
Growth	1,000 req/min	100 req/min	3× for 10s
Enterprise	5,000 req/min	500 req/min	5× for 30s

Rate Limit Headers

Every response includes rate limit headers:

Header	Description
X-RateLimit-Limit	Maximum requests per window
X-RateLimit-Remaining	Remaining requests in current window
X-RateLimit-Reset	Unix timestamp when the window resets
Retry-After	Seconds to wait (only on 429 responses)

---

Endpoints

Health

Method	Path	Description
GET	/api/v1/health	Platform health check

Auth / SSO

Method	Path	Description
POST	/api/v1/auth/sso/create-token	Create a single-use SSO launch token
POST	/api/v1/auth/sso/exchange	Exchange launch token for session
POST	/api/v1/auth/refresh	Refresh an access token
POST	/api/v1/auth/logout	Invalidate a session

Games

Method	Path	Description
GET	/api/v1/games	List available games
GET	/api/v1/games/:gameId	Get game details
GET	/api/v1/games/:gameId/config	Get game configuration

Wallet

Method	Path	Description
GET	/api/v1/wallet/balance	Get player balance
POST	/api/v1/wallet/deposit	Initiate a deposit
POST	/api/v1/wallet/withdraw	Initiate a withdrawal
GET	/api/v1/wallet/transactions	List transactions
GET	/api/v1/wallet/deposit-address/:chain	Get deposit address for chain

Sandbox / Testing

Method	Path	Description
POST	/api/v1/test/players	Create a test player
POST	/api/v1/test/players/:id/add-balance	Add test balance
POST	/api/v1/test/players/:id/reset	Reset test player
POST	/api/v1/test/force-outcome	Force a game outcome
GET	/api/v1/test/health	Detailed health check

Game Launch

Method	Path	Description
GET	/launch/:gameId	Launch game (browser redirect)

Admin

Method	Path	Description
GET	/api/v1/admin/tenants/me	Get operator profile
PATCH	/api/v1/admin/tenants/me	Update operator settings
GET	/api/v1/admin/webhooks	List webhook subscriptions
POST	/api/v1/admin/webhooks	Configure webhook endpoint
GET	/api/v1/admin/webhooks/logs	View webhook delivery logs
POST	/api/v1/admin/webhooks/replay/:eventId	Replay a webhook event
GET	/api/v1/admin/players	List players
GET	/api/v1/admin/players/:id	Get player details
POST	/api/v1/admin/players/:id/suspend	Suspend a player
POST	/api/v1/admin/players/:id/unsuspend	Unsuspend a player
GET	/api/v1/admin/rounds	List game rounds
GET	/api/v1/admin/rounds/:id	Get round details
GET	/api/v1/admin/audit-log	Query audit events

---

Response Envelope

All API responses follow a standard envelope format.

Success Response

interface ApiSuccessResponse<T> {
  success: true;
  data: T;
  meta?: {
    page?: number;
    pageSize?: number;
    total?: number;
    hasMore?: boolean;
  };
  requestId: string;
}

Error Response

interface ApiErrorResponse {
  success: false;
  error: {
    code: string;       // e.g. "80001"
    message: string;    // Human-readable description
    details?: Record<string, unknown>;
  };
  requestId: string;
}

Example Success

{
  "success": true,
  "data": {
    "launchToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresAt": "2026-01-15T10:30:30.000Z"
  },
  "requestId": "req_abc123def456"
}

Example Error

{
  "success": false,
  "error": {
    "code": "80001",
    "message": "Invalid API key",
    "details": {
      "hint": "Ensure you are using the correct environment key (sandbox vs production)"
    }
  },
  "requestId": "req_xyz789ghi012"
}

Idempotency

For financial operations (deposits, withdrawals, bets), include an idempotency key:

Idempotency-Key: <unique-string>

• Must be a unique string per operation (UUID recommended)
• Idempotency keys are valid for 24 hours
• Duplicate requests with the same key return the original response
• Required for: POST /wallet/deposit, POST /wallet/withdraw

const response = await fetch('https://api.slottylabs.com/api/v1/wallet/withdraw', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_abc123...',
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
    'X-Slotty-Timestamp': timestamp.toString(),
    'X-Slotty-Signature': signature,
  },
  body: JSON.stringify({
    playerId: 'player-123',
    amount: '100.00',
    currency: 'USDT',
    chain: 'ethereum',
    toAddress: '0x1234...',
  }),
});