Developer API Documentation
Reference documentation for the Soccerverse public APIs — Datacentre REST, GSP JSON-RPC, GraphQL subgraphs, the MCP server and datapack assets.
The Soccerverse public APIs are read-oriented and split across a few families. This overview lists each one, its base URL, and the conventions that are shared across all of them.
Scope
| Page | What it covers | Base URL |
|---|---|---|
| Datacentre REST API | Read endpoints for clubs, players, users, market, fixtures, transfers, news, votes, leaderboards and shop data. | https://services.soccerverse.com/api |
| GSP JSON-RPC | Game-state read methods and the state-envelope semantics. | https://services.soccerverse.com/gsp/ |
| Public subgraphs | GraphQL subgraphs for SVC/Democrit trading, Xaya chain stats, and shop, referral and pricing data. | https://graph.soccerverse.com/* |
| Soccerverse MCP | The MCP tool catalogue and the public Streamable HTTP endpoint. | https://mcp.soccerverse.io/mcp |
| Datapack & assets | Datapack JSON structure, the customization and share flow, asset URL rules and cache behaviour. | https://downloads.soccerverse.com/svpack/packv2/default.json |
Base URLs
| API family | Base URL | Protocol |
|---|---|---|
| Datacentre REST API | https://services.soccerverse.com/api | HTTP GET endpoints. |
| GSP JSON-RPC | https://services.soccerverse.com/gsp/ | HTTP POST, JSON-RPC 2.0, with the Soccerverse state envelope wrapping successful results. |
| Democrit/SVC subgraph | https://graph.soccerverse.com/democrit-sv and https://graph.soccerverse.com/democrit-svt | GraphQL query endpoint. |
| Xaya stats subgraph | https://graph.soccerverse.com/xaya-stats | GraphQL query endpoint. |
| Soccerverse shop/referrals/pricing subgraph | https://graph.soccerverse.com/sv-subgraph | GraphQL query endpoint. |
| Soccerverse MCP | https://mcp.soccerverse.io/mcp | Public Streamable HTTP MCP endpoint backed by REST, GSP and GraphQL handlers. Local deployments expose the same path, e.g. http://localhost:8928/mcp. |
| Datapack/default assets | https://downloads.soccerverse.com/svpack/packv2/default.json plus pack-provided asset bases | Static JSON/assets that map IDs to names, colours and image URLs. |
Access and authentication
- The documented endpoints are read-only: HTTP
GETfor the Datacentre REST API, and read methods for GSP JSON-RPC. - Some public services sit behind Cloudflare and may require a bypass header from automated clients. Use an environment placeholder such as
$CLOUDFLARE_BYPASS_SECRET; never hard-code a real secret into code, logs or examples. - Treat the Datacentre REST surface as
GET-only — do not assumePOST,PUTorDELETEsupport unless an endpoint documents it.
Sample identifiers used throughout
| Entity | Sample value | Notes |
|---|---|---|
| Club | club_id=50 | Used for club, market, fixture and shop examples. |
| Player | player_id=1100 | Used for player lookup/history examples. |
| User | username=snailbrain | Used for user/profile and Xaya name examples. |
| Season | season_id=2 or a live-discovered value | Some endpoints need a valid season from live data. |
Money and value scaling
- Datacentre REST and most raw GSP values are integer game units. Divide by
10000to present SVC to a human. - The frontend uses
API_VALUE_DIVISOR = 10000for display conversions. - Some MCP tools already return human-readable SVC; do not divide those values again.