Integrate skill contests.

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.

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.