Developer API Documentation

These APIs are read-only: you can look at Soccerverse data, not change it. There is no API key and no sign-up.

Most apps should start with the Datacentre REST API. Use a /v1 bundle for page-sized reads: one club, player, user or page in a single call. Use /v1/gsp, a JSON-RPC proxy for the game-state processor (GSP), only when a JSON-RPC method has no REST equivalent.

The hosted APIs are on https://play.soccerverse.com (not soccerverse.com), except the MCP server and the datapack, which are on their own hosts.

If you run your own node, see Running your own node.

#APIs and base URLs

Every /datacentre and /v1 route is listed in the machine-readable OpenAPI file.

#Access and authentication

• Read-only. Use GET for REST, /v1 and /events. POST is only used to send read requests: JSON-RPC to /v1/gsp, GraphQL queries and MCP calls.
• No API key. Just send a User-Agent of your own, for example my-app/1.0. Cloudflare rejects the default User-Agent of some libraries with 403 error code: 1010; Python's built-in urllib (Python-urllib/3.x) is the common one. curl, requests, Node fetch, Go, axios and wget work unchanged. For POST requests also send Content-Type: application/json.
• Fair use. Limits are per client IP address. Over a limit you get HTTP 429: wait a moment and try again.
  • /datacentre and /v1 share about 20 requests per second (bursts of 40).
  • /graph allows 5 per second (bursts of 10).
  • /events allows 5 new connections per second (bursts of 10) and 50 open streams.
  • /v1/gsp also refuses (413) a request with more than 100 calls or more than about 256 KiB.
• Browsers. Pages on any website can call /datacentre, /v1 (including /v1/gsp), /graph and the datapack directly. /events and MCP do not allow other websites, so call those from a server.
• No trailing slash. Write /v1/gsp, not /v1/gsp/, and /datacentre/clubs, not /datacentre/clubs/. With a trailing slash, /datacentre, /v1/gsp and /graph requests fail, and other /v1 requests are redirected away from play.soccerverse.com.

#Sample identifiers used throughout

#Money and value scaling

These rules are for /datacentre, /v1 and GSP. The subgraphs use token units instead, each with its own scaling (for example, USD amounts have 6 decimals): see Public subgraphs.

• SVC amounts (balances, wages, values and SVC prices) are whole numbers in units of 1/10,000 SVC. Divide by 10000 to get SVC: 379894315586 is 37,989,431.5586 SVC. This is the same on /datacentre, /v1 and GSP (where balance is an object with available, reserved and total). A few summary fields are already whole SVC, for example SVCTrades7dayVolSVC on /market.
• USDC values that are already decimals. svc2usdc (the USDC price of one SVC, for example 0.0032) and fields such as total_earnings_usdc are ordinary decimal numbers. Do not divide them.
• Shop prices and referral spend are scaled. Shop prices are USDC times 1,000,000: every price on /datacentre/shop/clubs and /v1/shop (pricePerPack, current_price, also inside shares, and pricing[].price). So is usd_spent on the referral leaderboards. Divide by 1000000: 335000 is 0.335 USDC.
• Everything else is a plain number. Ratings, ages, counts, percentages, timestamps and IDs are not scaled. Do not divide them. (One exception: game parameters whose names end in -bp or -bps are basis points — divide by 100 for a percentage.)
• Some MCP tools already return human-readable text such as 37989431.56 SVC. Do not divide those.

#Moved from the old URLs

These APIs used to be served from services.soccerverse.com and graph.soccerverse.com. Those hosts no longer work, and changing only the host name is not enough, because the paths changed too.

#Running your own node

This section is for people who already run their own Soccerverse game-state processor (GSP) node. Everything above is hosted by Soccerverse. A node you run has a bare JSON-RPC interface, and none of the hosted extras exist on it: no /datacentre, /v1, /events or /graph.

• JSON-RPC. If you run the GSP Docker image, it serves JSON-RPC on port 8600 (POST requests). It listens only inside its own container unless you start the node with --nogame_rpc_listen_locally.
• Methods. About 80, including getnullstate and waitforchange, a long poll that returns when the newest block changes. A few are off by default: see the next point. The get_* methods return the same state envelope as the hosted service. The GSP JSON-RPC page lists the methods and explains the envelope.
• Switched off by default. From GSP v1.4.2, --nounsafe_rpc is the default. It switches off the admin calls (such as stop, settargetblock and checkdb) and a few large reads: get_freebench, get_all_users, get_player_ids and get_players with more than 100 ids. They only work if you start the node with --unsafe_rpc, and you should do that only on a private node that nobody else can reach. The hosted service keeps them off too. Older versions have them on by default, so start those with --nounsafe_rpc if anyone else can reach the node. The full list is on the GSP JSON-RPC page.
• REST. The image also serves GET /state (the same summary as getnullstate) and GET /healthz on port 8700, and nothing else.