Secure purchases

The SDK’s purchase bridge — environment pre-flight, PIN mint, and single-shot verification.

Buying an item for real value is the highest-stakes flow in the platform. It is SDK-mediated by design: the SDK owns the environment pre-flight, the bearer authentication, the backend paths, and the response parsing. Your game only provides business data.

Never hand-roll a purchase. Route all purchases through the SDK’s PurchaseClient — the SDK core is the only place that knows the purchase endpoint paths.

The flow

 1.  PurchaseClient.mint_pin_session(MintRequest)
       │
       ├─ environment integrity check ──risks?──▶ blocked (ENV_COMPROMISED reported)
       │                                              PurchasePreflight::Blocked
       │
       └─ POST /api/v1/security/pin-session
               ─▶ PinSession { sessionId, sessionToken, expiresInMs, envLevel }
                            PurchasePreflight::Ready
 2.  Player enters PIN
 3.  PurchaseClient.verify_pin(sessionId, sessionToken, pin, VerifyRequest)
       └─ POST /api/v1/security/pin-session/{id}/verify
               ─▶ PinVerifyOutcome::Valid payload
               ─▶ PinVerifyOutcome::WrongPin { locked, attempts }
               ─▶ PinVerifyOutcome::Failed { code, message }

Mint a PIN session

use musterbox_sdk::purchase::{PurchaseClient, MintRequest};

let client = PurchaseClient::from_session(base_url, session)?;

let request = MintRequest::new("item-arena-bundle", 9.99, "purchase-1");
match client.mint_pin_session(&request)? {
  PurchasePreflight::Ready { session } => { /* show PIN entry */ }
  PurchasePreflight::Blocked { level, risks } => { /* surface block */ }
}

The on-device integrity check classifies risks:

• critical risks (DEVICE_ROOTED, DEBUGGER_ATTACHED) → COMPROMISED,
• any other risk (screen capture, suspicious accessibility, …) → WARN,
• no risks → the raw integrity level (SAFE by default).

Any detected risk blocks the purchase client-side and reports ENV_COMPROMISED to /api/v1/security/events.

Verify the PIN

use musterbox_sdk::purchase::VerifyRequest;

let req = VerifyRequest::new(4.5, wallet_address, "idem-key-1");
match client.verify_pin(&session.session_id, &session.session_token, pin, &req)? {
  PinVerifyOutcome::Valid { payload } => { /* authorized */ }
  PinVerifyOutcome::WrongPin { locked, attempts } => { /* retry or block */ }
  PinVerifyOutcome::Failed { code, message } => { /* session/transport error */ }
}

The amount travels as a decimal string on the wire; always provide a fresh idempotencyKey per authorized withdrawal.

Security events

Best-effort audit logging (backend acknowledges with 202). The SDK reports automatic pre-flight blocks; use it for your own incidents:

let _ = client.report_security_event(
  "SUSPICIOUS_ACTIVITY",
  serde_json::json!({ "detail": "..." }),
)?;

Wallet custody boundary

The SDK never sees, holds, or signs wallet private keys. Custody lives in MusterBox’s MPC custody layer; the player authorizes a withdrawal by PIN, and the custody layer executes it. The destinationAddress your code passes to verify is the single authorization target — validate it carefully.

Next: Security & integrity.