Working protocol / Developer notes

Batch the evidence.
Budget every stage.

One API request can read many players. KMCoin uses that to discover submissions and verify public evidence without making a separate request for every account.

Implementation and provider documentation reviewed October 31, 2026. Request estimates use the current defaults and examples with up to 100 friends. Validators may have larger friend lists within the adapter's supported limits; 100 is an example size, not a validator eligibility limit. Discovery, verification and ledger throughput are counted separately.

01 / Who makes requests

Discovery and verification have separate costs.

Producer

Reads its source friend list and proposes a block, normally about once per minute.

Watcher

Reads profile fields in batches and stages changed submissions. An unchanged submission is not continually resubmitted.

Validator

For a winning Phase I proposal, independently checks friends, game presence and valid transaction candidates.

Both verifiers poll local work every second. An empty work queue makes no evidence API call. The verification window is about 29 seconds, so both request volume and response time matter. Transaction authorization is checked against a stable player-state copy before transaction-specific API calls; finalization checks current state again.

Native Steam submissions travel with Steam blocks. Xbox Bio submissions travel with Xbox blocks, including transactions authorized by Steam profiles or Minecraft skins. Admitted candidates survive a losing Phase I proposal in the matching pending pool. A later winner selects pending candidates for verification; overflow stays pending. Failed evidence attempts are consumed and require a newly observed submission change.

Count verification jobs from all producers, not just the local producer. Difficulty reduces expected work but does not prevent several winners arriving together. Each validator makes its own reads. Processes sharing credentials contribute to the same provider budget.

02 / Steam Web API

Up to 100 profiles in one request.

Valve provides the Web API free and states a limit of 100,000 calls per day. Keep the key in the node-local SteamKey.txt, outside source control and browser code; include all helpers and other uses of that key in the budget. See the Steam Web API terms and key registration.

GetFriendList reads the producer collection. GetPlayerSummaries accepts up to 100 SteamIDs and supplies profile and game information. KMCoin batches native transaction evidence at that size; game selection scans batches in deterministic order and stops at the first eligible player. The watcher uses the friend IDs already collected by the producer. See Valve's API reference.

100 friends: one proposal, one watcher scan and one winning verification per minute
Valid transaction candidates per jobRequests per minuteRequests per day
04: produce 1 + watch 1 + verify 25,760
100 distinct identities5: produce 1 + watch 1 + verify 37,200

These examples use 1,440 minutes per day and assume an eligible game is found in the first presence batch. With no transaction candidates, verification reads friends and presence only. Adding 100 valid identities costs one transaction-evidence batch per job, or 1,440 extra calls/day. Each additional validator repeats its verification reads.

Native Steam carries setup and inferred bridge candidates. The number of profiles checked does not change the one-bridge-per-finalized-block rule.

Daily Steam calls = 1,440 x (1 + ceil(friends / 100))
                  + winning jobs/day x (1 + game batches + ceil(candidate identities / 100))

For the 100-friend example, production and watching use 2,880 calls/day. Each winning verification adds two calls without transaction candidates, or three with up to 100 valid candidate identities. Include every validator sharing the key and leave room for other requests and busy intervals.

03 / Direct Xbox services

Batched Bios, with service-specific limits.

The adapter lets a validator sign in with a valid Xbox account on Microsoft's own page and store an API token locally. That token authorizes API lookups; it is not player transaction authorization. KMCoin never asks players to hand over gaming-account passwords. Players publish a valid transaction and the required public evidence, while their wallet secret stays on their device.

The batch profile endpoint returns multiple identities; KMCoin requests Gamertag and Bio. The configured producer XUID selects the friend list to read. API requests use the validator's signed-in account, which may be different. Tokens stay out of blocks, peer data and browser code.

Discover 20 Bios, then move to the next group.

The watcher polls about once per minute and reads at most 20 friends' Bios in one profile request. It persists its place in the ordered list and wraps after the last friend. A failed batch does not advance the scan. With up to 20 friends, every Bio can be checked each poll. With 100 friends, a full scan takes about 5 minutes, plus request delays. This trades discovery speed for a steady profile-request budget.

This basic discovery strategy keeps API usage predictable while eventually checking every friend. A producer may have one friend, fewer than 20, or a larger list. Future implementations could prioritize particular accounts or adjust polling within the API's permitted limits. These choices affect transaction discovery speed, not block-selection or transaction-verification rules.

A larger friends list does not give a validator more mining weight or additional block-production opportunities. It expands the pool of potential player recipients. Eligible friends must still be available for a block to complete verification.

The watcher still refreshes the friend list separately each poll. Production and verification also fetch their own complete lists, with pagination and completeness checks. The rotating Bio scan does not reduce the collection used to build or verify a block.

Current Xbox defaults; friend-list reads assume one complete page
StageRequestsWhen
Produce a proposal1 friend-list requestAbout once per minute
Discover Bio changes1 friend-list + 1 profile batch of up to 20About once per minute
Verify a winner's game activity1 friend-list + presence batches of up to 16Each winning Phase I job; stop at the first eligible friend
Verify candidate Bios0 or 1 profile batchAfter local proof checks; up to 16 candidates per job

Game selection starts at the deterministic position in the full friend list and walks it in groups of 16. An eligible friend in the first group needs one presence request. If none qualifies, the next group is checked, within the original 29-second deadline. For a 100-friend list, checking every friend takes up to 7 presence requests. Selection stops sooner when an eligible friend is found, and all requests must fit within the verification window.

One Xbox verification = friend-list pages
                      + presence batches needed to find a winner
                      + Bio batches for locally valid candidates
                      + Steam / Minecraft evidence, when needed

Budget each service separately.

Microsoft publishes Profile and Social baselines of 10 requests per 15 seconds and 30 per five minutes, counted separately per user and title. HTTP 429 responses carry Retry-After. These are planning baselines, not a measured allowance for this login context. See Xbox rate-limiting documentation.

One rotating watcher uses about 5 profile calls per five minutes, for both the 20-friend and 100-friend examples. One winning job per minute, each with valid transaction candidates, adds another 5: 10 profile calls per five minutes in total. With no transaction candidates, verification adds no Bio calls. An already queued candidate does not wait for another discovery scan before verification.

With one-page friend lists, one producer, one watcher and one winning verification per minute use about 15 Social calls per five minutes. Pagination, more winning jobs and other processes add to those totals. These estimates exclude authentication refreshes and failures.

Presence uses PeopleHub. The published quota for presence.xboxlive.com is not evidence of PeopleHub's allowance. Measure its responses and throttling separately. Reusing one login across machines combines usage in that authentication context; a node's local cooldown does not coordinate other machines.

The current format admits at most 16 transaction candidates per Xbox block. Profile batching defaults to 20, so their distinct relay Bios fit in one request. Smaller configured batches require more verification requests; the watcher still makes only one profile batch per poll and visits fewer friends. Increasing the client batch setting does not raise the watcher's 20-profile cap or the block's 16-candidate cap.

04 / Additional evidence

A Bio can carry a transaction for another platform.

Additional evidence after the batched Xbox Bio check
Wallet identityCurrent extra requestsEvidence
XboxNoneThe ledger-linked XUID owns the Bio containing the full transaction.
Steam1 request per batch of up to 100 distinct SteamIDsThe real-name field matches the first 63 hex characters of the full transaction hash.
Minecraft Java1 session profile + 1 skin download per candidateThe ledger-derived UUID resolves to a skin containing the exact transaction.

The Xbox verifier groups Steam identities only after their local authorization and exact Bio checks pass. With today's 16-candidate cap, all qualifying Steam identities fit in one Steam request, not one request per transaction. Native Steam also batches its own profile reads. Minecraft evidence remains individual session-profile and skin requests.

Invalid local proofs are rejected before these extra reads. Valid candidates can still fail public verification because the profile changed, visibility is restricted, or the request timed out. Keep those failures in request accounting even when no transaction reaches the ledger.

05 / Capacity boundaries

Profiles read are not transactions finalized.

  • Xbox admission allows at most 16 candidates per block, one transaction per sending wallet, and one bridge per finalized block.
  • The general network finalizer also has a 1,000-counted-transaction cutoff and a one-bridge rule. That does not increase Xbox admission limits or establish 1,000 successful transactions per block.
  • Both API verifiers must finish within their job window. Fifty or more sequential requests can exhaust it even if a longer-term quota has room.
  • Block and queue size, transport, duplicate checks, ledger writes and validator agreement must be tested together before raising throughput.

The difficulty schedule controls how proposals qualify for verification. With 15 or 16 proposing validators, each sending once per minute, its idealized average is close to one qualifying proposal per minute across the network. Each validator still verifies that network workload; winners need not arrive evenly.

06 / Operational measurements

Measure the busy interval, not just the daily average.

Record request counts per service and credential context, batch sizes, returned versus requested identities, latency, throttling and Retry-After, completed and expired jobs, and queued candidates. Keep keys, tokens and authorization headers out of logs.

Before increasing limits, test complete large friend lists, full batches, concurrent winners, slow responses and cross-platform evidence across validators. The Xbox client has a shared local cooldown and makes no immediate HTTP retries. A cooldown prevents repeated requests; it does not prove a workload fits the provider budget.

Player tools should use the public player data API for wallet state and honor its polling policy. Those website reads are separate from validator requests to Steam, Xbox and Minecraft.

Adding an API covers canonical identities, transaction evidence and adapter tests. The transaction guide covers player submission steps.