Crazy8s

← All documentation

Server API reference

Every RPC the platform exposes, and who may call it. Generated from server/nakama/src/rpc/manifest.ts — do not edit this file by hand; run pnpm api:docs instead.

If you are building a game, you almost certainly do not need this page: a game bundle has no network access at all, and a match handler talks to the platform through its dispatcher. See writing the server rules.

This is for building a client — a web front end, a mobile app — against the platform. Start with client integration, which covers authentication, the response envelope, and the socket.

Authorisation policies

Policy Who can call it Count
Public Anyone, signed in or not. 8
Player Any signed-in account. 48
Developer Accounts in the developers group. 8
Operator Accounts in the operators group. 14
Server Nobody with an account. Callable only with the platform's HTTP key. 25

A handler enforces its own policy as its first statement, and a test walks this manifest calling every handler with a session it should reject. An RPC cannot be exposed without a policy, and a policy cannot be declared for something never registered.

Public — 8 RPCs

Nakama still requires a credential on the wire for a call with no session — server-side callers use the HTTP key. Never ship that key in a client.

RPC What it does
GetCatalogueGame One published game's public detail.
GetLobby Who is online, who is in a match, and how many are waiting at each stake of each game.
GetPublicFeatures Which features are on, so the app can hide a button rather than show one that fails.
GetPushPublicKey The public VAPID key a browser needs to create a push subscription.
GetTournamentBoard A tournament leaderboard, tonight's by default or any past evening by date. Public, like the games list it is reached from.
Health Liveness probe. Returns build version and server time.
ListCatalogue Every published game. Browsing does not require an account.
ListTournaments Every game's tournament tonight, with its state and the caller's own standing in each. One call draws the whole screen.

Player — 48 RPCs

Send the player's session token as Authorization: Bearer <token>.

RPC What it does
ApproveWithdrawal Confirm a password and receive an approval for one specific withdrawal. A session token alone cannot move money off the platform.
CancelBankWithdrawal Pull back the caller's own queued withdrawal and refund it, while it is still unapproved and inside the cancel window.no such withdrawalforbidden
ClaimAsyncMatch Pay out a finished correspondence match to the caller. Idempotent — a retry is told it is already paid rather than paying twice.
ClaimQuest Claim a finished quest's reward. Idempotent: a retry is refused rather than paid twice. Rewards are non-monetary by construction.
CreatePracticeMatch Create a free practice match. No stake and no settlement, but a signed-in player like any other RPC.
CreatePrivateMatch Reserve a match and a share code. Costs nothing until someone sits down.
DeletePushSubscription Remove the caller's Web Push subscription.
EnterPool Enter an async pool at a stake tier, taking the entry fee into escrow.
GetAsyncMatch One correspondence match from the caller's own seat, with the opponent's hand hidden by the game's own view. A match the caller is not in reads as not found.
GetBracket One bracket: the draw, who is through, and the caller's own tie if they have one. Names only — a bracket page shows who is in the draw and nothing else about them.
GetMatchStatus Whether a match the caller is seated in is ready to start.
GetMyProfile The caller's identity and platform roles, used to gate documentation.
GetMyReferralCode The caller's shareable referral code, allocating one if absent.
GetMyReferralStatus Whether the caller was referred and how long their window has left.
GetPaymentStatus The caller's own deposit or withdrawal. Never anyone else's.
GetPool The caller's view of a pool they entered. Never another entrant's run.
GetPoolStandings The standings inside one pool the caller is in — every entrant's position and score, provisional until the server has scored every run. Never an input log.
GetPrivateMatch The host's view of their own invitation. Readable only by the host.
GetReferralSummary Total commission the caller has earned from referrals.
GetRetentionProfile The caller's own standing: league, trophies, level, streak and quest progress. Read-only, and moves no money.
GetStorefront What the caller should see on one storefront surface, with level gating and frequency caps applied. Counts the visit, because a cap a client can decline to report is not a cap.
GetWalletBalance The caller's wallet balance in minor units.
GetWalletHistory A page of the caller's ledger entries, newest first.
Heartbeat Record that this player is still here, so they count as online.
JoinBracket Take a seat in a single-elimination tournament, escrowing the caller's own stake once. Ties are played as correspondence matches and carry no stake of their own.
JoinMatch Seat the caller in a match at a stake tier, taking their stake into escrow. The only path by which a real-money match begins.
JoinPrivateMatch Take the other seat in a private match, at the stake the invitation set.
JoinTournament Register for tonight's tournament, taking the entry fee into escrow. Refused once the window has opened.
LeaveQueue Leave a match that has not started and return the stake. Refused once the match is under way, where leaving is a forfeit rather than a cancel.
ListMyAsyncMatches Every correspondence match the caller is in, ordered so the ones waiting on them come first. Board states are left out — a list of twenty matches does not render twenty boards.
ListMyBrackets Every tournament the caller has entered, with a draw that has a tie waiting on them first.
ListMyPools Every pool this player has entered, pending and finished, with where they came and what it paid.
ListMyReferrals The people the caller referred, and what each has earned them.
PlayAsyncTurn Make a move in a correspondence match. Turn order is enforced by the platform; an illegal move is corrected rather than punished, and costs neither the turn nor the clock.
RecordDailyVisit Count today towards the caller's streak. Idempotent within a day, so it is safe to call on every app open. Pays trophies, XP or cosmetics — never money.
RegisterAsDeveloper Become a developer. Self-service, and needs only a player account and a name.
ReportDisconnect Record what a client knew about its own disappearance mid-match, so the outcome can be decided from evidence rather than assumed. Settles nothing; no verdict can pay the player who vanished.
RequestBankWithdrawal Request a manual bank payout. Debits immediately.
SavePushSubscription Store the caller's Web Push subscription, replacing any previous one.
SimulateBankWithdrawal Preview a withdrawal: the exact fee, the exact amount that will land, and the most that would currently go through. Moves and writes nothing, so it is safe to call on every keystroke.
StartAsyncMatch Join a waiting correspondence match or open one, escrowing the caller's own stake. Turn-based play with nobody connected — a move now, a reply tomorrow.
StartDeposit Ask the provider to take money from the caller's mobile money account. Credits nothing — the wallet moves only on a confirmed callback.
StartPracticeRun Issue a seed for a free solo run of an asynchronous game. No pool, no stake, no settlement — the async counterpart of CreatePracticeMatch.
StartTournamentMatch Pair the caller with another entrant in an arena tournament, or put them in the waiting room. The match it creates is stake-free.
StartTournamentRun Issue the seed for one of tonight's goes in a solo tournament. Everyone gets the same board for the same attempt number.
StartWithdrawal Debit the caller and ask the provider to pay out, against an approval from ApproveWithdrawal. Refunds in the same call if the provider refuses.
SubmitPoolRun Submit a completed run's input log. Records what the device claimed; never scores it.
SubmitTournamentRun Hand in a finished go for scoring. Records what the device claimed; never scores it — a game pod replays the log and reports.

Developer — 8 RPCs

A developer may only ever act on their own games; the handler enforces that itself.

RPC What it does
GetDeveloperEarnings Developer share, totalled and broken down by game.
GetDeveloperProfile The caller's developer profile and masked payout details.
GetMySubmission One of the caller's submissions.
ListMySubmissions Every game submission belonging to the caller.
SaveBankDetails Update the caller's payout bank details.
SaveDeveloperProfile Update the caller's developer profile.
SaveSubmission Create or update a draft, or send it for review.
WithdrawSubmission Pull a submission back out of review.

Operator — 14 RPCs

Every action is attributed to the operator who took it.

RPC What it does
AdjustPlayerBalance A capped, attributed manual balance correction.
ApproveBankWithdrawal Approve a payout for transfer.
GetDeveloperBankDetails Full bank details for making a payment. Every read is logged.
GetFeatures Every feature switch, its configured default, and what the platform is doing.
GetPlatformOverview The operations dashboard, in one consistent snapshot.
GetPublishedStorefront The published storefront as stored, unresolved. Operator only — it is the whole merchandising config.
GetSubmission One submission with its review history, for the reviewer.
ListBankWithdrawals The manual payout queue.
ListSubmissionQueue The review queue across all developers.
LookupPlayer One player's account, roles, balance and recent ledger.
MarkBankWithdrawalPaid Record that a transfer was made, with its bank reference.
RejectBankWithdrawal Reject a payout and refund the player.
ReviewSubmission Stage, approve, publish or return a submission.
SetFeature Turn one feature on, off, or back to its configured default. Audited.

Server — 25 RPCs

These decide what people are paid, or who holds a role. A client that could reach one could mint operators or confirm payments that never happened.

RPC What it does
ExpireStalePools Return the stakes of pools that never filled. Cron-driven; never callable by a client. The sweep existed and was tested from the start but had no RPC, so nothing could run it.
GetReconciliation Ledger totals that must agree with the provider's statement. Read-only: a control that could adjust what it measures is not one.
GrantRole Add a user to a role group. Cluster access required, not just an account.
ListPendingPushes Web pushes waiting to be sent, with the endpoint and keys to send them. notify-svc's queue; never reachable from a player's session.
ListPendingRuns Runs waiting to be scored, with the seed and the input log. The verifier's queue; never reachable from a player's session.
ListStuckWithdrawals Withdrawals started and never resolved. Every row is a player already debited and still waiting.
ListSystemActions The system audit trail: what was run, by whom, and how it went.
MarkPushSent Report what became of one queued push — delivered, the subscription is dead, or a transient failure to be retried.
MarkRunScored Record that a run has been replayed, so it is not replayed again — whatever the board made of the score.
MomoCallback MTN's callback, forwarded by the receiver on the registered callback host. Treated as a notification: the outcome is read from MTN, never from the body.
PaymentCallback The provider reporting what happened. Decides whether a balance goes up, so it is never reachable from an account.
ReconcileMomoPayments Ask MTN about payments no callback resolved, and settle them. Idempotent.
RecordSystemAction Record a system action in the audit trail. Used for operations run elsewhere.
RecordTournamentScore Write a verified score to tonight's board. Never callable by a client: a client that could write its own score could win.
RefundStuckEscrow Refund escrow whose match never reported a result.
RunSettlement Settle outcomes reported by game pods. Cron-driven; never callable by a client.
RunSystemOperation Run one named system operation — seeding role groups, granting or revoking a role.
ScorePoolEntry Record the server-derived score for one entry, settling the pool once every entry is scored. Decides what players are paid.
SeedRoleGroups Create the developer and operator groups. Idempotent.
SettleTournaments Pay the places for a finished tournament, or refund everybody when the field was too small. Cron-driven; never callable by a client.
SweepAsyncMatches Time out stalled correspondence matches and pay winnings nobody claimed. Cron-driven; never callable by a client.
SweepBrackets Advance running brackets as their ties finish, pay completed ones, and void any that never filled. Cron-driven; never callable by a client.
SweepPresence Delete presence rows past their keep window. Cron-driven; never callable by a client.
SyncFirstPartyGames Replace the first-party games in the registry from config/games.yaml. Never touches a developer's published game.
SyncStorefront Replace the published storefront from config/storefront.yaml. Validated on the way in, so a storefront that would misbehave is refused rather than served. There is deliberately no operator equivalent — an ad-hoc publish would be a second source of truth.

Related