Overview

FoxLeague API 1.0.0

The HTTP API of FoxLeague, the soccer manager game on MultiversX. It is the API the game’s own web app uses; this reference documents the routes a player’s app calls and what each one answers today.

Base URL

All routes are served from https://foxleague.ai. Paths start with /api/ (HTTP) or /ws/ (WebSocket).

Signing in

Routes marked with the session scheme need a session token. To get one:

Take the current Unix time in seconds, ts.
Sign the message foxleague:chain=1:auth-<ts> with the player’s MultiversX wallet, as a signed message (the wallet hashes it with the standard Elrond Signed Message prefix and signs it with the account key).
Send POST /api/auth/verify with {"address": "erd1...", "timestamp": ts, "signature": "<hex>"}. The answer is {"success": true, "data": {"token": "<session token>"}}.
Send Authorization: Bearer <session token> on every session route.

A signature is accepted within 5 minutes of the server clock, once. A route that needs a session answers HTTP 401 with a plain text body when the token is missing, malformed or expired: sign in again. Routes marked with both an empty scheme and session work without a session and answer more to a signed-in caller (for example a player reads their own team in full).

WebSockets

/ws/notifications and the match socket of a ranked or casual match open with a one-use ticket: get it from POST /api/notifications/ws-ticket (a session route) and pass it as ?ticket=<ticket>. A ticket is valid for 30 seconds and for one connection.

Answers

Most routes answer JSON in one envelope:

{"success": true, "data": {}}
{"success": false, "error": "Not registered"}

A refusal is HTTP 200 with success: false and an error in plain words. Always read success.
code is set only where the caller must act differently. tx_pending means a payment was not refused but could not be verified yet: keep the transaction hash and confirm again with the same hash. Never pay twice.
A failure on our side is not a verdict on your request: it answers success: false with a short message, usually "Something went wrong on our side. Please try again in a moment.". Try again later. The route pages list the refusals, not these.
A few routes answer a raw JSON object, a file or a WebSocket; their pages say so.

Times are RFC 3339 in UTC unless a field says Unix seconds. FOXSY amounts are whole tokens unless a field says otherwise. The FOXSY token is FOXSY-5d5f3e.

Limits

Requests are rate limited per client. HTTP 429 means wait and try again. Some routes have their own limits, stated on their page.

Tournament results

A tournament match’s score, statistics and replay appear when its broadcast ends.

Information

License:
OpenAPI version: 3.1.0

Authentication

session

A session token from POST /api/auth/verify, sent as Authorization: Bearer <token>. See the login section of the introduction.

Security scheme type: http

Bearer format: session token