API Documentation

All API endpoints are available under /api/v1. Responses are JSON. Time values are always in integer seconds.

An interactive API explorer is also available at /docs (Swagger UI).

Authentication

Most endpoints require a session cookie obtained by logging in. The session cookie is set automatically on register/login.

POST /api/v1/auth/register

Create a new account. Requires the WatermelonSyndicate registration token.

POST /api/v1/auth/register
Content-Type: application/json

{
  "username": "@you:matrix.org",
  "password": "yourpassword",
  "registration_token": "WatermelonSyndicate"
}

POST /api/v1/auth/login

POST /api/v1/auth/login
Content-Type: application/json

{ "username": "@you:matrix.org", "password": "yourpassword" }

POST /api/v1/auth/logout

Clears the session cookie. Requires authentication.

Users

GET /api/v1/users/me

Returns the current user's info and balances. Requires auth.

GET /api/v1/users

List all users. Requires auth.

GET /api/v1/users/{username}

Get a single user's info.

Bank Operations

All bank operations require authentication.

POST /api/v1/bank/transfer

Transfer limbus time to another user.

{ "recipient_username": "@them:matrix.org", "amount": 86400 }

POST /api/v1/bank/charge-purgatory

Spend your limbus time to add purgatory time to another user (1:1).

{ "target_username": "@them:matrix.org", "amount": 3600 }

POST /api/v1/bank/pay-purgatory

Spend your limbus time to reduce your own purgatory balance (1:1). Cannot reduce below 0.

{ "amount": 3600 }

Transactions

GET /api/v1/transactions?limit=100&offset=0

Returns all transactions, newest first. No auth required.

GET /api/v1/leaderboard/purgatory

Top 50 users by purgatory balance.

GET /api/v1/leaderboard/limbus

Top 50 users by limbus balance.

Betting System

POST /api/v1/events (requires EVENT_CREATE_TOKEN)

Create a new betting event. Requires the Authorization: Bearer <EVENT_CREATE_TOKEN> header. Returns the event including a unique resolution_token — store it safely, it cannot be retrieved again.

POST /api/v1/events
Authorization: Bearer <EVENT_CREATE_TOKEN>
Content-Type: application/json

{ "title": "Will Josh win the Minecraft Championship?" }

Response includes resolution_token — required to resolve the event.

GET /api/v1/events?status=open

List events. Optional status filter: open, resolved_yes, resolved_no, cancelled.

GET /api/v1/events/{id}

Get event details including total yes/no bets and % likelihood.

POST /api/v1/events/{id}/resolve

Resolve an event and trigger payouts. Uses the resolution_token from event creation. Winners receive their proportional share of the entire pot.

POST /api/v1/events/1/resolve
Content-Type: application/json

{ "resolution_token": "<token-from-creation>", "answer": true }

answer: true = Yes wins. answer: false = No wins.

POST /api/v1/events/{id}/cancel (requires EVENT_CREATE_TOKEN)

Cancel an open event and refund all bettors.

POST /api/v1/events/{id}/bets

Place a bet. Requires authentication. Limbus balance is deducted immediately.

{ "side": "yes", "amount": 3600 }

GET /api/v1/events/{id}/bets

List all bets on an event.

Time Reference