Basics
What is the SDK?
A single Rust core (v1.0.0) packaged for Unity, Godot, Unreal, Bevy, Cocos,
Defold, and the browser. It is the recommended client for authentication,
sessions, results, events, and purchases.
Is the SDK the source of truth?
No. The backend owns identity, sessions, results, and wallet custody. The SDK
is a bridge.
Which environments exist?
local (http://localhost:8081), sandbox
(https://sandbox-api.musterbox.dev), staging
(https://staging-api.musterbox.dev), production (https://api.musterbox.com).
Sessions & results
Why does a match not finalize after I submit a result?
Results require both participants’ claims. You likely received
decision: "pending" while awaiting the opponent. Claims are only recorded
when the single-use session token validates to that user + match.
What does the slot in the session context mean?
It is the opponent slot (1 or 2) the player occupies inside the bracket
Match — or null if the player’s participant row could not be mapped.
How long is a session token valid?
10 minutes (SDK_SESSION_TTL_MS). It is single-use and consumed on result
submission.
Authentication
Do I handle tokens?
No. The SDK stores, rotates, and revokes them. Never verify JWT signatures
client-side.
What happens if the backend answers requiresOTP?
The SDK surfaces an AuthenticationFailed error; OTP verification is not yet
supported in the client runtime.
Purchases
Can I call the purchase endpoints directly?
No — purchases are SDK-mediated only. The SDK owns the paths, auth, and the
environment pre-flight. Hand-rolling bypasses the trust model.
What if a player’s device is compromised?
check_environment_integrity detects it; purchase pre-flight blocks with
PurchasePreflight::Blocked, and an ENV_COMPROMISED event is reported. No
request is sent.
Should I retry verify_pin?
Never. It is single-shot; failure indicates wrong PIN (rate-limited), expired
session, or transport. See Secure purchases.
Distribution
Where can I install from?
Packaged artifacts in dist/ (tarballs/zips per engine). npm and crates.io
publication are not live yet — vendor and pin the artifact.
How do I confirm my install is intact?
shasum -a 256 -c dist/checksums/SHA256SUMS, then
musterbox sdk version && musterbox sdk smoke-test.
Support
Where do I get help?
See Support. Include a diagnostic bundle
(musterbox diagnostics generate) and the SDK version when filing an issue.Last modified on September 10, 2026
