API Reference

Euro Economy API

The backend that powers this site. Every endpoint except /health requires an API key. Amounts are always in cents (€1.00 = 100).

Base URL

http://localhost:3000

Auth header

X-API-Key: your-api-key-here

Health

Check that the backend and database are running.

GET /health

Server + database health check.

None

Authentication

Link a Minecraft account to the site with a temporary 6-digit code and a JWT.

POST /api/auth/generate-code

Generate a 6-digit code (valid 5 minutes).

None

POST /api/auth/verify-code

Verify a code from the mod when a player runs /auth <code>.

None

POST /api/auth/check-code

Poll whether a code has been verified; returns a JWT on success.

None

GET /api/auth/verify-token

Validate a JWT for protected routes.

JWT

Economy

Read and modify player balances. Amounts are in cents (€1.00 = 100).

GET /api/economy/balance/:uuid

Get a player’s balance by UUID (creates them at 0 if new).

API key

POST /api/economy/balance/set

Set an exact balance (admin).

API key

POST /api/economy/balance/add

Add money to a balance.

API key

POST /api/economy/balance/remove

Remove money from a balance.

API key

Transactions

Atomic transfers and transaction history.

POST /api/transaction/pay

Atomic transfer between players and/or organizations.

API key

GET /api/transaction/recent

Recent transactions (limit, offset).

API key

GET /api/transaction/volume

Total transfer volume over a time window (hours).

API key

Market analytics

Aggregate money-supply and holder statistics, recalculated every 60 seconds.

GET /api/market/total-supply

Sum of all player balances.

API key

GET /api/market/market-cap

Market capitalization (alias for total supply).

API key

GET /api/market/top-holders

Richest players (whale tracking).

API key

GET /api/market/stats

Comprehensive market statistics.

API key

GET /api/market/health

Backend + database health.

API key

Marketplace listings

The player-driven marketplace.

POST /api/market/listings

Create a new item listing.

API key

GET /api/market/listings

List active listings (paginated).

API key

PUT /api/market/listings/:id

Update a listing’s price or expiry.

API key

DELETE /api/market/listings/:id

Remove a listing; the item returns to the seller.

API key

Items

Remotely give items to players; queued until they are online.

POST /api/items/give

Give an item (with optional enchantments).

API key

GET /api/items/pending/:username

Pending items for a player (called by the mod).

API key

POST /api/items/mark-delivered

Mark an item as delivered.

API key

Notifications

Queue in-game messages shown when a player joins or checks notifications.

POST /api/notifications/create

Create a notification for a player.

API key

GET /api/notifications/pending/:username

Pending notifications (called by the mod).

API key

POST /api/notifications/mark-delivered

Mark a notification as delivered.

API key

POST /api/notifications/announce

Send a marketplace purchase announcement.

API key

Organizations

Business and District accounts: separate entities with balances, owners and members.

POST /api/business/create

Create a Business account.

API key

GET /api/business/list

List Business accounts.

API key

POST /api/district/create

Create a District account.

API key

GET /api/organizations/user/:uuid

Organizations a user belongs to.

API key

PUT /api/:id

Update an organization’s name or logo.

API key

DELETE /api/:id

Delete an organization.

API key

Admin

Maintenance operations.

POST /api/admin/flush-cache

Clear all in-memory caches.

API key

POST /api/admin/recalculate-supply

Force a market-stats recalculation.

API key

This is a summary. See the full API documentation for request/response bodies, examples and error codes.