Player tools / API v1

Player data feed

The read-only JSON feed used by the player console and available to downloadable wallets and desktop tools. Look up public player records without downloading the complete ledger or scraping this website’s HTML.

Request up to 20 records

GET /api/player-state?wallet=900001&wallet=900002
GET /api/player-state?player=76561190000000001
GET /api/player-state?player=Your%20Player%20Name

Repeat the wallet or player parameter to batch lookups. Wallet numbers, balances and transaction counters are returned as decimal strings. Keep them as strings or arbitrary-precision integers in your tool.

Respect the polling interval

Read policy.minimumPollSeconds or the X-Poll-Interval header. The default is 60 seconds for up to 5 lookups on a network of up to 1,000 player records. Larger batches or networks use 300 seconds; networks above 10,000 records use 600 seconds. These are initial configurable limits, not a measured capacity guarantee.

Keep the ETag and send it as If-None-Match on the next permitted request. A 304 means the response is unchanged. A 429 means wait for Retry-After. After a 503 or connection failure, back off instead of polling rapidly. Add a small random delay to prevent clients all polling at the same instant.

Read the snapshot, then prepare locally

{
  "version": 1,
  "snapshot": {
    "timestamp": 1790000000000,
    "source": "oracle",
    "totalPlayers": 2,
    "stale": false
  },
  "policy": {
    "minimumPollSeconds": 60,
    "maxPlayersPerRequest": 20
  },
  "players": [
    {
      "query": {
        "by": "wallet",
        "value": "900001"
      },
      "record": {
        "player": "ExamplePlayer",
        "wallet": "900001",
        "balance": "6700000000000000",
        "transactionCount": "0",
        "firstBlockMined": "original first block",
        "publicKey": "64-character public key"
      }
    }
  ]
}

A missing player returns record: null. The snapshot timestamp is when the oracle published that data, not when your tool fetched it. Treat stale or missing data as a reason to pause transaction preparation. No timestamp guarantees that another transaction has not advanced the account since then.

Passwords and private keys remain on the player’s device. This endpoint does not accept transactions, log into gaming accounts, or authorize spending. Every tool must follow the node’s transaction and renewal rules, and verify identity through the appropriate submission path.

Deployment notes

Snapshot indexing is cached and concurrent refreshes are combined. An initial per-IP polling guard runs within each server instance; clients sharing an IP should batch their requests. Before adding replicas or relying on stronger traffic enforcement, move rate limiting to a shared atomic store or trusted gateway. Self-hosted proxies must overwrite untrusted forwarding headers.

Future Steam/Xbox automation will require a separate authenticated client integration. This public feed provides the account data that such a client needs.