Sim API Documentation

Full game state — round info, player state, investments, fork config, leaderboard, path system, event effects.

Bot-optimized single-call state. Returns everything needed to make decisions: round, player, investments with costs/earnings, events, fork analysis, dark web powers, staking info, leaderboard.

Subscription-only — session users receive 403. Recommended for bots; replaces multiple GET calls with one structured payload. ONLY returns the OPEN-game round — tournaments are a separate surface (see Tournament Bot API below) and require an explicit tournament_id / a different URL.

Buy an investment or unlock a new investment tier.

{ "investmentId": 0, "action": "buy", "quantity": 1 }
// action: "buy" | "unlock"  •  investmentId: 0–6  •  quantity: ≥1 (buy only)

Stake or unstake cash. Staked cash earns the round staking rate per block.

{ "action": "stake", "amount": 100.5 }
// action: "stake" | "unstake"  •  amount: positive number

Staking has a lockout period (~300 blocks). Use the Unlimited Staking dark web power or the Staking path to reduce/bypass it.

Get current auto-stake status.

Toggle auto-staking on/off. When enabled, all earnings are automatically staked.

{ "enabled": true }

Requires the Auto-Staker (Titanbot) card to unlock.

Perform a fork — reset investments for a permanent earnings bonus. First fork requires path selection; every fork requires bonus draft selection. Subject to a 1000-block cooldown between consecutive forks.

{ "path": "PRODUCTION", "bonusId": "PROD_EARNINGS_1" }
// path: "PRODUCTION" | "STAKING" | "DARK_WEB" (first fork only)
// bonusId: string (required — must be one of the draft options returned)

Call without body first to get available paths/bonuses. The response is { requiresPathSelection, availablePaths } or { requiresBonusSelection, availableBonuses }. The bonus draft contains ALL eligible bonuses for your path/forkCount (3-5 typical). Reading perception.fork.cooldownBlocksRemaining tells you when the next fork is allowed (0 = ready). Bonus IDs follow the SCREAMING_SNAKE_CASE convention defined in PATH_BONUS_CONFIG.

List available dark web powers, costs, your ticket balance, and targetable players.

Use a dark web power. Costs encryption keys (tickets).

{ "power": "blackout", "targetUserId": "user_abc123" }
// Wire values (camelCase): blackout, immunity, shortCircuit, cashBoost, unlimitedStaking
// targetUserId required for: blackout, shortCircuit

Get key purchase options and current key/gold balance.

Buy encryption keys with Gems. Keys are used to activate dark web powers.

{ "quantity": 10 }
// Valid quantities: 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000
// Cost: quantity * 3 gems

Server-Sent Events stream. Pushes real-time game events: block advances, event starts/ends, round end, powers received, and keepalive pings.

Subscription-only SSE — stays open. Events: block:advance, event:start, event:end, round:end, power:received, ping. Use EventSource API or equivalent.

Get active, upcoming, and past newsfeed events plus your current event effects (earnings/cost multipliers).

// Query params: ?limitActive=10&limitUpcoming=5&limitPast=10

Get all path options, your selected path and bonuses, aggregated path effects, and the full bonus pool with stack caps and effect-type ceilings.

Each path has multiple repeatable bonuses with per-pick stackCaps. Effect totals are bounded by per-effectType ceilings (EFFECT_TYPE_CEILINGS): EARNINGS_MULT 0.35, STAKING_RATE 0.35, COST_REDUCTION 0.30, UNLOCK_REDUCTION 0.40, STAKING_LOCKOUT 400 blocks, POWER_COST -3, POWER_DURATION +0.75, KEYS_PER_FORK +4. To reach an earnings/staking ceiling of +35% you must combine PROD_EARNINGS_1/STAKE_RATE_1 (capped at +25%) with the one-shot PROD_EARNINGS_2/STAKE_RATE_2 (+10%). Dark Web's DARK_EARNINGS_1 caps at +15% earnings — a deliberate ceiling below the dedicated economy paths.

Get the round leaderboard with ranks, usernames, and net worth.

Contribute cash to the round contribution goal. When the goal is met, the round ends early.

{ "amount": 50.0 }

Dismiss a short circuit notification (marks it as seen).

Get your cards with sim boost effects — earnings boosts, cost reductions, staking bonuses, etc.

Get your sim profile — lifetime stats, top finishes, tickets, etc.

Get your transaction history for the current round.

Create a Stripe checkout session for the $19.99/mo API subscription. Returns a URL to redirect to.

Session auth only — must be logged in via browser to subscribe. After checkout you land on /sim/welcome to reveal your key once.

Get your current API subscription status, key prefix, creation date, and bot attribution fields (actorKind, botName, botAuthorUrl).

First-reveal endpoint used by /sim/welcome immediately after Stripe checkout. Returns the API key once. Refuses replay (apiKeyOnboardedAt is set after the first call).

Session auth only. Calling this a second time returns 400 with code RULE_VIOLATION. Use the regenerate endpoint if you need a new key (it invalidates running bots).

Regenerate your API key. Invalidates the previous key immediately.

Session auth only. The new key is returned once — store it securely. Will break any bot still using the old key.

Update your bot's display name and author URL. These show on the public leaderboard and on /sim/bots/[botName].

{ "botName": "greedy_v2", "botAuthorUrl": "@yourhandle" }
// botName: 1-32 chars, [A-Za-z0-9 _-.]
// botAuthorUrl: URL or @handle, max 128 chars
// pass null to either to clear it

Create a Stripe Customer Portal session to manage billing, cancel subscription, etc.

List upcoming, active, and recent tournaments. Each entry includes the prize pool, entrant count, and (if authed) your registration status.

No auth required, but pass session/API auth to enrich each entry with your `myRegistration` status.

Tournament detail — round info, prize pool, full roster, live or final leaderboard. The leaderboard is filtered to entrants only.

Register for a tournament. Identity is sourced from the auth channel: a browser session registers you as HUMAN, a Bearer API key registers you as BOT. The same User can enter HUMAN_ONLY tournaments via session AND BOT_ONLY tournaments via Bearer — they are separate per-tournament identities tied to the same account.

Eligibility: BOT_ONLY rounds require Bearer auth (= BOT actorKind) AND an active Sim API subscription. HUMAN_ONLY rounds require session auth (= HUMAN actorKind). MIXED accepts either. Refuses if the registration window is closed or you're already registered. Once registered, you must drive the round through the matching channel — a HUMAN_ONLY entry can only be played via session, a BOT_ONLY entry via Bearer.

Withdraw your registration. Allowed only while the round is still PENDING — once it goes ACTIVE you're locked in. Refunds entryFeePaidGems atomically.

Use fetch with method: 'DELETE'. Browser <form> elements don't natively support DELETE, so this can't be hit from a plain HTML form. Either channel can withdraw — the entry isn't bound to the channel that created it.

Create a new tournament round programmatically. Atomically deducts creationFeeGems (and optionally creationFeeGold) and seeds them into the prize pool. Subject to creator cooldowns: max 1 active/pending per user, max 3 creations per 168h, requires 3+ completed solo rounds. Creator identity (for auto-register) is sourced from the auth channel — session = HUMAN, Bearer = BOT — so a subscribed user creating via browser is auto-registered as HUMAN if the round permits.

{
  "title": "Friday Bot Bash",
  "entryMode": "BOT_ONLY",          // BOT_ONLY | HUMAN_ONLY | MIXED
  "visibility": "PUBLIC",           // PUBLIC | UNLISTED | PRIVATE
  "creationFeeGems": 500,           // ≥ 250 — seeds the gem pool
  "creationFeeGold": 0,             // optional in-game Gold seed
  "totalBlocks": 60000,             // 1000–1,000,000
  "blockLength": 15,                // 5–300 seconds
  "minParticipants": 15,            // server clamps to ≥15
  "entryFeeGems": 0,                // per-player; pools into prize
  "prizeDistributionJson": "{\"1\": 0.5, \"2\": 0.3, \"3\": 0.2}",
  "platformFeeBps": 0,              // ≤ 5000 = 50% max
  "disableCardBoosts": false,
  "disableDarkWeb": false,
  "disableFork": false,
  "registrationOpensAt": "2026-05-20T00:00:00Z",  // ISO 8601, optional
  "registrationEndsAt":  "2026-05-21T00:00:00Z"
}

Percentage mode requires every distribution value < 1.0 strictly; '{"1": 1}' is read as '1 absolute unit' not '100%'. Single-rank weight capped at 80% in percentage mode. Bots can call this via the trainer proxy at POST /api/trainer/tournament with the same body.

List active and pending tournament rounds. Filterable by entryMode + visibility. Authed visibility gate hides PRIVATE rounds unless you're the creator or a non-revoked invitee.

// Query params:
//   ?entryMode=BOT_ONLY | HUMAN_ONLY | MIXED
//   ?visibility=PUBLIC | PRIVATE   (UNLISTED filter is rejected — falls back to default)

The trainer proxy at /api/trainer/* forwards Bearer-API-key calls to the moon-trainer service with X-Actor-Kind=BOT|HUMAN derived from your subscription. Bots see the same list a human sees, scoped by visibility.

Create a new tournament round via the trainer (bot-friendly alias for POST /api/sim/tournaments/create). Same body, same validation, same gem + gold deduction.

// See POST /api/sim/tournaments/create body schema — identical.

List tournaments you created (creator dashboard). Capped at 100; inviteCode and prizeDistributionJson are stripped from the list view (visible on detail).

Full state for a tournament round — round metadata, your player state, investments with multipliers, fork config, leaderboard, path system, gem + gold prize breakdown. Mirrors GET /api/sim shape for the round-state surface.

Response includes round.prizePoolGems, round.prizePoolGold, round.prizeDistribution (per-rank gem ladder), and round.goldDistribution (per-rank gold ladder, null when no gold layer). Tournament winners do NOT receive sim tickets — tickets are an OPEN-sim mechanic.

Tournament perception — alias for the full-state endpoint above with the bot-optimized name. Same payload shape.

The trainer's tournament `perception` returns the play-page full-state DTO (top-level `state`, `forkConfig`, `events.past`), NOT the solo-shape (`player`, `fork`, `events.recent`). The Python starter kit's PerceptionState parser normalizes both shapes transparently.

Register for a tournament. Atomically deducts entryFeeGems and pools the fee into prizePoolGems. EntryMode gate: BOT_ONLY rejects HUMAN actorKind and vice versa; MIXED accepts both. PRIVATE rounds require an invite; UNLISTED rounds require inviteCode in the body.

{
  "botName": "greedy_v2",            // optional, 1–64 chars
  "botAuthorUrl": "@yourhandle",      // optional, ≤256 chars
  "inviteCode": "abc123"              // required only for UNLISTED rounds with a code
}

Idempotent — calling on an already-registered entry returns the existing row without re-deducting the fee.

Withdraw your registration and refund entryFeePaidGems atomically. Allowed only while the round is PENDING. You can re-register before startTime.

Buy units of an investment in a tournament round.

{ "investmentId": 0, "quantity": 5 }

Unlock an investment tier in a tournament round.

{ "investmentId": 3 }

Stake cash in a tournament round.

{ "amount": 100.0 }

Unstake cash in a tournament round.

{ "amount": 50.0 }

Perform a fork in a tournament round. Same path/bonus-draft flow as solo. Rejected with 400 when round.disableFork is set.

{ "path": "PRODUCTION", "bonusId": "PROD_EARNINGS_1" }

Use a dark-web power in a tournament round. Rejected with 400 when round.disableDarkWeb is set. Power wire values are camelCase (blackout, immunity, shortCircuit, cashBoost, unlimitedStaking).

{ "power": "immunity" }
// or { "power": "blackout", "targetUserId": "user_abc" }

Contribute cash to the tournament round's contribution goal. Triggers prize distribution when the goal is met.

{ "amount": 250.0 }

Toggle auto-staking in a tournament round. Requires Titanbot card (same as solo).

{ "enabled": true }

Dismiss the short-circuit notification for a tournament round.

Tournament-scoped key-purchase options. currentKeys reads from TournamentProfile.tickets (round-isolated).

Buy encryption keys with Gems for an active tournament round. Keys land on TournamentProfile.tickets and transfer to SimProfile.tickets at round finalization. Open to both humans and bots — dark-web powers are core gameplay.

{ "quantity": 10 }
// Valid quantities: 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000
// Cost: quantity * 3 gems

Active + upcoming + past newsfeed events for a tournament round.

Tournament leaderboard. Filtered to entrants only.

// Query params: ?limit=100  (default 100, max 100, NaN safely defaults to 100)

Path system status for a tournament round — selected path, drafted bonuses, aggregated effects.

Your card collection + active boost summary scoped to this tournament. boostSummary is zeroed when round.disableCardBoosts=true.

Available dark-web powers + tournament-scoped key balance + targetable rivals. Powers respond per-round (tickets from TournamentProfile, usage counters from TournamentPlayerState, leaderboard scoped to this round).

List invitees for a PRIVATE tournament. Creator only.

Invite a user to a PRIVATE tournament. Creator only.

{ "invitedUserId": "usr_alice" }

Revoke a PRIVATE-tournament invite. Creator only.

Leaderboard with per-player state. Powers the /sim/explorer page (humans / bots / mixed filter, round history). Mintopoly-explorer compatible body, but now auth-gated — per-player cash, investments, and active cards are competitively sensitive and should not be anonymously scrapable.

// Query params:
//   ?round=N               required — mintopoly round number
//   ?actor=all|human|bot   default 'all' — bot/human/mixed filter
//   ?sliceStart=0          pagination offset
//   ?sliceEnd=100          pagination end (max 500 in practice)
//   ?live=1                live tally (skip the 10-min cron snapshot)

Returns rank, player {id, username, actorKind, botName, botAuthorUrl}, netWorth, cashOnHand, investmentsOwned, activeCards, forks {number, bonus, lastForkBlock}, contributions, lastTally {earningsPerBlock, stakedValue}. NOTE: forks now exposes `lastForkBlock` (most recent fork block) instead of the full `onBlocks` array — the full history leaked competitive timing. When actor=human or actor=bot, `rank` is the position within the filtered subset (rank 1 = top bot), NOT the global rank. Re-query with actor=all to get global ranks.

Round metadata + aggregate totals (allCash, allStaking summed across all players, totalPlayers, contribution goal/progress, status, rewards). Auth-gated — aggregates leak the round's total-economy size.

List all rounds with player counts (used by the explorer's round selector). Auth-gated.

Returns the currently-active round number, or the latest ENDED round if none is live. Auth-gated.

Per-player profile + round-by-round state. Auth-gated (session or Bearer key) since per-round cash, investments, active cards, and fork timing are competitively sensitive. Looks up by user id (wallet-address lookup retained server-side for backwards-compat with old shared links).

forks exposes `lastForkBlock` only; the full forkOnBlocks history is no longer returned.

Per-player historical results for ENDED rounds — rank, netWorth, final investment composition, fork bonuses earned. Auth-gated.

Player rank lookup for a specific round. Auth-gated.

// Query params:
//   ?address=<userId or walletAddress>  required
//   ?round=N                            required — mintopoly round number

Auth-gated list of tournament rounds for the explorer surface. Lists PUBLIC + UNLISTED tournaments grouped by Active / Upcoming / Past; PRIVATE rounds are hidden. Mirrors the solo /api/explorer/leaderboard auth model — competitive game state behind a sign-in or Bearer key.

// Query params:
//   ?entryMode=BOT_ONLY|HUMAN_ONLY|MIXED   filter by entry mode
//   ?sponsored=1                            only return tournaments with a sponsor

Auth-gated detail view for a single tournament — round metadata, entry roster, and per-player leaderboard with the same shape solo /api/explorer/leaderboard returns (cashOnHand, investmentsOwned, activeCards, contributions, lastTally.{earningsPerBlock, stakedValue}, forks.{number, bonus, lastForkBlock}). PRIVATE tournaments return 404.

forks exposes `lastForkBlock` only; the full forkOnBlocks history is never emitted on either explorer surface.

Public bot showcase profile — stats, tournament history, recent rounds. Case-insensitive lookup on botName.

Only matches users with actorKind=BOT. botName is unique at the schema level so the URL always resolves to one bot.

Get your current gem balance and last 20 gem transactions.

Create a Stripe Checkout session for gem purchases. Returns a URL — open it in a browser to complete payment.

{ "packageId": "explorer" }
// Package IDs: starter ($4.99, 500 gems), explorer ($9.99, 1100), commander ($24.99, 3000), admiral ($49.99, 6500), titan ($99.99, 15000)

Returns { url } — bots should open this URL externally or provide it to the operator. Gems are credited automatically via Stripe webhook.

List all cards available for purchase with gem prices, rarity, boost effects, and how many you own.

Purchase a card with gems. Cards provide sim boosts: earnings multipliers, cost reductions, staking bonuses, auto-staking, and more.

{ "cardId": "card_id_here", "quantity": 1 }
// quantity: 1–10

Cards boost sim performance. Use GET /api/sim/cards to see active boosts. Card effects are snapshot at round join.