Integrate skill contests.

Building a free-game leaderboard? Read free-game results, custom ranking and replay support before choosing a service.

Your studio defines the game and its rules. The SDK provides pool preparation, entry receipts and settlement primitives.

Rehearse your contest in the portal#

Open Developer Console → Contests & pools. Load a saved plan, adjust price, splits and winner shares, select a quick scenario: Normal round, Pending payment, Rejected score, Tied scores or No scores. Use Run rehearsal to rerun after editing rules. Inspect the proposed prizes and download the report before changing your release.

Playmos · Publisher workspace

Save your contest, then choose Rehearse this contest’s prizes to load its exact saved rules. In the console, use Rehearse prizes, Inspect prize pool and Add to your game to stay in one workspace. The integration helper starts with a read-only series check and preserves paid-entry recovery. After registering your own pool, open Inspect prize pool and use Load my sandbox pools and Read chain state to inspect its series/epoch. Reconcile winner transfers separately.

Prepare your studio’s pool#

Use epochs.preparePool() to obtain an unsigned transaction and the fee sink. Inspect it, sign from your studio wallet, broadcast, then register ownership with the supported wallet proof. Preparation alone neither broadcasts nor proves readiness.

Create a series with epochs.prepareSeries(), sign its returned transaction, and read the series until created=true. Use the actual pool/series configuration for price, split and timer; do not copy shared sandbox values into a studio release.

Choose the right contest path#

Verify paid admission#

Your backend checks a paid entry before admitting a scored attempt. Round-based entries must preserve the exact roundKey and wallet#attemptId identity across pay and admission. Epoch integrations use their returned pool, series and epoch identifiers without translating them into the legacy round path.

import { Playmos } from '@playmos/sdk';
 
export async function enterYourRound(
  playmos: Playmos, gameId: string, roundKey: string,
  wallet: string, attemptId: string, amount: string,
) {
  return playmos.enterRound({
    gameId,
    roundId: roundKey,
    roundKey, // Use the same exact key for server admission.
    identity: `${wallet}#${attemptId}`, // A unique identity for each paid attempt.
    playerId: wallet,
    amount,
    idempotencyKey: attemptId,
  });
}

Your game owns score authority#

Record the score only through your trusted game backend. Existing first-party games keep their deterministic replay validation. Studio integrations need their approved validation model; a browser event cannot settle a contest.

Contest rules and payouts#

Planned policy and reference rules. These defaults do not override a contest’s saved terms or activate settlement. Use the live contest panel and verified receipts for actual results, timing and claims.

You need a registered pool, a created series and a trusted backend that records scores.

• Admit every paid entry, including repeat entries from the same player.
• Rank each player by their best admitted score in the window.
• Compute winners and amounts with your game's prize rules (Playmos's own games use the rules below), then settle.

Check your result: your rehearsal and your settlement both pay the same wallets the same amounts for normal, tied, small and empty windows.

Your studio owns the game and its score authority. Your studio also sets its own contest rules: round length (minimum 10 minutes), payout distribution and prize rules. The prize rules below are the ones Playmos uses on its own games. Show players your game's rules before they enter.

Entries and best score

Each paid attempt is its own entry and one ranked run. Re-entry is supported, and identityEntryCount records the paid count. A player may pay again to retry within the same window, up to your entry limit. Rank players, not attempts: only each player's best admitted run counts toward the leaderboard.

Entry limit. For contests, your studio sets a per-player limit of 1 to 3 entries per window for now. Playmos Labs skill games use 3 by default. Standard games with only in-app purchases have no entry limit.

Give every player in a window the same level, song or puzzle so the result depends on skill.

Prize table (Playmos's own games)

Ties. Tied players split the combined shares of the places they hold, evenly. No random tie-breaks. Rehearse this with the Tied scores scenario in Developer Console → Contests & pools.

Empty windows. When a window ends with a prize pool and no admitted players, the funds roll forward until a later window has a winner. An empty-window roll is a different outcome from a winner payment or a refund. Use the No scores rehearsal scenario.

First window. A series' first window has no incoming seed. Its prize pool comes only from that window's entries. Current pools move seed into carry at entry time, and settlement pays pool + incomingSeed.

No cap on testnet. Internal testnet windows have no prize cap.

Fees

Studio sets the split, Playmos takes 1%.

The default series terms, as shown in Your studio pool, are below. You can change the first three shares when you create a series, and seed can be zero. Playmos's 1% stays fixed.

Read the exact terms from the series you created. Don't copy them from another game.

Automatic payouts

Planned policy: unflagged rounds settle 15 minutes after close. This timing is not a claim about every deployed contest. Once the configured contract settles, settlement is final: a settled window can't be settled again or reversed. On EpochPrizePool, once a window has been closed for 15 minutes (SIGNED_SETTLE_DELAY, a fixed contract constant), anyone can submit your operator-signed result with executeSignedSettlement. Your operator can also settle earlier with settleEpoch.

Settle each completed window from your backend: the operator signs settlementTypedData, then epochs.executeSettlement sends it. Read epochs.get until the window is terminal. Settlement tries to send each prize directly.

Confirm WinnerSent in the canonical receipt and the recipient balance. WinnerCredited means the transfer failed and the amount stays recoverable: the player withdraws with epochs.withdraw. See Payouts & withdrawals.

Held runs

Pay every window automatically. See Anti-Cheat. Planned: a window with a flagged run waits for a person to review it (within 24 hours) before your operator signs the result. Don't sign a held window early, because anyone can submit a signed result 15 minutes after close. Make sure your pool's refund timeout is longer than the review window. Confirmed abuse can lead to sanctions in future rounds. Anti-cheat is in early access and not yet connected to payouts. Reviews will be handled by the studio that publishes the game.

Flagged runs use the flags and review console of the Anti-Cheat module. Planned: review (within 24 hours) happens before results are signed for payout, because a settled round can't be reversed. Player reports and sanctions apply to future rounds.

If it did not work

A rehearsal does not create a pool or transfer prizes. Compare the rehearsal allocation with your settlement amounts for each scenario before paid entry.

Try one variation: rehearse a two-player window with tied scores. Predict each wallet's amount before you run it.

Settle, then expose winnings#

A submitted settlement can still be settling. Read the relevant round or epoch until terminal success. Current epoch pools try to send prizes during settlement. Confirm WinnerSent in a canonical receipt and the recipient balance; WinnerCredited means transfer failed and the amount remains recoverable through withdraw or pushLeftover. Keep sent, credited, withdrawn and refunded amounts distinct. Old contest obligations survive release changes and takedown.

Legacy round operations#

On a supported legacy PrizePool, a secret-key backend uses rounds.open, player enterRound, then rounds.lock and rounds.settle. The payout rule can distribute the prize to one or several ranked wallet addresses. closeAt is advisory; it is not the epoch contract’s hard clock. A public key cannot operate or pay winners.

Keep an explicit, persisted attempt identity on your game path. A no-wallet sandbox entry can instead return a synthetic sandbox#entry_… identity; retain that response and never invent a wallet for a player who did not sign. A sandbox smoke is not a game template or production admission proof.

When settlement returns settling, check the same round’s state rather than blindly submitting another settlement. At settlement, current PrizePool and EpochPrizePool contracts attempt to send each winner’s tokens directly and emit WinnerSent. If a token transfer is refused, they retain that amount in withdrawable and emit WinnerCredited; show a recovery action through payout notices and withdrawals. Verify the canonical receipt and winner event before saying paid. A prize pool balance is not a paid winner.

For optional score verification, read Playmos Anti-Cheat. Explore gameplay checks and fair reviews. Early access integration is still in progress.